.. _Usage: ============ Script usage ============ Once you have installed the package you can run the script as .. code:: bash imagingtranscriptomics -i path_to_file -n 2 The script has some parameters that can be tuned according to the necessity of the analysis, which can be viewed by calling the help function from the script as :code:`imagingtranscriptomics -h` or :code:`imagingtranscriptomics --help`. Here we will describe in more details all the parameters of the script. The parameters of the script are: ``-i`` (``--input``) Scan on which you want to perform the analysis. It is *recommended* that you provide an absolute path to your scan (e.g., :code:`~/Desktop/myscan.nii.gz`) instead of a relative one (e.g., :code:`myscan.nii.gz`) to avoid errors. The input file *must* be an imaging file in NIfTI format (both :code:`.nii` and :code:`.nii.gz` formats are supported), be in MNI152 space and have a matrix dimension of 182x218x182. If your image has a different matrix size you can reslice it to match this dimension with your preferred method. (A quick method is to use *fslview* and reslice to match the dimension of the included *MNI152_1mm* brain atlas). .. warning:: The input scan must have a predefined dimension **(182x218x182)** and be in **MNI152** space. If the input scan is not in the required dimension the script will throw an error. You should always check the dimension before running the script and eventually reslice or spatially normalise your image to the matching dimensions with your preferred method (e.g., SPM, FSL, ANTS). ``-n`` (``--ncomp``) Number of PLS components to use for the analysis. The parameter *must* be an **integer** between 1 and 15, otherwise an error will occur. *Please note* that in PLS regression the first component is not necessarily the component explaining the most amount of variance, as in PCA. Example: running :code:`imaging-transcriptomics -i path_to_file -n 2` will run the script on your imaging file selecting the two first components for the analysis. ``-v`` (``--variance``) Total amount of variance you want your components to explain. The code will automatically select the number of components that explain at least the variance you specify. The parameter *must* be an **integer** between 10 and 100, which represents the percentage of explained variance. Example: if you run :code:`imaging-transcriptomics -i path_to_file -v 30` and the first 3 components explain 10%, 25% and 3%, respectively, of the total variance the script will use 2 components, even if they explain 35% (which is a bit more than specified) of the total variance. .. warning:: Please note that the **-v** and **-n** parameters are mutually exclusive and only one has to be provided as argument for the script, otherwise an error will occur. ``--corr`` Allows to run the analysis using regression instead of PLS regression. .. note:: If you use the **--corr** option you can avoid specifying all other parameters (e.g., **-v**, **-n**) as the script will ignore them anyway. Optional additional parameters that can be provided are: ``-o`` (``--out``) Path where you want to save the results, if no path is provided the results will be saved in the same path as the input scan. When the code is finished running the results will be saved in a folder named *Imt_myscanname* and will contain all the results (.csv files, .pdf report and images in .png format). If you run the script multiple times you will have more than one results folder with a trailing number for the run (e.g., *Imt_myscanname* for the first run and *Imt_myscanname_1* for the second run). ``--verbose`` Sets the output logging level to debug mode and shows all debug values and steps ``--suppress`` Sets the logging level to warning and will display only eventual warning messages. .. _library: ======================= Usage as python library ======================= Once installed the library can be used like any other Python package in custom written analysis pipelines. To the library can be imported by running: .. code:: python import imaging_transcriptomics as imt Once imported the package will contain the core ``ImagingTranscriptomics`` class, along with other useful functions. To see all the available functions imported in the library run: .. code:: python dir(imt) which will display all the functions and modules imported in the library. ImagingTranscriptomics Class ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``ImagingTranscriptomics`` class is the core class of the entire package and allows you to run the entire analysis on your data. To start using the class the first step is to initialise it. A way to do this is: .. code:: python my_analysis = imt.ImagingTranscriptomics(my_data, n_components=1) The ``my_data`` is an array that contains the data you want to analyse (e.g., the average values from the scan). This vector has to have some characteristics, mainly: * it has to be a ``numpy.array`` with length 41, which corresponds to the number of regions in the left hemisphere of the Desikan-Killiany atlas. * it has to contain the values you want to analyse but not the ``zscore`` of the values as this is computed automatically during the initialisation. Alternatively to initialise the class with the number of desired components, you can initialise the class by specifying the amount of variance that you want the components to explain. The software will then select the number of components that explains *at least* the specyfied amount (e.g., you specify a 60% of variance and one component explains 58% while the first two components combined explain 70%, two componets will be selcted). .. code:: python my_analysis = imt.ImagingTranscriptomics(my_data, var=0.6) # The amount of varinace can be expressed in different ways and gets converted internally. # The following will produce the same results as the above my_analysis = imt.ImagingTranscriptomics(my_data, var=60) Once the class in initialised, you can run the analysis by invoking the ``.run()`` method. .. code:: python my_analysis.run() There are currently two methods to run the analysis, the first uses PLS regression while the other uses Spearman correlation. The PLS analysis is the default method to analyse the data is PLS, while if yoh want to run the analysis with correlation you can run the command: .. code:: python my_analysis.run(method="corr") .. note:: Please be aware that running the correlation method is currently much slower than the PLS method. This is due the number of correlation that have to be ran during the permutation analysis. The code running these analysis is leveraging multiprocessing of the processor, by using as many cores of the CPU as possible, but even doing this times of *20min* are not uncommon. Once the analysis is completed you can check you results by accessing the attributes of the class. Other Functions of Imaging_Transcriptomics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``imaging_transcriptomics`` library contains several helpful functions, like: * ``read_scan``: that allows to read a NIfTI file and returns the data matrix (without any of the header information. * ``extract_average``: that allows to extract the average value from the left hemisphere of the scan.