CAPICE is a computational method for predicting the pathogenicity of SNVs and InDels. It is a gradient boosting tree model trained using a variety of genomic annotations used by CADD score and trained on the clinical significance. CAPICE performs consistently across diverse independent synthetic, and real clinical data sets. It ourperforms the current best method in pathogenicity estimation for variants of different molecular consequences and allele frequency.
The software can be used as web service, as pre-computed scores or by installing the software locally, all described below.
CAPICE can be used as online service as part of VIP at https://vip.molgeniscloud.org
hg38.phyloP100way.bw
spliceai_scores.masked.indel.hg38.vcf.gz
spliceai_scores.masked.indel.hg38.vcf.gz.tbi
spliceai_scores.masked.snv.hg38.vcf.gz
spliceai_scores.masked.snv.hg38.vcf.gz.tbi
The CAPICE software is also provided in this repository for running CAPICE in your own environment. The following sections will guide you through the steps needed for the variant annotation and the execution of making predictions using the CAPICE model.
Note: performance of CAPICE has been tested on Python 3.10. Performance on other Python versions is not guaranteed.
Preferred
pip install capice
Optional
git clone https://github.com/molgenis/capice.git
cd capice
pip install .
Developers
git clone https://github.com/molgenis/capice.git
cd capice
pip install -e '.[test]'
Additionally, the BCFTools Singularity image has to be obtained.
Installation on Windows systems is as of current not possible. Please refer to UNIX like systems (macOS or Linux) or use the Windows subsystem for Linux. You may also use the Singularity image of CAPICE found here.
Singularity images of CAPICE are made available as part of the VIP pipeline. These can be found here.
In order to score your variants through CAPICE, you have to annotate your variants using VEP by using the following command:
vep --input_file <path to your input file> --format vcf --output_file <path to your output file> \
--vcf --compress_output gzip --sift s --polyphen s --numbers --symbol \
--shift_3prime 1 --allele_number --refseq --total_length --no_stats --offline --cache \
--dir_cache </path/to/cache/107> --species "homo_sapiens" --assembly <GRCh38> \
--fork <n_threads> --dont_skip --allow_non_variant --use_given_ref --exclude_predicted \
--flag_pick_allele --plugin Grantham \
--plugin SpliceAI,snv=<path/to/spliceai_scores.masked.snv.vcf.gz>,indel=</path/to/spliceai_scores.masked.indel.vcf.gz> \
--custom "<path/to/gnomad.total.sites.stripped.vcf.gz>,gnomAD,vcf,exact,0,AF" \
--custom "<path/to/hg38.phyloP100way.bed.gz,phyloP,bed,exact,0" \
--dir_plugins <path to your VEP plugin directory>
Note: Certain arguments might not be needed if training/predicting without using all possible features offered by CAPICE.
Then you have to convert the VEP output to TSV using our own BCFTools script:
./scripts/convert_vep_vcf_to_tsv_capice.sh -i </path/to/vep_output.vcf.gz> -o </path/to/capice_input.tsv.gz>
Important!: this script uses APPTAINER and expects binds to be set correctly by the system administrator by utilizing the environment variable APPTAINER_BIND
.
CAPICE can be run by using the following command:
capice [-h] [-v] [--version] {module}
arguments
-h
: Print help and exit.-v
: Verbose flag. Add multiple v
to increase verbosity (more than 2 v
does not further increase verbosity).--version
: Print current CAPICE version and exit.CAPICE currently has the following available modules:
predict
train
explain
For all modules predict
, train
and explain
, the following arguments are available:
convert_vep_to_tsv_capice.sh
in the scripts directory (requires apptainer).For instance:
-i input.tsv
creates the output file input_capice.tsv.gz
-i input.tsv -o output.tsv.gz
creates the output file output.tsv.gz
-i input.tsv -o path/to/output.tsv.gz
creates the output file path/to/output.tsv.gz
-i input.tsv -o path/to/output_directory
creates the output file path/to/output_directory/input_capice.tsv.gz
The following argument is specific to predict
:
CAPICE_version
(str
), vep_features
(list[str]
), processable_features
(list[str]
) and predict_proba
(XGBoost.XGBClassifier
).
Models can be found as attachments on the GitHub releases page.The following arguments are specific to train
:
null
.
Please note that the features are case-sensitive!You can also use capice {module} --help
to show help on the command line.
A file will be put out containing the following columns:
Outside of Predictions, this repository also provides users the availability to create new CAPICE like models according
to their specific use case. Since the input file features are not validated apart from 6 features (CHROM
, POS
, REF
, ALT
, sample_weight
, binarized_label
(case sensitive)), user can provide their
own features. Please note that performance is validated on natively supported features. Performance is not guaranteed
for custom features.
Sample weight can be 1 for all samples if no sample weight should be applied. Binarized label should be either 0 or 1,
depending on your labels of classification. Train is optimized for a 2 class problem. Performance is not guaranteed for
more than 2 classes.
A file will be put out containing the following element:
xgb_classifier
: Universal Binary Json or JSON file of
a XGBClassifier instance that
has successfully trained on the input data, containing additional attributes CAPICE_version, vep_features and processable_features.Note: To load in the (universal binary) json model, use the following commands:
import xgboost as xgb
model = xgb.XGBClassifier()
model.load_model('/path/to/model.ubj')
Is only supported for CAPICE models that have been created using CAPICE v5.0.0 or greater!
The explain module takes a model and exports the feature importances of said model. Each of the importance type is described here.
Do note that the output of the explain module will always a gzipped TSV, just like the output of predict
.
Question:
Will CAPICE support CADD 1.6 and Genome Build 38?
Answer:
No (CADD 1.6) and yes (Genome Build 38). CADD has moved on to Snakemake and is quite slow.
It also limits us on updating VEP for improved and bugfixes on features. However, CAPICE will support genome build 38.
Question:
These scores are nice and all, but what do they really mean for this particular variant?
Answer:
CAPICE bases it's scoring on the training that it was provided with. A score is assigned based on features the model
learned to recognize during training. There are plans to make a "Capice Explain Tool" which will tell how a score came
to be.
Question:
Training a new model failed with an error in joblib.externals.loky.process_executor.RemoteTraceback
with ValueError: unknown format is not supported
. Why?
Answer:
This could possibly originate from a low sample size during the cross validation in RandomSearchCV.
Please contact us for further help.
Question:
I'm on Windows and installing XGBoost fails with the PIP
error “No files/directories in C:\path\to\xgboost\pip-egg-info (from PKG-INFO)”
. Am I doing something wrong?
Answer:
Unfortunately, XGBoost does not cooperate well with Windows. You might want to try to
install Setuptools before you attempt to install the dependencies. If that does
not work either, we suggest you use either a Unix style virtual machine or, if you are using Windows 10,
the Windows Subsystem for Linux is also available in the
Windows Store for free, which is guaranteed to work.
You could also use CAPICE through the Singularity Container.
Question:
I'm trying to run CAPICE, but I'm getting the following error:
xgboost.core.XGBoostError: XGBoost Library (libxgboost.dylib) could not be loaded.
Answer:
This error is caused on (likely) macOS when the package "OpenMP" is not installed. Please install libomp
to get XGBoost
running.
Question:
I'm getting the following error: ModuleNotFoundError: No module named 'sklearn'
. What is going wrong?
Answer:
sklearn
is a module that should be installed when scikit-learn
is installed. Either install sklearn
manually
though pip install sklearn
or try to re-install scikit-learn
.
Question:
I'm getting the warning /usr/local/lib/python3.8/dist-packages/joblib/_multiprocessing_helpers.py:45: UserWarning: [Errno 2] No such file or directory. joblib will operate in serial mode warnings.warn('%s. joblib will operate in serial mode' % (e,))
when using the CAPICE Singularity image. What's going wrong?
Answer:
This is likely due to the fact that the Singularity image searches for shared memory, which is different for Windows style operating systems.
This means that any and all multiprocessing parts of CAPICE will perform in single threaded mode. Other than that, CAPICE should work just fine.
Question:
I want to use the standalone SpliceAI instead of the VEP plugin. Is this possible?
Answer:
We are investigating options to include the standalone SpliceAI since this requires a lot less resources for the precomputed scores that the VEP plugin uses.
You could try to use it, but proceed at your own risk.
Question:
CAPICE gives an error that the model version does not match with the CAPICE version.
Answer:
There are certain restrictions regarding what model versions can be used with CAPICE.
For regular releases, the major version must be identical.
For pre-release versions (with rc<number>
in the version), the entire version number (major, minor, patch & pre-release) must be identical.
Question:
I created/am using a .pickle.dat
model, but the newer versions of CAPICE switched to .ubj
/.json
instead for models.
Can I somehow use my old .pickle.dat
with newer versions of CAPICE.
Answer:
First of all, it's important to note that with every major release, breaking changes might be implemented.
However, it might be possible to upgrade a CAPICE 4.x.x model to a model usable by CAPICE 5.x.x (though no guarantees are
given!).
To convert a .pickle.dat
model to .ubj
/.json
, one can do the following (using a local git clone of the repository):
Use the following python code:
import sys
import pickle
with open(sys.argv[1], 'rb') as model_file:
model = pickle.load(model_file)
model.save_model(sys.argv[2])
sys.argv[1]
: the input .pickle.dat
filesys.argv[2]
: the output .json
fileCAPICE_version
within the new model file to that of the new release (major version should match!).
It is advisable however to ensure that the filename still contains the version it was trained on (e.g. v4.0.0_grch38_v5.0.0-compatibility.json
) to ensure no confusion will exist on which version it was actually trained.Do note that we recommend using a model trained on a specific major version instead, as other breaking changes might be present as well!
The gnomAD files can be generated through the following scripts (which also download the gnomAD files):
PhyloP resources can be downloaded from:
Files for the SpliceAI VEP plugin can be found in the Illumina project "Predicting splicing from primary sequence" (as mentioned here), which can be accessed after creating an account on Illumina. Once added, the relevant files can be accessed as follows:
Predicting splicing from primary sequence
analyses
subtab (might be selected by default)genome_scores_v<version_number>
(select most recent version)files
subtabgenome_scores_v<version_number>
folderIf you're lost in the code, an outdated map can be found here.