Graphical Interface (Workbench)
The SigProfilerMatrixGenerator Workbench generates mutational matrices from your browser, without writing code. Choose a folder of variant calls and the reference genome they were called against, start the run, follow its progress, and plot the resulting matrices sample by sample.
Everything runs on your own computer: the Workbench is a small server on this machine, and your browser is its window. Your data never leaves the computer. It runs the same function as Python and the command line, with the same defaults, so a run started here writes exactly the files described in Output Overview.
-
Variant calls in
A folder of VCF, MAF or simple text files. The format, samples, mutations and indels are reported before anything runs.
-
The right genome
Install reference genomes from the Workbench. It warns when the calls name a different assembly from the one chosen.
-
Follow the run
Live progress and log. Mutations the run had to skip are counted by reason.
-
Matrices out
Every matrix charted sample by sample, the PDF plots, and every file to download.
Install and start
The Workbench comes with SigProfilerMatrixGenerator. Download or clone the repository and start it from that folder. The only requirement is Python 3.9 or newer.
- If Python 3 is not installed, install it from python.org (or with Homebrew or conda).
- In the SigProfilerMatrixGenerator folder, double-click
launch_web.command. - The first time, macOS may say it cannot verify the file: right-click it, choose Open, then Open again. macOS remembers this choice.
- A Terminal window opens and sets up the Workbench's private Python environment. This takes a few minutes the first time and is skipped afterwards.
- The Workbench opens in your browser. Keep the Terminal window open while you use it; Quit in the Workbench's top bar stops it.
- If Python 3 is not installed, install it from
python.org. Tick Add
python.exe to PATH in the installer (the
pylauncher it installs also works). - In the SigProfilerMatrixGenerator folder, double-click
launch_web.bat. - If Windows SmartScreen appears, click More info, then Run anyway.
- A console window opens and sets up the Workbench's private Python environment. This takes a few minutes the first time and is skipped afterwards.
- The Workbench opens in your browser. Keep the console window open while you use it; Quit in the Workbench's top bar stops it.
In a terminal, in the SigProfilerMatrixGenerator folder:
The first start sets up the private Python environment (a few minutes),
then opens the Workbench in your browser. ./launch_web.sh also works in
Terminal on macOS.
The browser opens http://127.0.0.1:<port>/. A free port is picked on every
start, and the window that started the Workbench prints the address. Starting it
while it is already running prints the address of the running one instead of
starting a second.
What gets installed, and where
| What | Where | Removed by the uninstaller |
|---|---|---|
| A private Python environment with SigProfilerMatrixGenerator and its dependencies | .venv-dashboard, inside the SigProfilerMatrixGenerator folder |
yes |
| Run records: each run's settings, log and result | ~/.cache/sigprofilermatrixgenerator (macOS, Linux), %LOCALAPPDATA%\SigProfilerMatrixGenerator (Windows) |
yes |
| Reference genomes installed through the Workbench | SigProfilerMatrixGenerator/references/chromosomes/tsb, inside the SigProfilerMatrixGenerator folder (inside the installed package when started with pip), unless you set a Genome install folder |
only if you agree, since runs from Python or the command line in this folder use them too |
| Your matrices | each run's output folder | no |
| Downloaded packages, kept so later installs are quicker | uv's cache: ~/.cache/uv (macOS, Linux), %LOCALAPPDATA%\uv\cache (Windows); or pip's cache if pip was used |
no: uv cache clean (or pip cache purge) empties it |
Nothing else is installed: no system files, services or registry entries. The
launcher reinstalls into its environment only when setup.py or
pyproject.toml changes, for example after updating the repository.
The launcher installs with uv, which downloads
and installs packages in parallel and is much quicker than pip: on a laptop, a
reinstall from its cache takes seconds instead of half a minute. It uses the
uv already on your PATH if there is one; otherwise it first adds uv to the
Workbench's own environment. If uv cannot be added or cannot install, the
launcher says so and uses pip instead. To always use pip, for example behind a
network that only allows pip's configured package mirror, set the environment
variable SPMG_WEB_INSTALLER=pip.
Launch options
| Option | Meaning |
|---|---|
--no-launch |
Start without opening a browser tab |
--stop |
Stop the running Workbench, and any run it started, then exit |
--volume PATH |
Folder where reference genomes are installed (same as the CLI's --volume) |
--reinstall |
Force a fresh install into .venv-dashboard (launcher scripts only) |
./launch_web.sh --no-launch # start without opening a tab
./launch_web.sh --stop # stop it from another terminal
SigProfilerMatrixGenerator web --volume /data/genomes
Home
The Workbench opens on a page that introduces the tool: what it takes, what it gives back, and how it works, in five steps from reading the calls to plotting the matrices. Three buttons lead on:
- Start a new run opens the New run tab.
- Try the BRCA example (or the GRCh38 test set, whichever can run sooner) fills in a complete run. The line under it says how long it takes, or that its genome is installed first.
- Open results opens any folder SigProfilerMatrixGenerator wrote.
Once you have made runs, the last four are listed at the bottom of the page: a finished one opens its results, any other its progress. The Workbench's name, at the top left, always brings you back here.
Setting up a run
The New run tab has an Examples card and four numbered cards. Each number turns green once its card is complete, and Start run stays disabled until every card is.
Try an example first
Two examples that ship with SigProfilerMatrixGenerator can be filled in
with one click. Each writes to its own folder under
~/SigProfilerMatrixGenerator_example/.
| Example | Input | Genome |
|---|---|---|
| BRCA example | Simple text calls for four breast cancer genomes | GRCh37 |
| GRCh38 test set | 9,631 simulated substitutions in one genome (VCF) | GRCh38 |
The GRCh38 test set doubles as a check of your installation: its SBS96
matrix should match, channel for channel, the expected matrix that ships
with the package (scripts/Benchmark/GRCh38_bench_orig_96.txt). Tick
PDF plots to see SigProfilerPlotting's figures for it too. An example
whose genome is not installed yet installs it first (see
Reference genome).
1. Input
Click Choose the input folder, or paste a folder path and press Enter. Every file in the folder is read, so keep one cohort, in one format, per folder.
| Extension | Format | Samples |
|---|---|---|
.vcf |
VCF 4.x | One file per sample, named after the file |
.maf |
MAF | From the Tumor_Sample_Barcode column; one file can hold many samples |
.txt |
SigProfiler simple text | From the second column; one file can hold many samples |
As soon as a folder is chosen, the Workbench reads it and reports the format, the number of samples, the number of mutation calls (and how many are insertions or deletions) and the number of files, before anything runs. It also catches the usual mistakes:
- A single file instead of a folder. SigProfilerMatrixGenerator reads whole folders, so the Workbench names the folder to choose instead.
- Mixed formats. A folder holding both
.vcfand.maffiles is refused. Put each format in its own folder. - Other files. Files that are not mutation calls (a
README, say) are listed with a warning, since the run would try to read them too.
Files starting with __ or .DS are skipped, as SigProfilerMatrixGenerator
itself skips them. A folder that holds no files but has an input/ subfolder,
the layout of older projects, is read from input/.
2. Project
The project name becomes part of every file name, as in
BRCA.SBS96.all. It is filled in from the input folder's name until you type
your own.
The output folder is where the matrices go:
- Left blank, they go to an
outputfolder inside the input folder. - Set, they go straight into that folder.
Either way, each type of mutation found gets its own subfolder (SBS/,
DBS/, ID/), with run logs in logs/ and, when PDF plots is ticked,
SigProfilerPlotting's figures in plots/. SigProfilerMatrixGenerator also
keeps a copy of the input files it read, in an input/ folder: inside the
input folder by default, or inside the output folder when one is set.
An output folder that already holds results
SigProfilerMatrixGenerator does not clear an output folder before writing to it. A second run into the same folder rewrites the files it makes and leaves the rest: plots from a run that drew them, ID89 and ID476 from a run that asked for them, everything from a run that failed. Those files would then sit beside the new ones as if they belonged to them.
So when the output folder already holds results, the Project card says so and the run does not start until you choose one of:
- Use a new folder, which fills in the next free name beside it
(
BRCA_example_2,BRCA_example_3, ...). - Replace the earlier results, which deletes them when the run starts. Only what SigProfilerMatrixGenerator wrote is deleted: its matrices, plots, strand bias tables, logs and its copies of the input. Anything else in the folder stays. This cannot be undone. It is not offered when your input calls are inside the output folder.
3. Reference genome
Choose the assembly your variants were called against. The card says whether it is installed:
- Install it now starts the download in the background. The genome is large (about 3 GB for a human assembly) and is downloaded once.
- With If it is not installed yet, install it when the run starts ticked (the default), a run installs a missing genome as its first step.
Getting the genome right matters. Every mutation is checked against the
genome's reference base, so calls made on GRCh37 and run against GRCh38 or
CHM13-T2T mostly fail that check, and the run stops once more than 30% of
mutations are skipped. When the calls name their assembly (a VCF's
##reference or ##assembly header, the genome column of simple text, or a
MAF's NCBI_Build), the card warns if a different genome is chosen and offers
to switch. The BRCA example, for instance, names GRCh37. Calls that do not name
an assembly are not checked.
Installed genomes are also listed in the sidebar; clicking one selects it. The status describes the genome install folder the run will use: the one set under Advanced in the Matrices card if there is one, otherwise the folder the Workbench was started with. Changing that field (press Enter, or use Browse) updates the status straight away.
Note
The genome card only checks that each of the genome's files is present. A run checks the files against their expected checksums before it starts. If they do not match, the run downloads the genome again when automatic install is ticked; otherwise it stops and says the files do not match.
4. Matrices
SigProfilerMatrixGenerator writes the standard matrices for each type of mutation present in your calls: SBS for single base substitutions, DBS for doublet base substitutions and ID for small insertions and deletions. A cohort with no doublet substitutions, for example, gets no DBS matrices. The options add to the standard set:
| Option | What it does | Python / CLI equivalent |
|---|---|---|
| PDF plots | SigProfilerPlotting draws every SBS, DBS and ID matrix the run writes, one page per sample, into plots/. Adds time for large cohorts |
plot=True / --plot |
| Exome only | Keeps mutations inside the exome (with a 100 bp cushion). Files end in .exome |
exome=True / --exome |
| Strand bias test | Tests transcriptional strand bias for SBS24, SBS384 and SBS6144; results go to TSB/ |
tsb_stat=True / --tsb_stat |
| ID89, ID476 | Adds the Koh et al. (2025) indel matrices; ID83 is unchanged | indel_contexts=["89", "476"] / --indel_contexts 89 476 |
| Region BED file (Advanced) | Keeps only these regions; the file needs a header line. Files end in .region |
bed_file= / --bed_file |
| Genome install folder (Advanced) | Where reference genomes are installed | volume= / --volume |
Calls without insertions or deletions, such as the BRCA example, give no ID matrices: no ID83, and ID89 and ID476 come out all zeros. The card says so when ID89 or ID476 is ticked for such calls.
See ID89 and ID476 for the indel classifications, and Output Overview for every file a run writes.
Click Start run. The summary beside the button shows the project, the number of samples and the genome the run will use.
Following a run
Starting a run opens the Monitor tab:
- Progress in three steps: checking the reference genome (and installing it if needed), generating the matrices, and writing the summary. A genome install shows as a single step.
- Details: project, genome, input folder, output folder and start time.
- Log: the run's own output as it is written. Untick follow to scroll back while it runs.
- Stop ends the run. Files already written stay where they are.
When the run finishes, Open results shows its matrices. If it fails, the reason is shown above the log, and the full traceback is in the log.
SigProfilerMatrixGenerator skips mutations it cannot place (a reference base
that does not match the genome, a position past the end of a chromosome, and
so on) and lists each one in its own log, in the output folder's logs/, not
in the log shown here. When a run skipped any, the Monitor tab counts them by
reason and names that log file.
A run that fails may still have written matrices or plots before it stopped. The Monitor tab says so: do not use them. Run again into the same folder and choose Replace the earlier results, or delete the failed run.
Each run is a separate process, so a long run never slows the page, and runs keep their records after the Workbench is restarted. Every run, past and present, is listed in the sidebar under Runs; the Monitor tab shows a count of the ones still in progress.
Removing and deleting runs
A finished run has two buttons, on its row in the Runs list (shown when you point at it) and in the Monitor tab:
| Button | What it does |
|---|---|
| × (Remove from list) | Takes the run off the list. Its results stay on disk, and Undo in the message that follows brings it back. |
| Bin (Delete) | Deletes the run and, after asking, its results: what SigProfilerMatrixGenerator wrote in its output folder. Other files in that folder stay, and the folder itself goes only when nothing else is left in it. This cannot be undone: the files do not go to the Trash or Recycle Bin. |
If a later run wrote to the same output folder, deleting the earlier run removes only its entry and leaves the files alone, since they cannot be told apart. A genome install can only be removed from the list; that never uninstalls the genome. A run still in progress has neither button: stop it first.
Exploring results
Open a finished run from the Monitor tab or from Home, or click Open a
results folder in the sidebar and choose the folder a run wrote its matrices
into (the one holding the SBS, DBS and ID subfolders). That includes
folders written earlier by the Python function or the command line. It only
reads the folder.
This is not the Output folder field of a new run, which sets where a run will write.
The Results tab shows:
- Tiles: the number of contexts and matrix files, the number of samples, and the project.
- Matrices: one button per context found (SBS96, DBS78, ID83, and so on), grouped into SBS, DBS and ID.
- The profile of the selected context, for one sample at a time:
- choose the sample from the list;
- switch between Percent (the default, for every type of matrix), Counts and Proportion. Percent and proportion rescale each sample to its own total, which makes samples with different mutation burdens comparable;
- the ? button explains what the chart shows and how to read it;
- Download saves the matrix file;
- the camera button above the chart saves the figure as SVG, named after the project, context and sample.
- PDF plots: the figures SigProfilerPlotting drew, when the run had PDF plots ticked. Open shows a PDF in a new browser tab; Download saves it.
- Matrix files: every matrix in the folder, with its size and a download link.
Above the matrices, the Results tab warns about files that should not be read as one run's results:
- From an earlier run. For a folder written by runs started in the Workbench, matrices and plots older than the latest run there are marked "earlier".
- Older than its matrix. A PDF plot older than the matrix it shows was drawn by an earlier run, so it may not match. This works for folders written from the command line too.
- Empty. A matrix whose counts are all zero (ID89 for calls without indels, say) is marked empty and is not drawn.
- From a failed run. When the newest files come from a run that failed.
Charts are drawn by SigProfilerPlotting's own renderers, the same ones its dashboard uses.
Requirements for charts
Charts need SigProfilerPlotting 1.5.0 or later. With an older version the Results tab still lists the matrices and lets you download them, and says why the charts are missing. To upgrade:
SBS1536 and SBS4608 use a multi-panel layout that the Results tab does not draw. Download the matrix and open it in the SigProfilerPlotting dashboard to view it.
Themes
The menu in the top bar switches between four themes: UC San Diego, UAlbany and SigProfilerSuite are light, Night is dark. The choice is remembered by your browser. Until one is chosen, the Workbench follows your system's light or dark setting. Charts stay on a white panel in every theme, so the standard SigProfiler colours read the same everywhere.
Stopping the Workbench
Any of these stops the Workbench, together with any run still in progress:
- the Quit button in the top bar, which asks you to confirm and says if a run is still in progress;
./launch_web.sh --stop(orlaunch_web.bat --stop, orSigProfilerMatrixGenerator web --stop) from another terminal;- Ctrl+C in the terminal the Workbench was started from.
Matrices already written stay where they are.
Uninstall
The Workbench installs nothing outside the places listed under What gets installed, and where.
With a double-click
- Click Quit in the Workbench. (The uninstaller refuses to run while the Workbench or one of its runs is still going.)
- In the SigProfilerMatrixGenerator folder, double-click
uninstall_web.command(macOS) oruninstall_web.bat(Windows). On Linux, run./uninstall_web.sh. The same first-time prompts as for starting may appear: right-click and Open on macOS; More info, then Run anyway on Windows. -
It lists what it will remove and asks before doing anything:
SigProfilerMatrixGenerator Workbench uninstaller ------------------------------------------------ This removes: - the Python environment /path/to/SigProfilerMatrixGenerator/.venv-dashboard (600M) - the records of 3 run(s) in ~/.cache/sigprofilermatrixgenerator (settings and logs, not matrices) It keeps your matrices (each run's output folder) and this folder (/path/to/SigProfilerMatrixGenerator). Remove them? Type y and press Enter: -
Type y and press Enter.
-
If reference genomes were installed in this folder, it then lists them and asks about them separately, since runs from Python or the command line in this folder use them too and each takes a while to download again:
Reference genomes installed in this folder: GRCh37 GRCh38 (5.8G) in /path/to/SigProfilerMatrixGenerator/SigProfilerMatrixGenerator/references/chromosomes/tsb Runs from Python or the command line in this folder use them too, and each one takes a while to download again. Remove these genomes too? Type y and press Enter, or just Enter to keep them:Press Enter to keep them, or type y to remove them too. Only the genomes go: the files that ship with SigProfilerMatrixGenerator stay.
To remove the rest, delete the SigProfilerMatrixGenerator folder and, if you no
longer need them, your matrices. Double-clicking launch_web.command or
launch_web.bat again later sets everything up anew.
From a terminal, ./uninstall_web.sh --yes (or uninstall_web.bat --yes)
removes the environment and run records without asking and keeps the genomes;
add --genomes to remove the genomes too.
By hand
- Click Quit in the Workbench.
- Delete the
.venv-dashboardfolder inside the SigProfilerMatrixGenerator folder. - Delete the run records:
~/.cache/sigprofilermatrixgeneratoron macOS and Linux,%LOCALAPPDATA%\SigProfilerMatrixGeneratoron Windows. They hold each run's settings and log, not its matrices. - If you no longer need them, delete the genome folders (one per genome) in
SigProfilerMatrixGenerator/references/chromosomes/tsb.
Your matrices stay in each run's output folder.
Security
The Workbench is meant for one person on their own computer. It listens only
on this machine (127.0.0.1) and has no login, so it protects itself in other
ways:
- It answers only requests addressed to this machine by name (
127.0.0.1orlocalhost), which stops a website from reaching it through DNS tricks. - Anything that acts (starting or stopping a run, installing a genome, opening a file picker, quitting) must come from the Workbench's own page: from exactly its address and port, and carrying a secret written into that page when it starts. A website, or a page served by another program on this computer, can send requests to the Workbench but cannot read its page, so it cannot supply the secret.
- Every other request only reads (the page itself, run progress, matrix files), and your browser does not let other websites see the replies.
The Workbench can read any folder you can, and starts processes on your behalf, so do not expose it on a network.
Troubleshooting
"Python 3 was not found." Install Python 3.9 or newer (see Install and start), then double-click the launcher again.
macOS says the file cannot be opened, or is from an unidentified developer. Right-click the file, choose Open, then Open again.
Windows protected your PC. Click More info, then Run anyway.
The genome shows as not installed.
Install it from the genome card, or from a terminal:
SigProfilerMatrixGenerator install GRCh38. If your genomes live elsewhere,
set the genome install folder under Advanced and press Enter, or start the
Workbench with --volume. If the SIGPROFILERMATRIXGENERATOR_VOLUME
environment variable is set, it takes precedence over both.
The run failed: "More than 30% of mutations were skipped". Look at the reasons the Monitor tab lists. If most are "The reference base does not match the reference genome", the calls were made against a different genome from the one chosen: choose the genome they were called against and run again.
The PDF plots do not match the matrices. They were drawn by an earlier run into the same folder; the Results tab marks them. Run again with PDF plots ticked, choosing Replace the earlier results, or use a new folder.
There is no ID83, only ID89 and ID476 (all zeros). The calls hold no insertions or deletions. The Input card shows how many there are.
The folder picker does not open (Linux).
The picker needs zenity, kdialog or a Python with Tkinter. Without them,
paste the path into the box under the button instead.
The uninstaller says the Workbench is still running.
Click Quit in the Workbench (or run ./launch_web.sh --stop, or
launch_web.bat --stop), then run it again.
The page stopped responding after a restart. Each start uses a new address. Use the address the launcher printed, or run the launcher again: if the Workbench is already running, it prints that address.
Charts are missing on the Results tab. Upgrade SigProfilerPlotting to 1.5.0 or later (see above).
Where are the run records?
In ~/.cache/sigprofilermatrixgenerator/jobs on macOS and Linux, and
%LOCALAPPDATA%\SigProfilerMatrixGenerator\jobs on Windows. Each run's folder
holds its settings, its log and its result. The matrices themselves are only
in the run's output folder.