MMoCHi is a hierarchical classification system designed for CITE-Seq data, but applicable to diverse single-cell sequencing modalities. It includes tools for:
- Integrating data of Antibody Derived Tag (ADT) expression
- High-confidence thresholding of cell populations using ADT expression, gene expression, and cell metadata
- Building a hierarchy of cell subset classifiers
- Training and evaluating random forest classifiers at each hierarchy level
You can read the documentation here!
Daniel P. Caron, William L. Specht, David Chen, Steven B. Wells, Peter A. Szabo, Isaac J. Jensen, Donna L. Farber, Peter A. Sims. "Multimodal hierarchical classification of CITE-seq data delineates immune cell states across lineages and tissues." bioRxiv, 2023 [Open access article]
- Integrated Classification - Set up and run MMoCHi on 10X Genomics CITE-Seq data!
- Input/Output Specifications - A handy reference for expected input formats and the meaning of various outputs.
- Landmark Registration - Improving integration by manually adjusting peak identification.
- Hierarchy Design - Building your own MMoCHi hierarchy object and selecting markers for high-confidence definitions.
- High-Confidence Thresholding - Careful thresholding to improve high-confidence selection and training!
- Exploring Feature Importances - Interpreting random forests: What features are most useful for classification?
- Pretrained Classification - Applying a pretrained classifier to other datasets.
- Hyperparameter Optimization - Automatic hyperparameter optimization of the underlying random forests.
MMoCHi was developed using Python 3.8, but may also work on later Python versions. We recommend isolating installation using a virtual environment. You can create a virtual environment using miniconda or anaconda:
conda create -n mmochi python=3.8
Once you create this enviornment, activate it:
conda activate mmochi
Ensure this environment is activated for all of the following installation steps. For this reason, we recommend running installation in terminal, not through IPython notebooks.
MMoCHi was designed to be run in Jupyter IPython Notebooks. If you already have JupyterLab installed, you can use ipykernel to install your new environment into Jupyter as a separate kernel.
conda install ipykernel
python -m ipykernel install --user --name=mmochi
This environment can now be accessed within Jupyter via the "Kernel>Change kernel..." menu. You may need to restart Jupyter for changes to apply.
ALTERNATIVELY, if you do not have Jupyter preinstalled, you could create a fresh install of JupyterLab within this new conda environment:
conda install -c conda-forge jupyterlab
jupyter lab
Once you have set up the environment, clone this repository and cd into its root directory:
git clone https://github.com/donnafarberlab/mmochi.git
cd mmochi
(Note: The root directory is the one the with README.md in it)
ALTERNATIVELY, you can download the repository as a .zip file, extract it, and navigate to its root directory (which may be named MMoCHi-main).
Most of the dependencies for MMoCHi can be installed via conda:
conda install -c conda-forge --file requirements.txt
While not required, additional dependencies can be installed to enable hierarchy plotting functions (graphviz) and to follow along in our tutorials (harmonypy):
sudo apt-get install graphviz
python -m pip install harmonypy
If you are on an Intel(R) processor, you can also install the following package to accelerate computation:
python -m pip install scikit-learn-intelex
Lastly, while in MMoCHi's root directory, install the package from source. This install also includes dependencies for running landmark registration and for testing your installation with pytest.
python -m pip install ".[landmarking,pytest]"
Testing can help verify a successful install of MMoCHi. While the pytest covers ~90% of the code, it still does not capture many use-cases. Thus, while it catches major dependency issues, it may not detect issues with functions requiring user interaction. Please also run through the tutorials to verify your environment is correct. From MMoCHi's root directory run:
conda activate mmochi
python -m pytest
Although conda usually handles conflicts between dependency versions, issues sometimes still arise. Here, we have also provided a list of set dependencies for Python 3.8. Recreate your environment, set up Jupyter, navigate to MMoCHi's root directory, then install as follows:
conda activate mmochi
python -m pip install -r Python3_8_requirements.txt
python -m pip install .
Contributions to MMoCHi are welcome. Please get in touch if you would like to discuss. To install for development, navigate to MMoCHi's root directory and create an editable install as follows:
python -m pip install -e ".[docs,landmarking,pytest,tutorials]"
In addition to running the testing suite, you can also test tutorial notebooks automatically, check code coverage, and test many python versions and dependency sets:
python -m pytest --nbmake docs/Integrated_Classification.ipynb docs/Landmark_Registration.ipynb docs/Hierarchy_Design.ipynb docs/High_Confidence_Thresholding.ipynb docs/Exploring_Feature_Importances.ipynb docs/Pretrained_Classification.ipynb
python -m pytest --cov=mmochi --cov-report=html
python -m pytest --nbmake docs/*.ipynb --cov=mmochi --cov-report=html --cov-append
python -m tox -r
You can also compile the docs using the following command:
cd docs
make html
There will be many warnings, but it should end with "build succeeded". You can then view the docs by opening docs/_build/html/index.html in your local browser.
Occationally, there are errors running pandoc when installed using pip. Try resinstalling with conda:
pip uninstall pandoc
conda install -c conda-forge pandoc
cd docs
make html