# SpikeForge for biologists

SpikeForge creates research controls by editing selected alignment records in a
copy of an existing BAM. It is intended for bioinformatics pipeline and
variant-caller testing. It is **not** a clinical diagnostic, treatment system,
or substitute for wet-lab and clinical validation.

## Start the local application on Windows

1. Extract the complete SpikeForge release ZIP.
2. Install Python 3.10 or newer if it is not already installed.
3. Double-click **Launch SpikeForge.cmd**.
4. Choose the folder containing the BAM files you want SpikeForge to access.
5. Use the browser page that opens. Keep the SpikeForge terminal window open
   until the work is finished.

The browser is the user interface, but the SpikeForge engine and all BAM files
remain on the same computer. Nothing is uploaded to the public documentation
website.

## Choose a local BAM or an HTTPS download link

The **Single BAM** page offers two input sources:

- **Local BAM path** — browse inside the working folder selected when
  SpikeForge started. This is recommended for large BAMs and shared laboratory
  drives.
- **HTTPS download link** — paste an anonymous, direct-download link.
  SpikeForge downloads the BAM into the selected working folder, verifies that
  it is a real BAM, records its SHA-256 checksum, and only then enables it as an
  input. Processing and every output still happen locally.

A normal Dropbox shared-file link can work when anonymous download is enabled.
A private Dropbox `/home/...` page, a folder-browsing page, or any link that
requires a browser login is not a downloadable BAM. For those links, sync or
download the folder first and choose the resulting local path.

Signed URLs may contain secret query parameters. SpikeForge does not display or
record those parameters in its job results. Use only links you are authorised
to download.

## Add ten EGFR T790M-supporting alignment records

In **Single BAM**:

1. Choose a local input BAM or download one from an HTTPS link, then choose a
   different local output BAM path.
2. Choose **EGFR T790M** and the BAM's genome build:
   - GRCh37 / hg19: chromosome 7, position 55,249,071, C>T
   - GRCh38 / hg38: chromosome 7, position 55,181,378, C>T
3. Choose **Add ALT reads**, enter `10`, and enable **Require exact count**.
4. Run the preflight. It reports baseline ALT reads, eligible depth, the
   planned number of edits, projected ALT count/VAF, and whether exactly ten is
   feasible.
5. Run the job only after the preflight matches the intended experiment.

The preset coordinates are based on
[NCBI ClinVar VCV000016613](https://www.ncbi.nlm.nih.gov/clinvar/variation/16613/).
Always select the BAM's actual reference build.

Here, a “read” means one BAM alignment record that will be edited from the
reference allele to the ALT allele. It does not automatically mean one unique
DNA molecule. SpikeForge keeps mates, UMI families, and duplicate families
coherent, so some data sets cannot produce an arbitrary exact count. With
**Require exact count** enabled, such a job fails instead of quietly producing
a nearby number.

## Choose the intended target

- **Add ALT reads** edits the requested number of additional eligible
  alignment records.
- **Final ALT reads** subtracts pre-existing ALT support and aims for the
  requested total in the output.
- **VAF** retains the original allele-fraction targeting workflow.

For example, if an input already has three ALT-supporting reads:

- “Add 10” aims for 13 total ALT reads.
- “Final 10” aims to edit seven additional reads.

## Batch process a CSV

Use **Batch CSV** and start from `examples/web_batch_template.csv`. Paths may be
relative to the input/output folders chosen in the application. Multiple rows
may point to the same input BAM to add several mutations to one output.

Each row must provide exactly one input source:

- `input_bam` — a local absolute path or a path relative to the input root; or
- `input_url` — an anonymous direct HTTPS download link.

Common columns:

- `sample`
- `output_bam`
- `genome_build`
- `gene`
- `mutation`
- `chrom`, `pos`, `ref`, `alt`
- `target_mode`
- `target_value`
- `require_exact_count`

For the built-in EGFR preset, use `gene=EGFR`, `mutation=T790M`, and set
`genome_build` to `GRCh37` or `GRCh38`. For another mutation, provide
`chrom`, `pos`, `ref`, and `alt`.

Choose **Prepare & validate**. Linked BAMs are downloaded to the working folder
before the application validates every row, local path, BAM header, output
collision, and disk-space estimate. No BAM output is created until preparation
and validation finish. A failed processing sample is isolated and reported;
completed samples remain available.

## What the output contains

A successful BAM job produces:

- the modified BAM;
- a BAI index when the input is coordinate-sorted;
- a truth VCF;
- an edit ledger;
- planted-read names and record digests;
- a machine-readable manifest;
- record-by-record verification and realism-audit results.

SpikeForge verifies the private candidate output before it is presented as a
completed control. Keep the truth folder with the BAM so the experiment remains
auditable.

## Interpretation limits

BAM editing tests downstream processing from the aligned-read stage. It does
not test extraction, library preparation, sequencing, or the production
aligner. To validate the complete workflow, create FASTQ-level controls and run
them through the production pipeline, followed by independently designed
wet-lab validation.