Skip to content

3. Analysis

Jump to bottom
paolomanlapaz edited this page Jul 28, 2026 · 4 revisions

RiSPICE provides several downstream analysis utilities to help interpret variant scores. These workflows can be used to rank candidate variants, examine their predicted chromatin changes, and perform in silico saturation mutagenesis to identify influential nucleotides within a genomic region.

The available analyses are:

  1. Rank by Overall Score
  2. Analyze Per-Feature Scores
  3. In Silico Saturation Mutagenesis

Tip: Append --help to any RiSPICE command to display its usage, available options, and descriptions of each argument.

1. Rank by Overall Score

Ranks variants according to their Overall Score, allowing candidate variants with the largest predicted chromatin changes to be identified.

python -m scripts.analysis.prioritization.rank \
    --scores path/to/scores.tsv \
    --snp_list path/to/snp_list.tsv \
    -o path/to/output_directory

Use the --top flag to output only the top N variants (e.g. --top 20). When specified, the results are saved as top{N}_variants.tsv.

Visualize Ranked Variants

Generate a bar plot of the ranked variants.

python -m scripts.analysis.visualize.prioritization.top_variants \
    -i path/to/top20_variants.tsv \
    -o path/to/top20_variants.png \
    --title "Overall Scores of the Top 20 Variants"

Adjust the figure width as needed depending on the number of variants being displayed. The default width (6) is recommended for approximately 20 variants.

2. Analyze Per-Feature Scores

Generates a matrix of Per-Feature Scores sorted by Overall Score. Chromatin features are ordered according to their average predicted impact across all input variants, making the most affected features easier to identify.

python -m scripts.analysis.prioritization.per_feature_scores \
    --scores path/to/scores.tsv \
    --snp_list path/to/snp_list.tsv \
    -o path/to/output_directory \
    --top 20

Use the --top flag to output only the top N variants (e.g. --top 20). When specified, the results are saved as per_feature_scores_top{N}.tsv.

Visualize Per-Feature Scores

Generate a heatmap of the Per-Feature Scores.

python -m scripts.analysis.visualize.prioritization.per_feature_scores \
    -i path/to/per_feature_scores_top20.tsv \
    -o path/to/per_feature_scores_top20.png \
    --threshold_dir path/to/per_feature_thresholds \
    -t "Per-Feature Scores of the Top 20 Variants"

Adjust the figure height as needed depending on the number of variants being displayed. The default height (12) is recommended for approximately 20 variants.

Specify --threshold_dir to annotate statistically significant Per-Feature Scores. This directory should point to the extracted per_feature/ folder from the downloaded empirical background distribution, which contains the significance threshold (*.tsv) files for all chromatin features.

3. In Silico Saturation Mutagenesis Analysis

Prepare the Input

In Silico Saturation Mutagenesis evaluates the predicted effect of every possible single-nucleotide substitution within a genomic interval.

To begin, generate a snp_list.tsv containing all possible A/C/G/T substitutions across the region of interest. RiSPICE provides a helper script for this.

python -m scripts.snp.range_to_snp_list \
    --chrom 4 \
    --start 19884636 \
    --end 19884735 \
    --fasta genome.fna \
    --output_dir output/

The script:

  • extracts the specified interval from the reference genome.
  • determines the reference nucleotide at each position, and
  • generates every possible single-base substitution in snp_list.tsv.

Once the list has been generated, process it through the standard Prediction Pipeline to obtain scores.tsv.

Generate the Mutation Matrix

Convert the predicted scores into a mutation matrix suitable for downstream analysis.

python -m scripts.analysis.prioritization.mutagenesis \
    --scores scores.tsv \
    --snp_list snp_list.tsv \
    --output matrix.tsv

The resulting matrix.tsv contains the predicted score for every possible nucleotide substitution at each genomic position.

Annotate Statistical Significance

Annotate each mutation using the precomputed empirical significance thresholds.

python -m scripts.analysis.prioritization.genomewide_sig \
    --input matrix.tsv \
    --thresholds thresholds.tsv \
    --output_dir output/

This script produces:

  • significant_matrix.tsv, a boolean matrix indicating whether each mutation is statistically significant, and
  • significant_positions.tsv, a table containing positions within the genomic interval that has significant mutations.

Specify the --thresholds file containing the empirical significance thresholds. If you downloaded the empirical background distribution, use the corresponding thresholds.tsv file for your selected model.

Visualize the Results

Heatmap

Visualize the mutagenesis matrix as a heatmap.

python -m scripts.analysis.visualize.prioritization.mutagenesis_heatmap \
    --input matrix.tsv \
    --significance significant_matrix.tsv \
    --output heatmap.png \
    --title "In Silico Saturation Mutagenesis"

The heatmap displays the predicted score for every possible nucleotide substitution at each position. Statistically significant mutations are annotated using significant_matrix.tsv.

Maximum Effect Line Plot

Generate a line plot showing the maximum predicted score at each genomic position.

python -m scripts.analysis.visualize.prioritization.mutagenesis_max_effect \
    --input matrix.tsv \
    --thresholds thresholds.tsv \
    --output max_effect.png \
    --title "Maximum Score per Position"

The plot displays the maximum predicted score at each genomic position. A horizontal red line indicates the genome-wide significance threshold, making it easy to identify mutation hotspots with statistically significant effects.

Clone this wiki locally