Skip to content

crisprme_web_interface_user_guide.md

Latest commit

 

History

History
854 lines (647 loc) · 40.5 KB

crisprme_web_interface_user_guide.md

File metadata and controls

854 lines (647 loc) · 40.5 KB
Raw

CRISPRme: Local Web Interface User Guide

This guide covers how to launch, navigate, and operate CRISPRme's locally hosted web interface. Getting CRISPRme and its reference data in place is a one-time step — the simplest route is the Docker Quickstart (a few commands, no conda, no multi-hour setup), summarised in Section 2 below. Once your data is in place, the web interface provides a point-and-click alternative to the command line for running searches and exploring results.

New here? The quickest way to run everything below is the Docker Quickstart: install Docker, fast-download the data and a prebuilt index, and launch the interface — a few commands, no conda and no multi-hour setup. Section 2 gives the short version.

Section 1. Introduction to the Web Interface

CRISPRme's local web interface provides a browser-based front-end to the same analysis engine used by the command-line tool. It is designed for users who prefer a graphical environment for configuring analyses, monitoring job progress, and interactively exploring results — without sacrificing any of the analytical depth available from the CLI.

Who is this interface for?

  • Researchers who are new to CRISPRme and prefer guided, form-based input over command construction.
  • Analysts who want to interactively filter and visualise results after a search completes, without writing custom scripts.
  • Teams sharing a single server installation, where multiple users can access the interface via a browser on the same network.

What the interface provides:

  • A guided three-step job-submission form for configuring and launching Complete Search analyses.
  • A dedicated Job Status page that tracks pipeline progress and links to results upon completion.
  • A Results page with an interactive summary table and up to six report tabs (Summary by Sample and Personal Risk Cards appear only for variant-aware searches; a reference-only search shows four), each covering a different analytical perspective on the identified off-targets.
  • Embedded visualisation panels including stem plots, population bar charts, radar charts, and sequence motif logos.
  • A direct download path for all result files generated by CRISPRme.

What the interface does not replace:

The web interface is a front-end to the same complete-search pipeline described in the CLI guide. Utilities such as gnomAD-converter and generate-personal-card remain CLI-only operations. For those workflows, refer to Section 2.2 of the CRISPRme README.

Section 2. Prerequisites and Launching the Interface

Estimated time: a few minutes of downloads, then the interface starts in seconds.

The interface needs two things: CRISPRme (we recommend Docker — the only thing you install is Docker itself) and a working directory holding the reference data. The full setup is the Docker Quickstart; the short version is here.

2a. Get the data (one time)

Make a folder for your data and results, then fast-download the reference data and a prebuilt SpCas9 (NGG) index from the CRISPRme mirror (minutes, not the multi-hour legacy setup):

mkdir -p ~/crisprme && cd ~/crisprme

# reference genome, annotations, PAMs and sample lists
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 \
  crisprme.py download --what all --path /DATA

# a ready-made SpCas9 (NGG) reference index (skips a long index build)
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 \
  crisprme.py download --what index --index-name NRG_3_hg38 --path /DATA

# the variant-aware index used by the default web search (1000G + HGDP)
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 \
  crisprme.py download --what index --index-name NRG_3_hg38+hg38_1000G2021_HGDP --path /DATA

This creates the CRISPRme folder structure (Genomes/, PAMs/, Annotations/, VCFs/, samplesIDs/, genome_library/, Results/) inside ~/crisprme. The pre-downloaded NRG_3_hg38+hg38_1000G2021_HGDP index already makes the default web search variant-aware — you do not need the raw VCFs for that. Optional (advanced): the raw 1000 Genomes VCFs (~16 GB) are only needed for CLI sample-level analyses / personal risk cards: … crisprme.py download --what vcf --dataset 1000G --path /DATA.

2b. Start the local server

From the same folder, launch the web interface. -p 8080:8080 connects the app to your browser, and -v "${PWD}:/DATA" keeps your data and results on your own computer:

docker run --rm -v "${PWD}:/DATA" -w /DATA -p 8080:8080 -it \
  pinellolab/crisprme:v2.5.5 crisprme.py web-interface

