Metadata-Version: 2.1
Name: mitoscripts
Version: 1.0.1
Summary: To assist in quantifying mitochondrial morphology
Home-page: https://github.com/granthussey/MitoScripts
Author: Grant Hussey
Author-email: grant.hussey@nyulangone.org
License: UNKNOWN
Description: # MitoScripts
        
        This Python package, **MitoScripts**, assists in quantifies mitochondrial morphology. It was written by me, Grant Hussey, as a rotation project in the Holt Lab at NYU Langone Health's Institute of Molecular Biomedicine. 
        
        This package first requires data to be processed into 3D models by using [MitoGraph](https://github.com/vianamp/MitoGraph), an open-source software developed by [Matheus Viana](https://sites.google.com/site/vianamp/).
        
        This build of MitoScripts works for MitoGraph v3, and was tested on mammilian cells.
        
         ## General Notes and Procedure
        
         MitoGraph is a software that takes z-stack images of mitochondria and produces a 3D model. This Python package, _MitoScripts_, takes the output from MitoGraph and quantifies it.
        
        ### Steps 
        
        <a name="step1"></a>**1. Acquire your data.**
        
        *Be sure to have a consistent naming scheme for these image files that do not repeat, in order to automate the quantification process downstream.*
        
         <a name="step2"></a>**2. Process your data through MitoGraph.**
        
        **3. Run MitoScripts.**
        
        After MitoGraph processing is completed, you get *.gnet* and *.mitograph* files. These are used by MitoScripts to quantify mitochondrial morphology.
        
        First, gather the *.gnet* and *.mitograph* files into a single directory. Next, import the python package, which has three modules, [mitographer](#mtgrapher), [mitodata](#mt), and [mitopca](#mtpca). You will most likely only interface with **mitographer**.
        
        As of now, MitoScripts works best if used in scientific mode in an IDE or a jupyter notebook.
        
        `` import mitodata as mt ``
        
        `` import mitographer as mtgrapher ``
        
        `` import mitopca as mtpca``
        
        **4. Run the analysis of choice.**
        
        &nbsp;
        
        # What MitoScripts Can Do
        
        ##  <a name="mtgrapher"></a> MitoGrapher module
        
        This is the most self-explainatory MitoScripts module. Interface with it to produce automated graphs based on your MitoGraph outputs, *.gnet* and *.mitograph* files.
        
        `create_graph_suite` takes `data_dir`, `data_name`, `name_dict`, and `savefigs`. Produces a scattered box plot graph for a plethora of quantifiable metrics from MitoGraph. This function **returns a Pandas DataFrame** containing the extracted metrics. **Keep this DataFrame for downstream analysis.**
        
        * `data_dir`: the directory of your *.gnet* and *.mitograph* files.
        * `data_name`: a user-defined name unique to the experiment (for example, "20oct19_treatment_with_chemical_x")
        * `name_dict`: a [user-defined dictionary that maps your filenames to their respective labels](#name_dic).
        * `savefigs`: set this to `True` to save figures inside of your current directory.
        
        
        `pca_suite` takes `df`, or the DataFrame returned by `create_graph_suite`, and runs a PCA analysis. It also creates a scree plot and a centroid plot (where the centroid of each cluster is graphed instead of the points). It takes `df`, `to_drop`, and `style`.
        
        * `df`: as explained above
        * `to_drop`: defaults to None. If None, will initialize to the automated output of `get_default_col_to_drop`. This removes 1) redundant metrics and 2) irrevelant metrics. Set to a user-defined list if you want to customize the metrics used by MitoPCA.
        
        * `style`: defaults to "tableau-colorblind10", a Seaborn style, as defined in the global variable `DEFAULT_STYLE`. 
        
        `scatter_length_distribution` takes `data_dir`, `data_name`, `name_dict`, and `savefigs`. Variable definitions are the same as above. This function will create a heatmap that displays the individual distributions of each image to visualize distribution of lengths in each image's greater mitochondrial network.
        
        
         ## <a name="mt"></a>  MitoData module
        
        This is the main backbone of the MitoGrapher module. Of note, there may be one function you'd interface with:
        
        `analyze_images` takes `data_dir`, `name_dict`, and `data_name` and produces the `df` explained above.
        
         ##  <a name="mitopca"></a> MitoPCA module
        
        This module is the backbone of `mitographer.pca_suite`. There is one notable function:
        
        `run_special_pca` uses an algorithm to drop columns producing the most dissimilarity in the data, then displays the resultant data's PCA graph. It takes `df`, `threshold`, `min_cols`.
        
        `threshold` and `min_cols` work in tandem. They define two different conditions that the algorithm will stop. `threshold` defines the max cutoff for PC 1's explained variance ratio, while `min_cols` defines the min number of columns in `df` you wish to keep in the final DataFrame. 
        
        For example, let's say I have a DataFrame with 20 columns. The algorithm will start deleting columns that produce the most dissimiliarity. If deleting a column makes PC1's explanied variance ratio greater than `threshold`, it will stop deleting columns, then run a final PCA.
        
        If `threshold` is not met, then the loop will continue.
        
        Simiarly, the algorithm checks each loop if you've whittled the DataFrame down below `min_cols`. If so, the algorithm will also stop deleting columns and run a final PCA.
        
        &nbsp;
        
        
        # Other Things
        
        ### A longer description on `name_dict`
        
         <a name="name_dic"></a> `name_dict` has key:value pairs as filename:treatment_name. For example, lets say you're treating cells with hydrogen peroxide and seeing if there is a change in mitochondrial morphology. You need to save your images in the form of "control_000", "control_001", "control_nnn" and "h2o2_000", "h2o2_001", "h2o2_nnn", then create a name_dict like so: 
        
        ``
        name_dict = {
            'control':'Control Group',
            'h2o2':'With Hydrogen Peroxide'
        }
        ``
        
        This way, your graphs and variables will be displayed with the nicer headers "Control Group" and "With Hydrogen Peroxide."
        
        ---
        
        ### Extended notes for each step
        
        [For Step 1](#step1): 
        Read the papers on MitoGraph (namely [this one](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6322684/)) to follow best imaging practices for good MitoGraph results. 
        
        [For Step 2](#step2): 
        If you wish to use the normal MitoGraph pipeline, please see [MitoGraph's github repo](https://github.com/vianamp/MitoGraph) for procedure. You may skip to the next step.
        
        Otherwise, if curious, I have provided here my own ImageJ macros based upon those supplied by Matheus that were useful in my pipeline. In order of use: 
        
        *Tiff_and_MaxProfs.ijm*: This macro takes a directory of *.nd2* files, the output of our confocal microscope, and produces a *.tif* image for each file. Next, it take sthe *.tif* files and produces a new z-stack containing max projections of each image. *Use case:* In the MitoGraph pipeline, you need to create such a z-stack to assist in cropping out individual cells from each image.
        
        *CropCells_Complete.ijm*: This macro takes a directory containing the *.tif* files from above, the max projection from above, and an ROISet.zip file containing ROIs for each cell (user-defined) and crops out the ROIs, creating one new *.tif* image per ROI. *Use case:* In my pipeline, I need not only a directory containing each one file per cell ROI, as is used in the normal MitoGraph pipeline, but also a directory of directories where each directory contains a single ROI. This extra "directory of directories" is used on the compute cluster offered at my institution.
        
        *createMontage.ijm*: This macro creates a montage directly comparing the *.png* file output from MitoGraph (which displays the mitochondrial segmentation) to the original *.tif* for manual quality control. *Use case:* Post-MitoGraph processing, use this to see if any catastrophic segmentation errors occured.
        
        ---
        
        **Dependencies**: 'numpy', 'pandas', 'scikit-learn', 'igraph', 'matplotlib', 'seaborn'. Please import these into your environment.
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
