MuSiCal (Mutational Signature Calculator) is a comprehensive toolkit for mutational signature analysis. It leverages novel algorithmic developments to enable accurate signature assignment as well as robust and sensitive signature discovery.
MuSiCal requires Python 3.10 or above. We recommend conda for managing packages and environments. If you do not have conda on your system yet, you can install conda through Anaconda or Miniconda.
You will also need Jupyter Notebook to try out the example scripts. If you have installed Anaconda, Jupyter Notebook will be installed already. Otherwise, follow this guide to install Jupyter Notebook separately. Note that it is better to install Jupyter Notebook in the base environment.
First, download the latest repository (e.g., via git clone, by downloading the zip file directly, etc.).
Then, create a conda environment:
conda create -n python310_musical python=3.10
Activate the environment with conda activate python310_musical or source activate python310_musical, depending on the version of conda you have on your system.
Install some dependencies:
conda install numpy scipy scikit-learn matplotlib pandas seaborn
Install MuSiCal:
cd /Path/To/MuSiCal
pip install ./MuSiCal
If you want to install MuSiCal in the development mode, use:
pip install -e ./MuSiCal
If pip install fails, try adding sudo -H.
Cornet is implemented in Sonata, which is an optional dependency of MuSiCal. It is required if you use the Cornet algorithm for de novo signature discovery.
With the python310_musical environment activated, install Sonata with:
pip install sonata-tools
After installing MuSiCal (either from third-party distributions or from source), you need to set up Jupyter Notebook to try out the example scripts.
Assuming that the python310_musical environment is activated, do:
conda install ipykernel
python -m ipykernel install --user --name python310_musical --display-name "python310_musical"
Since Jupyter Notebook is installed in the base environment, you need to deactivate the python310_musical environment with conda deactivate or source deactivate (depending on your conda version) to access Jupyter Notebook. You can launch Jupyter Notebook with
jupyter notebook
If you have installed Anaconda, you can also launch Jupyter Notebook from the graphical interface of Anaconda-Navigator.
Now you are ready to try out the example scripts. Remember to set the kernel of the notebook to python310_musical.
MuSiCal can be used after import musical within python.
The overall goal of mutational signature analysis is to decompose a mutation count matrix X into a signature matrix W and an exposure matrix H. Note that X is mutation type by sample (i.e., each column is a sample), W is mutation type by signature, and H is signature by sample.
De novo signature discovery is performed to derive de novo signatures, through musical.DenovoSig. The input matrix is factorized repeatedly, over a range of numbers of signatures and over multiple replicates, optionally on bootstrapped count matrices. The resulting solutions are then filtered and aggregated, and the best number of signatures is selected.
Three algorithms are available, selected with the method parameter of musical.DenovoSig:
method |
Algorithm | Notes |
|---|---|---|
'nmf' |
Standard NMF | Nonnegative matrix factorization with the Kullback-Leibler divergence. Simple and fast. |
'mvnmf' |
Minimum-volume NMF | Resolves the non-uniqueness problem of standard NMF by penalizing the volume spanned by the signatures. Addresses the "weight-stealing" problem in signature discovery, which is particularly relevant for flat signatures. |
'cornet' |
Cornet | Explicitly models the correlation structure between signatures instead of assuming independence among them as in NMF. Excels at sensitive signature discovery, resolving correlated and composite signatures, and mitigating cross-contaminations between discovered signatures. Implemented in Sonata, which must be installed separately. |
For example:
import musical
model = musical.DenovoSig(X, min_n_components=1, max_n_components=15,
method='cornet', n_replicates=20, ncpu=10)
model.fit()
The tmb_factor parameter rescales the input matrix so that the mean total mutation burden per sample becomes tmb_factor times the number of mutation types. For example, for SBS96 signatures there are 96 mutation types, so a tmb_factor of 10 corresponds to a mean total mutation burden of 960. Relative differences in mutation burden between samples are preserved. Rescaling is only relevant for Cornet. In general, a larger tmb_factor leads to sparser exposures and flatter signatures in Cornet solutions, and a smaller tmb_factor leads to flatter exposures and sparser signatures. We recommend a tmb_factor between 10 and 40 for SBS96 signatures.
In refitting, the observed mutational spectrum is decomposed into a combination of existing signatures with nonnegative coefficients. MuSiCal utilizes a novel algorithm called likelihood-based sparse nonnegative least squares (NNLS) for refitting. See example scripts.
MuSiCal provides preprocessing functionalities for automatic cohort stratification and outlier removal, to further improve the sensitivity of de novo signature discovery. See example scripts.
If you use MuSiCal, please cite:
Jin, H., Gulhan, D. C., Geiger, B., Ben-Isvy, D., Geng, D., Ljungström, V. & Park, P. J. Accurate and sensitive mutational signature analysis with MuSiCal. Nature Genetics 56, 541–552 (2024). https://doi.org/10.1038/s41588-024-01659-0
If you use the Cornet algorithm, please additionally cite the Cornet paper. A manuscript describing Cornet is currently in preparation, and this section will be updated with the citation once it becomes available.