Keep this terminal open for the session; press Ctrl+C to stop the server.

Using a Conda/Mamba install instead? Activate your environment (mamba activate crisprme — the env the source build creates — or conda if you use conda), cd into your working directory, and run crisprme.py web-interface. Everything else in this guide is identical.

2c. Open the interface in a browser

Once the server is running, open one of the following supported browsers and navigate to the address below:

Situation URL to enter
Running locally on your own machine http://127.0.0.1:8080
Running on a remote server or HPC node http://<server-ip-address>:8080

Browser compatibility: The interface has been tested and confirmed working on Google Chrome, Mozilla Firefox, and Safari. For the best experience, use an up-to-date version of one of these browsers.

No internet connection required: All interface assets are served locally. Once the server is running, the interface is fully self-contained and does not require outbound network access.

Section 3. Interface Overview

The web interface is built around four distinct pages (a Search page, a Results page, a History page, and a Settings / Data Manager) that follow the natural sequence of a CRISPRme analysis: job submission on the Homepage, progress tracking on the Job Status page, and interactive data exploration on the Results page. A persistent navigation bar at the top of every page provides access to the manual and allows navigation between active jobs and completed results.

3a. Homepage

The homepage is the starting point for every new analysis. It presents a single scrollable form divided into three clearly labelled steps. Completing these steps and clicking Submit is all that is required to launch a genome-wide off-target search.

The form is designed to be self-guiding: each input field is accompanied by a short description of the expected format, and required fields are visually distinguished from optional ones. The three steps cover:

  • Step 1 — Spacer and PAM selection: Define what to search for.
  • Step 2 — Genome selection and threshold configuration: Define where to search and how permissively. By default a single Maximum edits slider (total mismatches + bulges, default 3) controls stringency; Advanced options exposes the per-type caps (mismatches up to 6, DNA bulges up to 2, RNA bulges up to 2), and a candidate must satisfy each per-type cap and the overall budget.
  • Step 3 — Email notification and job name: Label the job (functional annotations are applied automatically from the enabled set — see Managing annotations).

Each step is described in detail in Section 4 of this guide.

3b. Job Status page

Immediately after submission, the interface transitions to the Job Status page. This page displays a live progress report for the running job, drawn from the same log_verbose.txt file written to disk in the output folder. Once the pipeline finishes, a View Results link appears at the bottom of the status report, navigating directly to the Results page for that job.

The Job Status page is also reachable from previously submitted jobs listed in the navigation bar. If you close your browser during a long-running search, the job continues in the server process; return to this page at any time to check status or retrieve the results link.

3c. Results page

The Results page is the analytical hub of the interface. It is composed of two main areas:

Summary table. At the top of the page, a per-guide summary table provides an immediate overview of the search outcome. For each input guide RNA, the table reports the CFD specificity score, the number of on-targets, and the number of off-targets found in both the reference genome and the variant genome, broken out across mismatch and bulge categories. A Download General Table button in the top-left corner exports this summary as a plain text file.

Six interactive report tabs. Below the summary table, six tabs provide different analytical views of the full result set. Each tab is described in detail in Section 5 of this guide:

Tab Purpose
Custom Ranking Filter and rank off-targets by score, mismatch count, bulge size, or variant risk.
Summary by Mismatches/Bulges Matrix view of target counts organised by target type and alignment complexity.
Summary by Sample Per-sample breakdown of variant-specific off-targets and population-level context.
Query Genomic Regions Retrieve all off-targets overlapping a user-specified chromosomal interval.
Graphical Reports Stem plots, population bar charts, radar charts, and sequence motif logos.
Personal Risk Cards Individual-level report of private and personal off-target candidates (variant-aware searches only).

Section 4. Running an Analysis via the Web Form

This section walks through the three-step submission form on the Homepage. For full parameter definitions — including accepted value ranges and biological rationale — refer to Section 3 of the CRISPRme CLI Setup and Usage Guide.

Step 1: Spacer and PAM selection

This step defines the CRISPR reagents to search with.

Spacer(s)

