Installation guide

Pre-requisites

Python >= 3.12

Note

We recommend creating a separate environment such as Mamba to avoid package conflicts.

Installing Phenoverse

Install Phenoverse via pip:

pip install Phenoverse

Verifying installation

To check the Phenoverse installation, please run:

phenoverse --help

You should see an output like this:


+----------------------------------------------------------------------------+
| Thank you for using Phenoverse, an interpretable deep learning tool for    |
| learning sample representations and characterizing disease states in       |
| single-cell transcriptomics : )                                            |
|                                                                            |
| Documentation: https://kellislab.github.io/Phenoverse/                     |
| Issues: https://github.com/KellisLab/Phenoverse/issues                     |
+----------------------------------------------------------------------------+

usage: Phenoverse [-h] [--seed SEED] [--gpu GPU] [--train TRAIN] [--test TEST]
                  [--phenotypelabel PHENOTYPELABEL] [--samplecol SAMPLECOL]
                  [--celltypecol CELLTYPECOL] [--checkpoint CHECKPOINT]
                  [--output_dir OUTPUT_DIR] [--embedding_dim EMBEDDING_DIM]
                  [--token_dim TOKEN_DIM] [--num_prototypes NUM_PROTOTYPES]
                  [--encoder_hidden_dim ENCODER_HIDDEN_DIM]
                  [--encoder_blocks ENCODER_BLOCKS] [--n_heads N_HEADS]
                  [--n_latents N_LATENTS] [--dropout DROPOUT]
                  [--batch_size BATCH_SIZE] [--test_size TEST_SIZE]
                  [--max_epochs MAX_EPOCHS] [--patience PATIENCE]
                  [--accum_steps ACCUM_STEPS] --setting {train,test}

options:
  -h, --help            show this help message and exit

General:
  --seed SEED           seed
  --gpu GPU             Please specify the GPU to use

Input:
  --train TRAIN         Path to training dataset (.h5ad)
  --test TEST           Path to test/query dataset (.h5ad)
  --phenotypelabel PHENOTYPELABEL
                        Phenotype label column in the AnnData object. Default: `disease`
  --samplecol SAMPLECOL
                        Sample/donor ID column in the AnnData object. Default: `donor_id`
  --celltypecol CELLTYPECOL
                        Cell type column in the AnnData object. Default: `cell_type`
  --checkpoint CHECKPOINT
                        Model checkpoint path (output when training, input when testing). Default: `Phenoverse_best_model.pth`

Output:
  --output_dir OUTPUT_DIR
                        Output directory for test results. Default: current working directory

Model:
  --embedding_dim EMBEDDING_DIM
                        Dimension of the cell embedding space
  --token_dim TOKEN_DIM
                        Dimension of the token for each cell type
  --num_prototypes NUM_PROTOTYPES
                        Number of prototypes per cell type
  --encoder_hidden_dim ENCODER_HIDDEN_DIM
                        Hidden dimension of the cell encoder
  --encoder_blocks ENCODER_BLOCKS
                        Number of residual blocks in the cell encoder
  --n_heads N_HEADS     Number of attention heads in the Perceiver-based aggregator
  --n_latents N_LATENTS
                        Number of latent tokens in the Perceiver-based aggregator
  --dropout DROPOUT     Dropout rate

Training:
  --batch_size BATCH_SIZE
                        Batch size
  --test_size TEST_SIZE
                        Fraction of samples held out for validation during training
  --max_epochs MAX_EPOCHS
                        Maximum number of training epochs
  --patience PATIENCE   Early stopping patience (epochs)
  --accum_steps ACCUM_STEPS
                        Gradient accumulation steps

Task:
  --setting {train,test}
                        `train` to train a Phenoverse model;
                        `test` to run a trained Phenoverse model on new data