CLI Referenceο
Auto-generated: All command output below is captured live during documentation build from the actual
sirnaforgeCLI.
This reference shows each command with its real --help output and working examples.
Help & Versionο
Main Helpο
Usage: sirnaforge [OPTIONS] COMMAND [ARGS]...
siRNAforge - siRNA design toolkit for gene silencing
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --install-completion Install completion for the current shell. β
β --show-completion Show completion for the current shell, to β
β copy it or customize the installation. β
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Commands βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β search Search transcript references and optionally fetch sequences. β
β workflow Run the end-to-end workflow: transcripts β siRNA design β β
β off-target. β
β offtarget Run off-target analysis on pre-designed siRNA candidates. β
β zfn Evaluate a ZFN pair and run exhaustive genome-wide off-target β
β search (EXPERIMENTAL). β
β design Design siRNA candidates from a transcript FASTA file. β
β validate Validate a FASTA file and report basic statistics. β
β version Show CLI version and author information. β
β config Print the default design parameter values. β
β cache Inspect and clear the unified reference cache. β
β sequences Manage siRNA sequences and metadata β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Versionο
ββββββββ Version Info ββββββββ
β 𧬠siRNAforge Toolkit β
β Version: 0.6.0 β
β Author: Austin S. Hovland. β
ββββββββββββββββββββββββββββββ
workflowο
Run complete siRNA design from gene query to scored candidates.
Helpο
Usage: sirnaforge workflow [OPTIONS] {gene_query}
Run the end-to-end workflow: transcripts β siRNA design β off-target.
This is the main orchestration command. It resolves transcriptome and miRNA
reference policies, designs candidates, and then runs off-target analysis on
the selected top candidates.
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * gene_query <str> Gene name or ID to analyze [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --input-fasta <str> Local path or β
β remote URI to an β
β input FASTA file β
β (http/https/ftp) β
β --output-dir -o <path> Output directory β
β for all workflow β
β results β
β [default: β
β sirna_workflow_oβ¦ β
β --database -d <str> Database to β
β search (ensembl, β
β refseq, gencode) β
β [default: β
β ensembl] β
β --design-mode <str> Design mode: β
β sirna (default), β
β mirna β
β (miRNA-biogenesiβ¦ β
β or zfn β
β (EXPERIMENTAL) β
β [default: sirna] β
β --zfn-subfingerβ¦ <str> ZFN sub-finger β
β mutation β
β allowance. β
β Repeatable β
β format: β
β scope:max_mutatiβ¦ β
β scope can be β
β subfinger index β
β (e.g. 2), '*' for β
β default β
β per-subfinger, or β
β 'overall' for β
β global budgets. β
β Use 'mismatch' as β
β a shorthand alias β
β for β
β 'substitution'. β
β --zfn-max-mismaβ¦ <int range> Convenience β
β [x>=0] option equivalent β
β to β
β --zfn-subfinger-β¦ β
β '*:<N>:mismatch'. β
β --zfn-max-substβ¦ <int range> Convenience β
β [x>=0] option equivalent β
β to β
β --zfn-subfinger-β¦ β
β 'overall:<N>:subβ¦ β
β --zfn-left-halfβ¦ <str> Left ZFN β
β half-site β
β sequence (9-18 β
β bp, IUPAC β
β allowed). β
β Required for β
β --design-mode β
β zfn. β
β --zfn-right-halβ¦ <str> Right ZFN β
β half-site β
β sequence (9-18 β
β bp, IUPAC β
β allowed). β
β Required for β
β --design-mode β
β zfn. β
β --zfn-search-spβ¦ <str> Genome reference β
β key or local β
β FASTA path for β
β ZFN off-target β
β search space. β
β Built-in keys: β
β ensembl_human_hgβ¦ β
β ensembl_mouse_grβ¦ β
β ensembl_rat_grcrβ¦ β
β ensembl_macaque_β¦ β
β Default: β
β ensembl_human_hgβ¦ β
β when β
β --design-mode β
β zfn. β
β --zfn-search-spβ¦ <str> Optional β
β persisted β
β search-space β
β index bundle path β
β for indexed ZFN β
β backends β
β (currently β
β fm_index; β
β fm_index is β
β experimental on β
β large β
β references). β
β --zfn-search-baβ¦ <exhaustive_pyt Half-site search β
β hon|pyahocorasi backend: β
β ck|fm_index> pyahocorasick β
β (default), β
β exhaustive_python β
β (baseline), or β
β fm_index β
β (experimental). β
β [default: β
β pyahocorasick] β
β --zfn-algorithm <homology|conse ZFN off-target β
β rved_g|zfn_v2> scoring β
β algorithm: β
β homology, β
β conserved_g, or β
β zfn_v2 (default). β
β [default: zfn_v2] β
β --zfn-dimer-mode <heterodimer_on Dimer mode: β
β ly|include_homo heterodimer_only β
β dimers> (default) or β
β include_homodimeβ¦ β
β [default: β
β heterodimer_only] β
β --zfn-spacer-leβ¦ <str> Comma-separated β
β allowed spacer β
β lengths between β
β half-sites β
β (default: 5,6,7). β
β [default: 5,6,7] β
β --zfn-max-mismaβ¦ <int range> Max mismatches β
β [0<=x<=6] per half-site in β
β exhaustive β
β genomic search β
β (default: 2). β
β [default: 2] β
β --cores <int range> Total CPU core β
β [x>=1] budget for β
β workflow β
β execution. ZFN β
β sharding and β
β workflow parallel β
β stages derive β
β from this. β
β [env var: β
β SIRNAFORGE_CORES] β
β --zfn-annotation <str> Optional GTF/GFF β
β annotation file β
β for ZFN β
β off-target region β
β classification. β
β --top-n -n <int range> Cap how many β
β [x>=1] top-ranked β
β candidates are β
β reported β
β (default: no cap, β
β report all). β
β Screening and β
β enumeration β
β always cover β
β every candidate, β
β so this only β
β truncates the β
β reported set -- β
β leave it unset to β
β keep the full β
β design space. β
β --species <str> Comma-separated β
β canonical species β
β identifiers. This β
β single parameter β
β drives all β
β off-target β
β analysis: miRNA β
β database lookups β
β (default: 7 β
β species) and β
β transcriptome β
β fetching from β
β Ensembl (default: β
β 4 species). β
β Override specific β
β layers with β
β --mirna-species β
β or β
β --transcriptome-β¦ β
β Supported: human, β
β mouse, macaque, β
β rat, chicken, β
β pig, rhesus β
β [default: β
β chicken,pig,rat,β¦ β
β --query-species <str> Organism the β
β TARGET β
β transcripts β
β belong to, which β
β decides which β
β species' hits are β
β on-target and β
β whose alignment β
β must succeed β
β before candidates β
β can be scored β
β after screening. β
β --species is an β
β unordered set of β
β genomes to screen β
β AGAINST and never β
β sets this. β
β Defaults to the β
β organism the β
β gene-query β
β database serves β
β (human), which is β
β also the species β
β of the default β
β transcriptome; β
β set it when β
β designing against β
β an input FASTA β
β from another β
β organism. β
β --mirna-db <str> miRNA reference β
β database to use β
β for seed analysis β
β [default: β
β mirgenedb] β
β --mirna-species <str> Override miRNA β
β species β
β identifiers β
β (comma-separatedβ¦ β
β When omitted, β
β automatically β
β maps from β
β --species. Use β
β this for surgical β
β control of miRNA β
β database queries. β
β --transcriptomeβ¦ <str> Override or β
β extend β
β transcriptome β
β references for β
β off-target β
β analysis. β
β Accepts: local β
β file, HTTP(S) β
β URL, or β
β pre-configured β
β source (e.g., β
β 'ensembl_human_cβ¦ β
β When omitted, β
β automatically β
β fetches Ensembl β
β cDNA for species β
β selected via β
β --species. Custom β
β FASTA files are β
β cached and β
β indexed β
β automatically. β
β Use this to add β
β novel sequences β
β (e.g., synthetic β
β contigs) to the β
β default set. β
β --transcriptomeβ¦ <str> Filter β
β transcriptome to β
β reduce size and β
β memory β
β requirements. β
β Comma-separated β
β filter names: β
β 'protein_coding' β
β (only β
β protein-coding β
β genes), β
β 'canonical_only' β
β (only canonical β
β isoforms). β
β Example: β
β --transcriptome-β¦ β
β protein_coding,cβ¦ β
β Filtered versions β
β are cached β
β separately with β
β automatic β
β indexing. β
β --offtarget-indβ¦ <str> Comma-separated β
β overrides for β
β genome indices β
β used in β
β off-target β
β analysis. Format: β
β human:/abs/path/β¦ β
β When provided, β
β overrides β
β cached/default β
β genome β
β references. β
β --gc-min <float range> Minimum GC β
β [0.0<=x<=100.0] content β
β percentage β
β [default: 30.0] β
β --gc-max <float range> Maximum GC β
β [0.0<=x<=100.0] content β
β percentage β
β [default: 60.0] β
β --length -l <int range> siRNA length in β
β [19<=x<=23] nucleotides β
β [default: 21] β
β --modifications -m <str> Chemical β
β modification β
β pattern β
β (standard_2ome, β
β minimal_terminal, β
β maximal_stabilitβ¦ β
β none) β
β [default: β
β standard_2ome] β
β --overhang <str> Overhang sequence β
β (dTdT for DNA, UU β
β for RNA) β
β [default: dTdT] β
β --skip-off-targβ¦ Skip off-target β
β analysis (faster) β
β --snp <str> Variant β
β identifier(s) for β
β SNP β
β targeting/avoidaβ¦ β
β Accepts rsID β
β (rs12345), β
β coordinate β
β (chr17:7577121:Gβ¦ β
β or HGVS β
β (NM_000546.6:c.2β¦ β
β Can be specified β
β multiple times. β
β All variants must β
β be on GRCh38 β
β assembly. β
β --snp-file <path> VCF file β
β containing β
β variants for β
β targeting/avoidaβ¦ β
β Preferably β
β bgzip-compressed β
β with tabix index β
β (.vcf.gz + .tbi) β
β for performance. β
β Variants are β
β filtered by β
β --min-af and β
β --clinvar-filterβ¦ β
β --variant-mode <target|avoid|b How to handle β
β oth> variants in siRNA β
β design: 'avoid' = β
β exclude β
β candidates β
β overlapping β
β variants β
β (default), β
β 'target' = design β
β siRNAs β
β specifically β
β targeting variant β
β alleles, 'both' = β
β generate β
β candidates for β
β both reference β
β and alternate β
β alleles. β
β [default: avoid] β
β --min-af <float range> Minimum allele β
β [0.0<=x<=1.0] frequency β
β threshold for β
β variant β
β inclusion. β
β Variants with AF β
β below this value β
β are excluded β
β (default: 0.01 = β
β 1%%). β
β [default: 0.01] β
β --clinvar-filteβ¦ <str> Comma-separated β
β ClinVar clinical β
β significance β
β levels to β
β include. Default: β
β 'Pathogenic,Likeβ¦ β
β pathogenic'. β
β Other options: β
β 'Benign', 'Likely β
β benign', β
β 'Uncertain β
β significance'. β
β [default: β
β Pathogenic,Likely β
β pathogenic] β
β --variant-assemβ¦ <str> Reference genome β
β assembly for β
β variants (only β
β GRCh38 supported) β
β [default: GRCh38] β
β --verbose -v Enable verbose β
β output β
β --log-file <path> Path to β
β centralized log β
β file (overrides β
β SIRNAFORGE_LOG_Fβ¦ β
β env) β
β --nextflow-dockβ¦ <str> Override the β
β Docker image β
β passed to β
β Nextflow β
β (default: β
β ghcr.io/austin-sβ¦ β
β [env var: β
β SIRNAFORGE_NEXTFβ¦ β
β --max-hits <int range> Cap off-target β
β [x>=1] hits retained per β
β candidate per β
β species (default: β
β exhaustive, no β
β cap). Set a lower β
β value (e.g. β
β 10000) to speed β
β up analysis of β
β large gene β
β families at the β
β cost of censoring β
β per-species hit β
β counts. β
β --max-off-targeβ¦ <int range> Reject a β
β [x>=0] candidate above β
β this many genuine β
β off-target sites β
β (default: 3). β
β Counts only hits β
β left after β
β on-target, β
β ortholog and β
β repeat β
β classification. β
β Unlike --max-hits β
β this changes the β
β PASS/EXCESS_OFF_β¦ β
β gate, not how β
β many hits are β
β recorded. β
β --json-summary --no-json-summβ¦ Write β
β logs/workflow_suβ¦ β
β (disable to skip β
β JSON output) β
β [default: β
β json-summary] β
β --help Show this message β
β and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Note
The workflow command searches for gene transcripts, designs siRNA candidates, scores them using thermodynamic analysis, and outputs ranked results.
ZFN Notesο
Warning
EXPERIMENTAL. --design-mode zfn runs the experimental ZFN arm, which has known unfixed defects
(half-site orientation handling, FokI seed-region weighting, off-target region classification,
inverted worst_site_score/best_offtarget_score exports) tracked in
#82. Do not use ZFN output for any decision
without independent validation. See ZFN Module Guide.
ZFN activity/off-target evaluation now has a dedicated command: sirnaforge zfn.
Use the workflow command for transcript-centric siRNA/miRNA runs.
Input Sources & Transcriptome Referencesο
siRNAforge accepts complementary inputs when you need to bypass gene search or control the reference used for transcriptome off-target analysis:
--input-fastareplaces the transcript retrieval step. Point it at a local FASTA file, HTTP(S) URL, or FTP location. The positional argument (GENE_QUERY) still names the outputs, while the workflow designs guides from the supplied sequences. When you pass--input-fastawithout--transcriptome-fasta, transcriptome off-target analysis is disabled (design-only mode).--transcriptome-fastaselects the dataset used for transcriptome off-target analysis. It accepts local paths, remote URLs, or presets such asensembl_human_cdnaandensembl_mouse_cdna(seesirnaforge cache --info). Provide this flag to re-enable transcriptome off-target analysis when running from a custom FASTA.--offtarget-indicesoverrides the genome indices used for Nextflow/BWA-MEM2 with explicitspecies:/path/to/index_prefixentries. When present, these drive the set of species processed by the off-target pipeline.
Passing both flags is common: the input FASTA feeds the design engine, while the transcriptome FASTA controls which reference is indexed for the Nextflow stage. Remote resources are cached under ~/.cache/sirnaforge/ and reused automatically.
Design-only mode is a deliberate cost guard, not an oversight: resolving the built-in defaults means downloading and indexing four multi-gigabyte Ensembl cDNA references (human, mouse, rat, macaque). Supplying your own sequences never triggers that implicitly. Library callers get the same policy β run_sirna_workflow(input_fasta=...) is design-only unless you pass transcriptome_fasta=... or opt in with allow_transcriptome_with_input_fasta=True.
--skip-off-targets disables all reference-based screening for the run: no transcriptome reference is resolved, downloaded or indexed, the Nextflow off-target stage does not run, and repeat-element detection is skipped as well. Repeat detection scans guides against the query speciesβ cDNA reference, so it cannot run without the very download the flag exists to avoid; logs/workflow_summary.json reports it as repeat_summary.status = "skipped" with reason = "user_disabled", and candidates keep repeat_flagged = false. Drop --skip-off-targets (optionally with --transcriptome-fasta) whenever you need repeat verdicts.
Rows inside off_target/results/*/analysis.tsv and the aggregated combined_offtargets.tsv include a species column so you can filter hits directly. Aggregated summaries collapse those values into human vs other buckets, exposing hits_per_species, human_hits, and other_species_hits in combined_summary.json plus the workflow console output. The workflow also records the resolved reference decision in logs/workflow_summary.json (reference_summary.transcriptome) so each run documents whether the transcriptome reference was disabled, defaulted, or explicitly provided.
searchο
Search gene databases and retrieve transcript sequences.
Helpο
Usage: sirnaforge search [OPTIONS] {query}
Search transcript references and optionally fetch sequences.
This command queries Ensembl/RefSeq/Gencode (depending on flags) for a gene
or transcript identifier. When sequences are fetched, it writes them to a
FASTA file and can optionally also emit a canonical-only FASTA.
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * query <str> Gene ID, gene name, or transcript ID to search for β
β [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --output -o <path> Output FASTA file β
β for transcript β
β sequences β
β [default: β
β transcripts.fasta] β
β --database -d <str> Database to search β
β (ensembl, refseq, β
β gencode) β
β [default: ensembl] β
β --all -a Search all databases β
β --fallback --no-fallback Enable automatic β
β fallback to other β
β databases if access β
β is blocked β
β [default: fallback] β
β --no-sequence Skip sequence β
β retrieval (metadata β
β only) β
β --canonical-only Extract only β
β canonical isoforms β
β --extract-canonical --no-extract-canoβ¦ Automatically β
β extract canonical β
β isoforms to separate β
β file β
β [default: β
β extract-canonical] β
β --types -t <str> Comma-separated list β
β of transcript types β
β to include (e.g., β
β protein_coding,lncRβ¦ β
β [default: β
β protein_coding,lncRβ¦ β
β --exclude-types <str> Comma-separated list β
β of transcript types β
β to exclude β
β [default: β
β nonsense_mediated_dβ¦ β
β --verbose -v Enable verbose β
β output β
β --help Show this message β
β and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
designο
Design siRNA/miRNA candidates from FASTA sequences.
Helpο
Usage: sirnaforge design [OPTIONS] {input_file}
Design siRNA candidates from a transcript FASTA file.
Outputs a TSV/CSV-like table of candidates, optionally including secondary
structure scoring, off-target checks, and chemical modification annotations.
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * input_file <file> Input FASTA file containing transcript β
β sequences β
β [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --output -o <path> Output file for siRNA β
β candidates β
β [default: β
β sirna_results.tsv] β
β --design-mode <str> Design mode: sirna β
β (default) or mirna β
β (miRNA-biogenesis-awarβ¦ β
β For ZFN use 'sirnaforge β
β zfn'. β
β [default: sirna] β
β --length -l <int range> siRNA length in β
β [19<=x<=23] nucleotides β
β [default: 21] β
β --top-n -n <int range> [x>=1] Cap how many top-ranked β
β candidates are reported β
β (default: no cap, β
β report all). All β
β candidates are β
β generated and screened β
β regardless. β
β --gc-min <float range> Minimum GC content β
β [0.0<=x<=100.0] percentage β
β [default: 30.0] β
β --gc-max <float range> Maximum GC content β
β [0.0<=x<=100.0] percentage β
β [default: 60.0] β
β --max-poly-runs <int range> [x>=1] Maximum consecutive β
β identical nucleotides β
β [default: 3] β
β --genome-index <path> Genome index for β
β off-target analysis β
β --snp-file <path> VCF file with SNPs to β
β avoid β
β --skip-structure Skip secondary β
β structure prediction β
β (faster) β
β --skip-off-targets Skip off-target β
β analysis (faster) β
β --modifications -m <str> Chemical modification β
β pattern (standard_2ome, β
β minimal_terminal, β
β maximal_stability, β
β none) β
β [default: β
β standard_2ome] β
β --overhang <str> Overhang sequence (dTdT β
β for DNA, UU for RNA) β
β [default: dTdT] β
β --verbose -v Enable verbose output β
β --help Show this message and β
β exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Example: Design from Sample Dataο
ββββββββββββββββ Configuration ββββββββββββββββ
β 𧬠siRNAforge Toolkit β
β Design Mode: sirna β
β Input: ../examples/sample_transcripts.fasta β
β Output: /tmp/sirna_example.csv β
β Length: 21 nt β
β GC range: 30.0%-60.0% β
β Reported candidates: 5 β
β Modifications: standard_2ome β
β Overhang: dTdT β
βββββββββββββββββββββββββββββββββββββββββββββββ
2026-09-08 14:50:12,511 - sirnaforge.models.sirna - INFO - siRNA candidates schema validation passed for 2051 candidates
β Ό Saving results...
π Design Summary
βββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Metric β Value β
βββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Input Sequences β 3 β
β Total Candidates β 2051 β
β Filtered Candidates β 535 β
β Top Candidates β 5 β
β Processing Time β 1.64s β
β Best Score β 89.4322089459545 β
β Tool Versions β {'python': '3.12.14', 'biopython': '1.88', β
β β 'sirnaforge': '0.6.0'} β
βββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π Top Candidates:
βββββββββββββ¬ββββββββββββ¬βββββββββββ¬βββββββββββββ¬βββββββ¬βββββββ¬ββββββββ¬ββββββββ
β ID β Transcriβ¦ β Position β Sequence β GC% β Hits β Hit % β Score β
βββββββββββββΌββββββββββββΌβββββββββββΌβββββββββββββΌβββββββΌβββββββΌββββββββΌββββββββ€
β SIRNAF_Nβ¦ β NM_00204β¦ β 1011 β CAAATTCGTβ¦ β 42.9 β 1 β 33.3% β 89.4 β
β SIRNAF_Nβ¦ β NM_00054β¦ β 2346 β CAATTGTAAβ¦ β 42.9 β 1 β 33.3% β 89.4 β
β SIRNAF_Nβ¦ β NM_00054β¦ β 2348 β CACAATTGTβ¦ β 42.9 β 1 β 33.3% β 88.7 β
β SIRNAF_Nβ¦ β NM_00204β¦ β 193 β ATGTAAACCβ¦ β 38.1 β 1 β 33.3% β 87.3 β
β SIRNAF_Nβ¦ β NM_00204β¦ β 1245 β TATTGATGGβ¦ β 38.1 β 1 β 33.3% β 87.3 β
βββββββββββββ΄ββββββββββββ΄βββββββββββ΄βββββββββββββ΄βββββββ΄βββββββ΄ββββββββ΄ββββββββ
β
Results saved to: /tmp/sirna_example.csv
Output Previewο
id,transcript_id,position,guide_sequence,passenger_sequence,gc_content,asymmetry_score,structure,mfe,paired_fraction,duplex_stability_dg,duplex_stability_score,dg_5p,dg_3p,delta_dg_end,melting_temp_c,off_target_screened,off_target_count,off_target_penalty,on_target_hits,ortholog_hits,repeat_hits,ortholog_species,repeat_flagged,repeat_transcript_fraction,transcriptome_hits_total,transcriptome_hits_0mm,transcriptome_hits_1mm,transcriptome_hits_2mm,transcriptome_hits_seed_0mm,on_target_confirmed,mirna_hits_total,mirna_hits_0mm_seed,mirna_hits_1mm_seed,mirna_hits_high_risk,guide_pos1_base,pos1_pairing_state,seed_class,supp_13_16_score,seed_7mer_hits,seed_8mer_hits,seed_hits_weighted,off_target_seed_risk_class,transcript_hit_count,transcript_hit_fraction,isoform_coverage,conservation_score,composite_score,score_asymmetry,score_gc_content,score_accessibility,score_empirical,score_off_target,score_isoform_coverage,score_conservation,scored_after_screening,weight_set_version,passes_filters,guide_overhang,guide_modifications,passenger_overhang,passenger_modifications,variant_mode,allele_specific,targeted_alleles,overlapped_variants
SIRNAF_NM_002046-7_1011_1031,NM_002046.7,1011,CAAATTCGTTGTCATACCAGG,CCTGGTATGACAACGAATTTG,42.857142857142854,1.0,.....................,0.0,0.0,-33.900001525878906,0.3061225527808779,-4.199999809265137,-9.699999809265137,5.5,68.50393013284815,False,0,0,0,0,0,,False,0.0,0,0,0,0,0,False,0,0,0,0,,,,,,,,,1,0.3333333333333333,,,89.4322089459545,24.0,18.4322089459545,26.0,21.0,,,,False,2.0.0,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,[],[]
SIRNAF_NM_000546-6_2346_2366,NM_000546.6,2346,CAATTGTAATCCCAGCACTCT,AGAGTGCTGGGATTACAATTG,42.857142857142854,1.0,.....................,0.0,0.0,-35.5,0.41496598639455784,-4.699999809265137,-9.699999809265137,5.0,70.91275888569237,False,0,0,0,0,0,,False,0.0,0,0,0,0,0,False,0,0,0,0,,,,,,,,,1,0.3333333333333333,,,89.4322089459545,24.0,18.4322089459545,26.0,21.0,,,,False,2.0.0,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,[],[]
SIRNAF_NM_000546-6_2348_2368,NM_000546.6,2348,CACAATTGTAATCCCAGCACT,AGTGCTGGGATTACAATTGTG,42.857142857142854,0.9699999809265136,.....................,0.0,0.0,-35.29999923706055,0.40136049231704396,-4.699999809265137,-9.399999618530273,4.699999809265137,70.94870376154853,False,0,0,0,0,0,,False,0.0,0,0,0,0,0,False,0,0,0,0,,,,,,,,,1,0.3333333333333333,,,88.71220848819083,23.279999542236325,18.4322089459545,26.0,21.0,,,,False,2.0.0,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,[],[]
SIRNAF_NM_002046-7_193_213,NM_002046.7,193,ATGTAAACCATGTAGTTGAGG,CCTCAACTACATGGTTTACAT,38.095238095238095,1.0,.....................,0.0,0.0,-33.29999923706055,0.2653060705483367,-3.5,-8.899999618530273,5.399999618530273,68.35174455395514,False,0,0,0,0,0,,False,0.0,0,0,0,0,0,False,0,0,0,0,,,,,,,,,1,0.3333333333333333,,,87.28738189772183,24.0,19.28738189772183,26.0,18.0,,,,False,2.0.0,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,[],[]
SIRNAF_NM_002046-7_1245_1265,NM_002046.7,1245,TATTGATGGTACATGACAAGG,CCTTGTCATGTACCATCAATA,38.095238095238095,1.0,.....................,0.0,0.0,-33.70000076293945,0.2925170587033641,-3.799999952316284,-8.899999618530273,5.099999666213989,68.30738914474875,False,0,0,0,0,0,,False,0.0,0,0,0,0,0,False,0,0,0,0,,,,,,,,,1,0.3333333333333333,,,87.28738189772183,24.0,19.28738189772183,26.0,18.0,,,,False,2.0.0,True,dTdT,2OMe(11),dTdT,2OMe(11),,False,[],[]
zfnο
Evaluate a ZFN pair and run exhaustive genome-wide off-target search.
Warning
EXPERIMENTAL β results are not decision-grade. The ZFN arm ships experimental in 0.6.0 with known
unfixed defects in half-site orientation handling, FokI seed-region weighting and off-target region
classification, tracked in #82. Do not use ZFN
output for any decision without independent validation. The published CCR5 half-site pair does not
match its own on-target site under the default strand-pairing rule β pass
--zfn-right-half-site CTTTTGCAGTTT rather than the published AAACTGCAAAAG β which also
invalidates the recorded ZFN validation runs. Two further defects change nothing visible in the
output: the exported worst_site_score and best_offtarget_score fields are inverted
(worst_site_score is the minimum site score, best_offtarget_score the maximum, whereas the
highest-scoring off-target is the most dangerous one), and a site inside a large containing gene can
be classified intergenic, which undercounts the exonic/promoter tallies the pass/fail filters read.
See ZFN Module Guide.
Helpο
Usage: sirnaforge zfn [OPTIONS]
Evaluate a ZFN pair and run exhaustive genome-wide off-target search
(EXPERIMENTAL).
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --output-dir -o <path> Output β
β directory for β
β ZFN activity β
β evaluation β
β results β
β [default: β
β sirna_zfn_outpβ¦ β
β --zfn-subfingeβ¦ <str> ZFN sub-finger β
β mutation β
β allowance. β
β Repeatable β
β format: β
β scope:max_mutaβ¦ β
β scope can be β
β subfinger index β
β (e.g. 2), '*' β
β for default β
β per-subfinger, β
β or 'overall' β
β for global β
β budgets. Use β
β 'mismatch' as a β
β shorthand alias β
β for β
β 'substitution'. β
β --zfn-max-mismβ¦ <int range> Convenience β
β [x>=0] option β
β equivalent to β
β --zfn-subfingeβ¦ β
β '*:<N>:mismatcβ¦ β
β --zfn-max-subsβ¦ <int range> Convenience β
β [x>=0] option β
β equivalent to β
β --zfn-subfingeβ¦ β
β 'overall:<N>:sβ¦ β
β * --zfn-left-halβ¦ <str> Left ZFN β
β half-site β
β sequence (9-18 β
β bp, IUPAC β
β allowed). β
β [required] β
β * --zfn-right-haβ¦ <str> Right ZFN β
β half-site β
β sequence (9-18 β
β bp, IUPAC β
β allowed). β
β [required] β
β --zfn-search-sβ¦ <str> Genome β
β reference key β
β or local FASTA β
β path for ZFN β
β off-target β
β search space. β
β Built-in keys: β
β ensembl_human_β¦ β
β ensembl_mouse_β¦ β
β ensembl_rat_grβ¦ β
β ensembl_macaquβ¦ β
β Default: β
β ensembl_human_β¦ β
β --zfn-search-sβ¦ <str> Optional β
β persisted β
β search-space β
β index bundle β
β path for β
β indexed ZFN β
β backends β
β (currently β
β fm_index; β
β fm_index is β
β experimental on β
β large β
β references). β
β --zfn-search-bβ¦ <exhaustive_pyt Half-site β
β hon|pyahocorasi search backend: β
β ck|fm_index> pyahocorasick β
β (default), β
β exhaustive_pytβ¦ β
β (baseline), or β
β fm_index β
β (experimental). β
β [default: β
β pyahocorasick] β
β --zfn-algorithm <homology|conse ZFN off-target β
β rved_g|zfn_v2> scoring β
β algorithm: β
β homology, β
β conserved_g, or β
β zfn_v2 β
β (default). β
β [default: β
β zfn_v2] β
β --zfn-dimer-moβ¦ <heterodimer_on Dimer mode: β
β ly|include_homo heterodimer_onβ¦ β
β dimers> (default) or β
β include_homodiβ¦ β
β [default: β
β heterodimer_onβ¦ β
β --zfn-spacer-lβ¦ <str> Comma-separated β
β allowed spacer β
β lengths between β
β half-sites β
β (default: β
β 5,6,7). β
β [default: β
β 5,6,7] β
β --zfn-max-mismβ¦ <int range> Max mismatches β
β [0<=x<=6] per half-site β
β in exhaustive β
β genomic search β
β (default: 2). β
β [default: 2] β
β --cores <int range> Total CPU core β
β [x>=1] budget for β
β workflow β
β execution. ZFN β
β sharding and β
β workflow β
β parallel stages β
β derive from β
β this. β
β [env var: β
β SIRNAFORGE_CORβ¦ β
β --zfn-annotatiβ¦ <str> Optional β
β GTF/GFF β
β annotation file β
β for ZFN β
β off-target β
β region β
β classification. β
β --verbose -v Enable verbose β
β output β
β --log-file <path> Path to β
β centralized log β
β file (overrides β
β SIRNAFORGE_LOGβ¦ β
β env) β
β --nextflow-docβ¦ <str> Override the β
β Docker image β
β passed to β
β Nextflow β
β (default: β
β ghcr.io/austinβ¦ β
β [env var: β
β SIRNAFORGE_NEXβ¦ β
β --json-summary --no-json-summβ¦ Write β
β logs/workflow_β¦ β
β (disable to β
β skip JSON β
β output) β
β [default: β
β json-summary] β
β --help Show this β
β message and β
β exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Notesο
--zfn-left-half-siteand--zfn-right-half-siteare required.--zfn-search-spaceaccepts either a local/remote FASTA or a configured reference key.--zfn-search-backendselects the half-site scan engine:pyahocorasick(default),exhaustive_python(baseline), orfm_index(experimental).--zfn-search-space-indexaccepts a persisted index-bundle directory for indexed backends. This is currently supported byfm_index.--zfn-algorithmsupportshomology,conserved_g, andzfn_v2.Outputs are written as
sirnaforge/candidate_summary.jsonandsirnaforge/offtarget_sites.csv, with run metadata inlogs/workflow_summary.json.
Operational guidance from the backend tuning work β measured before the half-site convention issue was found, so read it as a runtime observation only, not as a validated correctness result:
prefer
pyahocorasickfor the first run on large references, but only for--zfn-max-mismatchesof 3 or lessuse
fm_indexonly for repeated persisted-index workflows; treat it as experimental on large referenceskeep
exhaustive_pythonas the baseline comparator and fallback implementation
Warning
The default pyahocorasick backend aborts above 3 mismatches on a 12 bp half-site. Both
pattern-enumerating backends (pyahocorasick, fm_index) expand the query over the full 15-letter
IUPAC alphabet rather than the four bases a genome contains, and reject the search when the expansion
exceeds 1,000,000 patterns. A 12 bp half-site at --zfn-max-mismatches 4 expands to 5,498,165
patterns and an 18 bp half-site at 3 mismatches to 1,717,605, so both raise:
ValueError: ZFN L half-site is too complex for the pyahocorasick backend: 5498165 candidate
patterns exceed the safety limit of 1000000.
--zfn-max-mismatches 4 is the budget the CCR5 benchmark needs, so pass
--zfn-search-backend exhaustive_python for those runs. Tracked in
#82.
For reproducible fm_index runs, prebuild one search-space bundle once, then reuse it across runs:
uv run sirnaforge internal zfn-build-search-index \
--genome-fasta /path/to/hg38.fa \
--search-backend fm_index
The command prints a JSON summary including bundle_dir; pass that directory to --zfn-search-space-index on subsequent sirnaforge zfn runs.
validateο
Check FASTA file format and content.
Helpο
Usage: sirnaforge validate [OPTIONS] {input_file}
Validate a FASTA file and report basic statistics.
This performs lightweight validation (parseable FASTA, presence of
sequences, and common issues like short/ambiguous sequences).
ββ Arguments ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β * input_file <file> FASTA file to validate [required] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Example: Validate Sample Dataο
π FASTA Validation Results
ββββββββββββββββββββββββββββββββ¬ββββββββββββ
β Metric β Value β
ββββββββββββββββββββββββββββββββΌββββββββββββ€
β Total sequences β 3 β
β Total length β 5,117 nt β
β Average length β 1705.7 nt β
β Min length β 1285 nt β
β Max length β 2512 nt β
β Short sequences (<50 nt) β 0 β
β Ambiguous sequences (with N) β 0 β
ββββββββββββββββββββββββββββββββ΄ββββββββββββ
β
FASTA validation complete
configο
Show default configuration parameters.
Default Design Parameters:
Basic Parameters:
siRNA length: 21 nt
Reported candidates: all (uncapped)
Filtering Criteria:
GC content: 35.0% - 60.0%
Max poly runs: 3
Max paired fraction: 0.6
Scoring Weights:
Asymmetry: 0.12
GC content: 0.1
Accessibility: 0.13
Off-target: 0.25
Empirical: 0.15
sequencesο
Manage siRNA sequences and chemical modification metadata.
Helpο
Usage: sirnaforge sequences [OPTIONS] COMMAND [ARGS]...
Manage siRNA sequences and metadata
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ Commands βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β show Show sequences from a FASTA file in table, JSON, or FASTA format. β
β annotate Merge metadata from a JSON file into FASTA headers. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
cacheο
Manage miRNA database cache for off-target analysis.
Helpο
Usage: sirnaforge cache [OPTIONS]
Inspect and clear the unified reference cache.
This command can display cache statistics and/or delete cached assets for
miRNA databases and transcriptomes.
ββ Options ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β --clear Clear all cached databases (miRNA + β
β transcriptomes) β
β --clear-mirna Clear only miRNA databases β
β --clear-transcriptome Clear only transcriptomes β
β --dry-run Show what would be deleted without actually β
β deleting β
β --info Show cache information for all databases β
β --help Show this message and exit. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