Enter one or more guide RNA spacer sequences, one per line, in the text input box. The spacer is the 20-nucleotide region that directs Cas protein binding to the genomic protospacer target. In CRISPRme, spacers are entered as DNA sequences (rather than RNA) for direct comparison with aligned protospacer sequences. The input sequence should not include the PAM.

Key constraints:

  • All spacers in a single submission must be the same length.
  • Each spacer must be entered on a separate line.
  • You can enter multiple spacers; for large batches use the command-line version (there is no limit on the number of spacers in the offline/CLI search).

Genomic sequence(s) (alternative input)

As an alternative to entering spacers directly, CRISPRme can derive candidate spacers automatically from a genomic region or a DNA sequence. Two formats are supported:

  • BED format — specify chromosomal coordinates as chromosome start end (0-based coordinates). CRISPRme extracts the possible spacer sequences within the region, beginning from the positive strand.
  • FASTA format — provide one or more DNA sequences up to 1,000 characters each. Each entry must be preceded by a >header line.

The spacer input and the genomic sequence input are mutually exclusive. Activating one disables the other.

PAM sequence

Select a PAM from the dropdown menu. The menu lists all PAM definition files found in your PAMs/ directory. CRISPRme supports both 3′ PAMs (such as the NGG PAM used by SpCas9) and 5′ PAMs (such as the TTTV PAM used by Cas12a). The PAM is a short DNA sequence adjacent to the protospacer that is essential for Cas protein binding.

If your nuclease is not listed, create a custom PAM file as described in Section 5 of the CLI guide and restart the server to make it available in the dropdown.

Step 2: Genome selection and threshold configuration

This step defines the search space and the alignment stringency.

Genome build

Select a reference genome from the dropdown menu. All genome directories present in your Genomes/ folder are listed. CRISPRme supports any FASTA-based genome from UCSC, including the default hg38 build (with mitochondrial DNA), custom transcriptomes, non-human genomes, and cancer genome assemblies.

When variant datasets have been prepared (for example, 1000 Genomes Phase 3 or HGDP), the interface presents the option to incorporate them into the search. Adding personal variants from private VCFs is supported in the local offline version via the CLI; it is not configurable from this form.

RNA-targeting strategies: For RNA-targeting Cas proteins, you can either provide a custom transcriptome genome or use a variant-enriched genome. Be aware that the latter may miss off-targets located at splice junctions.

Search thresholds

By default the form exposes a single Maximum edits slider — the total number of differences (mismatches + DNA/RNA bulges) allowed between a guide and an off-target (default 3; raise it for a deeper, slower search). This is all you need for a quick search.

Open Advanced options to set the per-type caps individually instead:

  • Mismatches — the maximum number of base mismatches between the spacer and the protospacer. The web interface supports up to 6 mismatches.
  • DNA bulges — the maximum number of DNA bulges (insertions in the DNA strand relative to the RNA). The web interface supports up to 2 DNA bulges.
  • RNA bulges — the maximum number of RNA bulges (insertions in the RNA strand relative to the DNA). The web interface supports up to 2 RNA bulges.

In Advanced mode a candidate must satisfy each per-type cap and the overall max-total-edits budget. Bulges can be consecutive (e.g., NN--NN) or interleaved (e.g., NN-N-NN).

The web interface uses only precomputed indexes and will not build one on the fly — if you request a PAM/bulge/genome combination with no installed index it blocks and asks you to install one first (see the Docker Quickstart, "Installing more indexes"). The variant selector is a dropdown pre-set to the variant-aware 1000G+HGDP index, with a Reference only option if you want a reference-genome search.

Performance note: Enabling bulge searching substantially increases runtime. For a whole-genome search across both 1000G and HGDP, expect runtimes of several hours even on well-resourced systems. Start with bulges set to 0 if you need a rapid preliminary result.

Base editing thresholds (optional)

When base editing is enabled (a Yes/No option, independent of the PAM/nuclease), an additional sub-section becomes active. Use the Window start and Window stop dropdowns — both constrained to the length of the input guide — to define the region within the protospacer where the base editing reaction is expected to occur. Then select the Nucleotide that the editor targets (for example, A for adenine base editors).

CRISPRme will annotate every candidate off-target site with whether the target nucleotide falls within the specified window, generating a comprehensive output file indicating per-site base editing susceptibility.

