Getting Started...

Here, we introduce CellPhenoX, an eXplainable machine learning method to identify cell-specific phenotypes that influence clinical outcomes for single-cell data. CellPhenoX integrates robust classification models, explainable AI techniques, and a statistical covariate framework to generate interpretable, cell-specific scores that uncover cell populations associated with a clinical phenotype of interest.

Figure 1. CellPhenoX leverages cell neighborhood co-abundance embeddings, Xi , across samples and clinical variable Y as inputs. By applying an adapted SHAP framework for classification models, CellPhenoX generates Interpretable Scores that quantify the contribution of each feature Xi, along with covariates and interaction term Xi, to the prediction of a clinically relevant phenotype Y. The results are visualized at single-cell level, showcasing Interpretable Scores at low-dimensional space, correlated cell type annotations, and associated marker genes.

You can install pyCellPhenoX from PyPI:

pip install pyCellPhenoX

github (link):

# install pyCellPhenoX directly from github
git clone [email protected]:fanzhanglab/pyCellPhenoX.git

Dependencies/ Requirements

When using pyCellPhenoX please ensure you are using the following dependency versions or requirements

python = "^3.9"
pandas = "^2.2.3"
numpy = "^2.1.1"
xgboost = "^2.0"
numba = ">=0.54"
shap = "^0.46.0"
scikit-learn = "^1.5.2"
matplotlib = "^3.9.2"
statsmodels = "^0.14.3"

Tutorials

Please see the Command-line Reference for details. Additonally, please see Vignettes on the documentation page.

API

pyCellPhenoX has four major functions which are apart of the object:

1. split_data() - Split the data into training, testing, and validation sets
2. model_train_shap_values() - Train the model using nested cross validation strategy and generate shap values for each fold/CV repeat
3. get_shap_values() - Aggregate SHAP values for each sample
4. get_intepretable_score() - Calculate the interpretable score based on SHAP values.

Additional major functions associated with pyCellPhenoX are:

1. marker_discovery() - Identify markers correlated with the discriminatory power of the Interpretable Score.
2. nonNegativeMatrixFactorization() - Perform non Negative Matrix Factorization (NMF)
3. preprocessing() - Prepare the data to be in the correct format for CellPhenoX
4. principleComponentAnalysis() - Perform Principle Component Analysis (PCA)

Each function has uniqure arguments, see our documentation for more information

License

Distributed under the terms of the MIT license, pyCellPhenoX is free and open source software.

Code of Conduct

For more information please see Code of Conduct or Code of Conduct Documentation

Contributing

For more information please see Contributing or Contributing Documentation

Issues

If you encounter any problems, please file an issue along with a detailed description.

Citation

If you have used pyCellPhenoX in your project, please use the citation below:

Young, J., Inamo, J., Caterer, Z., Krishna, R., Zhang, F. CellPhenoX: An eXplainable Cell-specific machine learning method to predict clinical Phenotypes using single-cell multi-omics, bioRxiv 2025.01.24.634132; doi: https://doi.org/10.1101/2025.01.24.634132

Contact

Please contact [email protected] for further questions or protential collaborative opportunities!