Step 3: Email notification and job name

This step attaches optional metadata to the search.

Functional annotation (now automatic)

Off-targets are automatically overlaid with the currently enabled functional annotations — no per-search selection is required. Annotations provide biological context (for example, whether an off-target falls within a regulatory element or a protein-coding gene) and populate the annotation columns of the results tables.

The default installation ships one enabled bundle that is applied out of the box:

  • Functional regions (hg38) — ENCODE candidate cis-regulatory elements (SCREEN cCREs), DHS accessible-chromatin regions, and GENCODE gene features (protein-coding genes, UTRs, introns), plus the GENCODE gene-annotation track.

Which annotations are applied is controlled centrally in Settings → Manage annotations (enable / disable) rather than on the search form. In the local offline version you can upload additional cell-type-specific annotation BED files (Settings → Add an annotation), enable/disable them per genome, and they are then applied automatically to every subsequent search. See Managing annotations below.

Email notification (optional)

Tick Notify me by email and enter your address to be emailed a link when the job completes — useful for long-running whole-genome searches where you do not wish to keep the browser open. Sending requires a one-time mail-server setup in Settings → Email notifications (SMTP host, sender address, and an app password); see Email notifications below. Until that is configured the job still runs — it simply will not email you.

Job name (optional)

Provide a short label to prefix the automatically generated unique job ID. For example, entering my_job produces an identifier such as my_job_G05B8KHU0H, making it easier to locate a specific search in the Results listing.

Submitting the job

Once all required fields in Steps 1 and 2 are complete, click the Submit button at the bottom of the form. The interface validates the inputs and highlights any missing required fields in red. If validation passes, the job is queued and the interface navigates automatically to the Job Status page.

Important: Do not close the browser tab while a job is running. Closing the tab does not cancel the job (it continues in the server process), but the live progress display will no longer update. To resume monitoring, return to the Job Status page from the navigation bar.

Long-running jobs: Whole-genome searches typically run for several hours. If you are using a remote server and are concerned about SSH session timeouts, start the server inside a tmux or screen session before opening the browser:

tmux new -s crisprme
cd ~/crisprme      # your data folder
docker run --rm -v "${PWD}:/DATA" -w /DATA -p 8080:8080 -it \
  pinellolab/crisprme:v2.5.5 crisprme.py web-interface
# Detach with Ctrl+B then D — the server continues running.
# (Conda users: mamba activate crisprme && crisprme.py web-interface)

Searching a personal assembly genome (assembly-search)

Alongside the standard reference + variant search, the web interface can search a fully assembled personal diploid genome directly — the two haplotype assemblies (e.g. paternal and maternal) — instead of inferring variants from population data via a reference genome + VCF. Each haplotype is searched independently, lifted to hg38 via its liftOver chain, and the two are reconciled: an off-target found on both haplotypes is homozygous-equivalent, found on one is heterozygous-equivalent, and a prediction with no hg38 equivalent is haplotype-non-mappable — invisible to any reference-based search. This is useful for individuals whose genome is not well represented by short-read variant panels (e.g. HPRC pangenome assemblies).

Step 1 — register an assembly (Settings → Data Manager → "Add a personal assembly"). Two ways to provide the inputs:

  • Fetch from HPRC (Release 2): enter an HPRC sample id (e.g. HG01255) and click fetch — CRISPRme downloads that individual's paternal + maternal assembly FASTAs, the liftOver chains, and the chromAlias files, and registers them with the Data Manager.
  • Upload your own: provide, per haplotype, a per-chromosome assembly FASTA folder, a liftOver .chain(.gz) versus GRCh38, and a .chromAlias.txt file (the HPRC-style tab-separated file with # assembly, ucsc, genbank columns), then Register assembly.

Step 2 — launch the search. On the search form, under Step 2: Select genome, switch from the Reference genome tab to the Personal assembly tab and pick a registered Individual. The guide/PAM/threshold fields are the same as a standard search (the analysis-mode radio does not apply — an assembly is the individual's genome, so there is nothing to infer). Click Submit; the job launches as an assembly-search run and the interface navigates to a status page tailored to its pipeline stages (per-haplotype search → liftOver → reconciliation).

Results. A completed assembly-search job opens a Personal Assembly Search Results page that mirrors the standard results layout for two-haplotype data: haplotype-coverage counts (both / paternal-only / maternal-only / non-mappable) with a coverage plot, a reconciled hg38 off-target table (with a Custom Ranking tab — site-set picker for mappable vs per-haplotype-unmappable sites, region filter, sort — and a Summary by Mismatches/Bulges tab), CFD-distribution and per-position plots, and a combined report.zip download that bundles the reconciled report plus each haplotype's own complete-search report.

CLI equivalent: crisprme.py assembly-search --genome-paternal … --genome-maternal … --chain-paternal … --chain-maternal … --chrom-alias-paternal … --chrom-alias-maternal … --guide … --pam … --mm … [--bDNA … --bRNA …] --output <name> (see crisprme.py assembly-search --help).

Managing annotations (Settings)

Functional annotations are no longer chosen on the search form. Instead they are managed centrally in Settings → Data Manager (local offline mode only; the section is disabled on the public --website server) and applied automatically to every search. This keeps searches reproducible — the same enabled set is used for all jobs until you change it.

Add an annotation (BED). Under Add an annotation, drag-and-drop or select a .bed/.bed.gz file. Each uploaded file is validated before it is accepted: it must have at least four tab-separated columns (chrom, start, end, label), integer coordinates with start ≤ end, a whitespace-free label, and be under the size cap. Malformed files are rejected with an explanatory message and nothing is written. Name files with the genome assembly token (e.g. myenhancers.hg38.bed) so they are offered for the matching genome.

Enable / disable annotations. Under Manage annotations (enable / disable), pick a genome to see a checklist of the available tracks — the built-in Functional regions bundle plus any custom BEDs you have uploaded for that genome. Tick the ones you want applied and click Save enabled annotations. The built-in bundle is enabled by default on a fresh install, so annotations work out of the box with no configuration.

When more than one track is enabled, CRISPRme merges them into a single combined annotation the first time you search (cached and rebuilt only when the enabled set changes). If you disable every track, searches still run — off-targets simply carry no functional annotation. The GENCODE gene-annotation track is applied automatically alongside the built-in bundle.

Email notifications (Settings)

To have CRISPRme+ email you when a job finishes, configure a mail server once in Settings → Data Manager → Email notifications (local offline mode only):

  • SMTP host / Port / SSL — your provider's outgoing mail server. For Gmail use smtp.gmail.com, port 465, SSL on.
  • Sender address — the account the notification is sent from.
  • App password — for Gmail (and most providers with 2-factor auth) generate an app password (Google Account → Security → App passwords) and paste it here — not your normal login password.

Click Save email settings. The settings are stored locally in your data folder (.email.json, readable only by you; it holds the app password, so set it only on a machine you control). You can also configure the sender/password without the UI via the CRISPRME_SMTP_SENDER / CRISPRME_SMTP_PSW environment variables.

Once configured, tick Notify me by email on the search form and enter your address. Email is best-effort: if the mail server rejects the message the search still completes normally — the failure is logged, not fatal.

Section 5. Visualising and Interacting with Results

When a search completes, clicking the View Results link on the Job Status page opens the Results page. The page is structured as a summary table followed by six interactive report tabs, each described below.

5a. Results summary table

The summary table at the top of the Results page provides a per-guide overview of the entire search. For each guide RNA submitted, the table shows:

  • CFD — the Off-Target Cutting Frequency Determination specificity score. This score quantifies the guide RNA's aggregate affinity for off-target sites: a higher score indicates greater predicted on-target specificity. The CFD specificity score was originally designed for searches with up to 3–4 mismatches; as the number of mismatches increases, the score declines non-linearly. Comparisons between searches that used different mismatch or bulge thresholds, or different variant datasets, should therefore be made with caution.
  • Off-Targets Reference (0–n Mismatches + Bulges) — the number of potential off-target sites identified in the reference genome, tabulated per mismatch and bulge count combination.
  • Off-Targets Variant (0–n Mismatches + Bulges) — the number of potential off-target sites identified in the variant genome, tabulated per mismatch and bulge count combination.

Use the Download General Table button in the top-left corner to export this summary as a plain text file.

5b. Tab 1 — Custom Ranking

The Custom Ranking tab presents a fully filterable and sortable table of all candidate off-target sites identified in the search. It allows users to construct a ranked shortlist based on criteria most relevant to their experimental question.

Targets can be filtered and ranked by any combination of:

  • Mismatches and bulges — retain only candidates within a specified alignment distance from the spacer sequence.
  • CFD score — set a minimum score threshold to focus on sites most likely to be cleaved.
  • Risk Score — the increase in CFD score attributable to a genetic variant at that site. A high Risk Score identifies positions where a population variant creates a substantially more cleavage-susceptible off-target than the reference sequence predicts.

This tab is the recommended starting point for generating a prioritised target panel for experimental validation.

5c. Tab 2 — Summary by Mismatches/Bulges

This tab presents a matrix that categorises all identified targets by alignment complexity. Rows in the matrix are organised by three target types:

  • X — targets containing only mismatches (no bulges).
  • DNA — targets containing at least one DNA bulge (with or without additional mismatches).
  • RNA — targets containing at least one RNA bulge (with or without additional mismatches).

Each cell of the matrix contains a count of targets for a given type, mismatch count, and bulge size combination. The following fields are reported per row:

Field Description
Bulge Type The bulge type of the targets in this row (X, DNA, or RNA).
Bulge Size The size of the bulge.
Mismatches The number of mismatches.
Targets in Reference Number of targets found in the reference genome for this mismatch/bulge combination.
Targets in Sample Number of targets found in the variant genome for this mismatch/bulge combination, each associated with at least one sample.
PAM Creation Number of sites where a genetic variant in the dataset creates a new PAM sequence.
Show Targets A link that opens a dedicated page listing all individual targets for the selected row, with full alignment and annotation details.

5d. Tab 3 — Summary by Sample

The Summary by Sample tab lists every sample present in the provided VCF datasets and reports how many variant-specific off-target candidates are associated with each individual. This view is the entry point for personalised risk assessment.

The following fields are reported per sample:

Field Description
Gender The sample's biological sex as recorded in the VCF metadata.
Population The population to which the sample belongs (e.g., CEU, YRI).
Super Population The superpopulation grouping (e.g., EUR, AFR, EAS, AMR, SAS).
Targets in Sample Number of variant off-targets generated by variants carried by this individual sample.
Targets in Population Number of variant off-targets generated by all samples within the same population.
Targets in Super Population Number of variant off-targets generated by all samples within the same superpopulation.
PAM Creation Number of new PAMs created by variants carried by this sample.
Show Targets A link that opens a dedicated page showing all individual off-target sites for the selected sample, with full alignment and annotation details.

5e. Tab 4 — Query Genomic Regions

The Query Genomic Regions tab provides a positional lookup tool. Enter a chromosomal interval in the format chromosome:start-end (for example, chr2:74732390-74732490) to retrieve all off-target candidates whose genomic coordinates overlap with the specified region.

This tab is particularly useful for assessing off-target risk within a specific regulatory element, coding exon, or other region of biological interest, without having to scroll through the full result set.

5f. Tab 5 — Graphical Reports

The Graphical Reports tab aggregates all visual outputs generated for the search into a single scrollable panel. Four types of plot are produced per guide RNA:

Stem plot (lolliplot)

The stem plot illustrates how genetic variants alter predicted off-target cleavage potential. Each candidate site is represented by two connected dots: a red dot for the reference allele off-target and a blue dot for the alternative allele off-target. The arrow connecting the two dots indicates the direction and magnitude of the change in predicted cleavage potential caused by the variant. Sites where the alternative allele substantially raises the score above the reference appear as prominent upward-pointing stems and represent the highest variant-driven off-target risk.

Population bar charts

A series of bar charts displays the distribution of the top candidate off-targets across superpopulations, stratified by mismatch count and bulge size. These charts give a population-level view of which demographic groups carry the highest burden of variant-specific off-target sites for the searched guide.

Radar chart

The radar chart visualises the relative specificity of the guide RNA across functional genomic regions, as defined by the GENCODE and ENCODE annotations provided during the search. Each axis of the radar corresponds to an annotation category (for example, promoters, coding exons, introns, or enhancers), and the area enclosed by the trace reflects the number of off-targets falling within that category. A larger enclosed area indicates a guide with more off-target candidates in annotated functional regions, which may be considered an undesirable outcome for clinical or therapeutic applications. A summary table accompanying the chart provides the exact count and percentage of off-targets per annotation category.

Sequence motif logo

The motif logo summarises the frequency and position of mismatches and bulges across all top candidates. Each position along the spacer and PAM sequence is represented by a stacked letter plot, where the height of each letter reflects how often that base position contributes a mismatch or bulge in the off-target alignment. This view reveals positional tolerances in the guide's recognition profile — positions with tall stacks are poorly discriminating and may warrant re-design.

5g. Tab 6 — Personal Risk Cards

The Personal Risk Cards tab generates a sample-specific off-target report for any individual in the variant dataset. Select a sample ID from the dropdown to retrieve a dedicated card summarising all off-target candidates relevant to that individual's unique genomic sequence.

The report is structured as two components:

Plots. Two dynamically generated plots display all candidate variant off-targets for the selected sample — those unique to the individual and those shared with the broader population — and illustrate how each sample's genetic variants influence predicted off-target cleavage potential relative to the reference genome.

Tables. Two tables accompany the plots:

  • Table 1 (Summary table) — provides aggregate counts for the three categories of personalised off-target risk:

    Field Description
    Personal Total count of all candidate variant off-targets for the selected sample, including both unique variants and those shared with other individuals.
    PAM Creation Count of instances where a variant carried by this sample creates a novel PAM sequence at an otherwise inactive site.
    Private Count of candidate variant off-targets found exclusively in this sample and not present in any other individual in the dataset.

  • Table 2 (Target detail table) — provides full alignment and annotation details for each individual off-target site extracted for the selected sample, equivalent in structure to the target detail tables accessible from the Summary by Sample tab.

This tab is the in-interface equivalent of the generate-personal-card CLI functionality. For batch generation of personal cards across many samples, refer to Section 2.2.6 of the CRISPRme README.

Section 6. Troubleshooting

This section covers issues specific to the local server environment and browser interaction. For problems with the CRISPRme search pipeline itself — such as unexpected output or missing results files — consult the log_error.txt file in the relevant results folder and refer to the CRISPRme GitHub Issues page.

The browser shows "Unable to connect" or the page does not load

Cause: The server has not started, or the URL is incorrect.

Steps to resolve:

  1. Confirm the server started without errors by checking the terminal output. Look for a message indicating the server is listening on port 8080.
  2. Confirm you are navigating to http://127.0.0.1:8080 (not https://). The local server does not use TLS.
  3. If running on a remote machine, replace 127.0.0.1 with the server's IP address or hostname.
  4. Confirm that port 8080 is not blocked by a firewall. On Linux, check with: 
    sudo ss -tlnp | grep 8080
  5. If another process is already using port 8080, stop it or restart the CRISPRme server after the port is free. If Docker reports Bind for 0.0.0.0:8080 failed: port is already allocated, another container is holding the port: stop it (docker ps, then docker stop <id>) or map a different host port with -p 8081:8080 and open http://127.0.0.1:8081.

Search finished but the results table is empty (or shows no variant off-targets)

Cause: The search completed but returned no candidates, or none carrying variants.

Steps to resolve:

  1. Thresholds too strict — raise Maximum edits; if you opened Advanced options, check the DNA and RNA bulges are not both 0.
  2. Reference-only selected — keep the 1000G+HGDP option (pre-selected by default) to get variant off-targets.
  3. Variant index not installed — re-run crisprme.py download --what index --index-name NRG_3_hg38+hg38_1000G2021_HGDP --path /DATA.
  4. Confirm success — Results/<name>/log_error.txt is empty and *.integrated_results.tsv is non-empty.

A search dies with no error / the container exits

Cause: Docker ran out of memory (OOM). Signs: the job stops advancing, log_error.txt is empty, and the terminal returns to the prompt (or exits with code 137). A genome-wide 1000G+HGDP search is the heaviest case; give it enough RAM.

Steps to resolve:

  1. Raise Docker Desktop memory to ≥32 GB (64 GB recommended for genome-wide population-variant runs).
  2. Delete the incomplete Results/<name>/ folder and resubmit.
  3. Or reduce the cost of the search: select Reference only or lower Maximum edits.

No genomes, PAM files, or VCF datasets appear in the form dropdowns

Cause: The server was started from the wrong working directory, or the Genomes/ and PAMs/ directories are empty.

Steps to resolve:

  1. Stop the server (Ctrl+C in the terminal).
  2. Confirm your current directory contains the expected CRISPRme subdirectories: 
    ls
# Expected: Annotations/ Dictionaries/ Genomes/ PAMs/ Results/ VCFs/ samplesIDs/
  3. Any crisprme.py command recreates missing directories automatically, but they stay empty until you run the download step. If the dropdowns are still empty, re-run crisprme.py download --what all --path /DATA (and the index download) from the working directory, then restart the server.
  4. Restart the server from the correct directory.

A submitted job appears to hang and the progress indicator does not advance

Cause: Long-running steps such as genome indexing or large VCF processing can take tens of minutes without visible progress updates.

Steps to resolve:

  1. Check the live log tail on the Job Status page for any error messages.
  2. Alternatively, inspect the log files directly in the terminal: 
    tail -f Results/<output-name>/log_verbose.txt
tail -f Results/<output-name>/log_error.txt
  3. If log_error.txt contains a non-empty error message, the job has failed. Note the error, address the underlying issue (for example, a missing annotation file or insufficient memory), delete the output folder, and resubmit.

The browser session times out during a long-running search

Cause: Whole-genome searches can take several hours. Some browsers impose idle timeouts, and remote SSH connections may drop.

Steps to resolve:

The search job runs in the server process, not in the browser. If your session expires or you close the tab:

  1. The job continues running on the server.
  2. When it completes, the results folder appears in the navigation bar the next time you load the interface.
  3. To prevent losing the server process on a remote machine, start the server inside a persistent terminal multiplexer before opening the browser: 
    tmux new -s crisprme
mamba activate crisprme
cd "$CRISPRME_DIR"
crisprme.py web-interface
# Press Ctrl+B, then D to detach. The server keeps running.
    To reattach later: tmux attach -t crisprme

Results appear on disk but are not visible on the Results page

Cause: The browser is displaying a cached version of the page.

Steps to resolve:

  1. Hard-refresh the browser tab: press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS).
  2. If the results folder still does not appear, confirm the search completed successfully by checking that Results/<output-name>/ exists in your working directory and that log_error.txt is empty.

Old result folders from previous sessions appear in the interface

Cause: CRISPRme lists every subdirectory found in Results/. Old result directories are not automatically removed.

Steps to resolve:

To remove old results, delete the unwanted folder from the terminal:

rm -rf Results/<old-output-name>/

Refresh the browser to update the listing.

Appendix: Mapping Web Form Fields to CLI Flags

Every analysis launched from the web interface is equivalent to a crisprme.py complete-search command. The table below maps each web form field to its corresponding CLI flag for cross-reference.

Web form field CLI flag Required
Spacer(s) / Genomic sequence(s) --guide / --sequence Yes (one or the other)
PAM sequence --pam Yes
Reference Genome --genome Yes
Variant dataset(s) --vcf Optional
Samples ID config --samplesID Required if --vcf provided
Mismatches --mm Yes
DNA bulges --bDNA Optional (default 0)
RNA bulges --bRNA Optional (default 0)
Base editing window --be-window Optional
Base editor nucleotide --be-base Optional (required if window set)
Functional annotation --annotation Optional
Gene annotation --gene_annotation Optional
Job name --output Yes

For complete parameter definitions, accepted value ranges, and guidance on choosing appropriate values for your experimental question, refer to Section 3 of the CRISPRme CLI Setup and Usage Guide and Section 2.2.1 of the CRISPRme README.