DnaSP
Trigger
Fire when a user requests population-genetic analysis of aligned DNA, a supported
VCF, or a DnaSP-compatible statistic listed below. Do NOT fire for sequence
alignment, read mapping, haplotype phasing, clinical advice, or significance
tests other than the coalescent P-values --n-sim gives for D, R2 and Fs.
Scope
Analyse genetic variation in supplied alignments using 16 selected DnaSP methods.
This is not a complete replacement for the DnaSP GUI or all its analysis modes.
Read the statistical reference for definitions, exclusions,
source conventions, file formats, examples and release validation evidence.
Core Capabilities
- Polymorphism: S, Eta, haplotypes, Hd, VarHd, pi, k, theta-W, G+C,
Tajima's D, Fu and Li D*/F*, Ramos-Onsins and Rozas R2.
- LD: D, D', R2, ZnS, Za, ZZ and original-column pair labels; recombination Rm.
- Mismatch distribution with unbiased variance over unordered pairs and Sokal &
Rohlf corrected CV; Harpending (1994) raggedness; Model 1 diallelic InDel diversity.
- Divergence and Hudson Fst between populations; outgroup Fu and Li D/F.
- Two-locus HKA, McDonald-Kreitman, Nei-Gojobori Ka/Ks, Fu's Fs and SFS.
- Opt-in coalescent P-values (
--n-sim) for Tajima's D, R2 and Fu's Fs under a
null with no recombination. A statistic whose simulated null takes one value
(R2 with two sequences; Fu's Fs with two sequences given S; Tajima's D below
four, its variance being zero at three) is reported without a P-value. A seed
replays only on the same Python.
- Ts/Tv, codon counts/RSCU including stops, named per-sequence ENC and its
synonymous-codon-weighted summary.
- Sliding windows mirror DnaSP's Gaps in Sliding Window = considered mode:
starts advance from 1 by the step, capped at alignment length; ends are capped
there too, and the first window reaching the end terminates the loop. Empty
windows are retained. The not-considered mode is not implemented.
- Window midpoints are the alignment position of the ceil(net/2)-th gap-free
column, or the window start if none exists; exported in TSV, JSON and report
and used for the plot. VCF windows use retained SNP indices, including the
final partial window.
- Raw per-site Fay-Wu H and theta-L minus theta-W; normalised Hn/ZE are absent.
Fu and Li D*/F* and outgroup D/F mirror Data > Segregating Sites/Mutations =
Segregating sites, using DnaSP's v5-style panels. The rp49 Eta-setting D*/F*
figures can be reproduced by substituting eta for S, but this is not a general
conversion: FULI.vb also changes singleton and external-mutation capping
(SingleMut and ExternaMut subtraction). No Eta-mode switch is implemented.
Workflow
- Confirm the input is pre-aligned and identify the scientific comparison:
ingroup, explicit outgroup, populations, coding interval and genetic code.
Do not infer an outgroup from record order or silently select a code.
- Use the full repository checkout or supplied validation code snapshot so the
shared reproducibility helpers are available. Install the declared dependencies.
- Choose an empty output directory. For alignment input use
--input; for VCF
use --vcf; for two-locus HKA alone use --hka-file --analysis hka.
- Select actual implemented names with
--analysis. Supply --outgroup,
--input2 or --pop-file when needed. Use --genetic-code vertebrate-mitochondrial for the matching mitochondrial table. The default is
standard. Coding intervals must be preselected and divisible by three.
- Execute the CLI. An explicit analysis that cannot run returns a non-zero code.
--analysis all is opportunistic: inspect its completed/skipped manifest.
- Read stderr diagnostics,
report.md and reproducibility/manifest.json.
Distinguish a failed analysis, an undefined statistic and an excluded site.
- Interpret the chosen statistic within its documented assumptions. Do not turn
a signed value or a threshold into a significance claim; only
--n-sim P-values
assess significance, and a rejection does not by itself identify its cause.
- Retain the input archive, settings, hashes and environment with the report.
commands.sh replays on the recorded host/code path into a new output folder;
moving a run requires the code and dependencies as well as its input archive.
- For Windows GUI comparison, follow the separate validation checklist and
capture raw DnaSP output. Source-derived expectations are not GUI observations.
Example Output
python skills/dnasp/dnasp.py --demo --output new_demo_run
python skills/dnasp/dnasp.py --input alignment.fas --analysis polymorphism,ld --output new_run
python skills/dnasp/dnasp.py --input coding.fas --outgroup OutSeq --genetic-code vertebrate-mitochondrial --analysis mk,kaks,codon --output new_coding_run
python skills/dnasp/dnasp.py --vcf samples.vcf --analysis polymorphism,sfs,fufs --output new_vcf_run
The synthetic demo contains 10 ingroup sequences, one outgroup and 300 sites:
| Quantity |
Demo value |
| S / haplotypes |
5 / 8 |
| Hd / Tajima D |
0.9556 / 0.6789 |
| MK Pn / Ps / Dn / Ds |
2 / 3 / 2 / 1 |
| MK alpha |
0.6667 |
| Ka / Ks / omega |
0.010239 / 0.030291 / 0.3380 |
| Ts / Tv |
4 / 1 |
The demo runs 15 modules; HKA uses a separate two-locus input. The regression
suite, rather than the printed banner alone, checks the expected figures.
Output Structure
output/
report.md
results.tsv # polymorphism and windows
summary.json # module summaries, window midpoints, named ENC/null
result.json # ClawBio envelope: headline summary, summary.json payload, artifacts
ld_pairs.tsv # when LD pairs exist
figures/ # when matplotlib is available
reproducibility/
inputs/
commands.sh
environment.yml
manifest.json
checksums.sha256
Dependencies
Python 3.10 or later. Core estimators use the standard library. Plotting uses
matplotlib; the repository's shared reproducibility package also imports NumPy,
pandas and OpenTelemetry. Use environment.yml or the validation package's
pinned requirements. The Windows validation runner targets Python 3.12.
Gotchas
- The model will want to count IUPAC symbols as alleles. Do not. Supported
ambiguity symbols are missing data and the nucleotide mask excludes their columns.
- The model will want to analyse an unknown outgroup as an ingroup-only run.
Do not. Identifiers must be unique and an explicit outgroup must resolve.
- The model will want to call VCF diversity per-base diversity. Do not. VCF
columns represent retained variant records; invariant callable bases are absent.
- The model will want to use any coding annotation in a NEXUS file. Do not.
This implementation requires a preselected coding alignment and does not read
CHARSET coding annotations. In COII, use positions 1-681 for codon usage.
- The model will want to apply one stop-codon rule everywhere. Do not. Selected
stops count in RSCU and as family 21 in MK/KaKs; ENC and coding G+C use sense codons.
- The model will want to read raw H/E as normalised DnaSP Hn/ZE. Do not.
These outputs are explicitly different, and no significance test is supplied.
- The model will want to overwrite an earlier output folder. Do not. Choose a
fresh folder; runs reject non-empty destinations to preserve prior artefacts.
- The model will want to infer genomic-scale performance from the tiny bundled
VCF examples. Do not. LD enumerates all biallelic-site pairs and uses quadratic
storage; read the measured limits in the reference before a large run.
Known Differences from DnaSP 6.12.03
Four values compared with DnaSP 6.12.03 are unresolved. They come from the DnaSP
VCF examples with a single variant site: the phased diploid Scaffold_2
(n = 20) and the haploid Region_MSA_2 (n = 10). The skill follows the DnaSP 6
source code and the result files shipped with DnaSP 6.0.60; the captures cannot
tell whether DnaSP's build or its analysis route changed.
| Statistic |
Skill |
DnaSP 6.0.60 |
DnaSP 6.12.03 |
| Pi, Scaffold_2 |
0.1 |
0.1 |
n.a. |
| R2, Scaffold_2 |
0.217945 |
0.217945 |
0.259808 |
| Pi, Region_MSA_2 |
0.2 |
0.2 |
n.a. |
| R2, Region_MSA_2 |
0.3 |
0.3 |
0.346410 |
Differences of setting or definition, not errors:
- Fu and Li's tests follow DnaSP's Segregating sites setting; DnaSP's default
Eta setting gives different D*, F*, D and F.
- DnaSP prints two F* forms; the skill reproduces the "DnaSP v5" form (Simonsen
et al. 1995), not the biallelic-positions form (Achaz 2009) that DnaSP's
multi-alignment output reports.
- A coding region whose final codon is a stop in every sequence is analysed
without that codon; DnaSP keeps it if the user declines its prompt.
- The folded SFS excludes multiallelic sites; DnaSP's segregating-sites spectrum
places them in a frequency class.
- Sliding windows with no segregating site report Tajima's D as undefined;
DnaSP prints 0.0000.
- Coalescent simulation (
--n-sim): the null has no recombination, so for a
recombining region a low Fu's Fs P-value may reflect recombination rather than
growth (Tajima's D and R2 are conservative there). DnaSP 6 offers a
recombination setting; DnaSP 6's own one-locus module conditions on theta only,
fixed S being its v5 routine; and DnaSP reports the one-tailed P(Sim <= Obs),
where this skill reports twice the smaller tail for Tajima's D.
- Ts/Tv has no DnaSP 6 counterpart, and raw Fay and Wu H and Zeng E are not
DnaSP's normalised Hn and ZE.
Version History
Current version 0.6.1. Every change that alters a result, and the version compared
with DnaSP 6.12.03 (0.5.2), is recorded in docs/version_history.md.
Safety
All sequence analysis and output remain local. ClawBio is a research and
educational tool. It is not a medical device and does not provide clinical
diagnoses. Consult a healthcare professional before making any medical decisions.
Agent Boundary
The agent selects documented inputs/options, executes the skill and explains
reported results. The code computes the statistics. Neither the agent nor the
skill may fabricate GUI validation, P-values or missing results.
Integration with Bio Orchestrator
CLI alias: dnasp. Use --analysis for module selection, not invented flags
such as --pi, --kaks or --tajima. The repository dispatcher permits the
implemented options, including VCF, populations and genetic-code selection.
Route here when the user asks for a statistic this skill computes (for example
nucleotide or haplotype diversity, Tajima's D, Fu and Li's tests, Fu's Fs,
McDonald-Kreitman, Ka/Ks, HKA, the mismatch distribution, InDel polymorphism or
codon usage bias) on an aligned FASTA or NEXUS file or a multi-sample VCF.
INTENTS.json publishes the dnasp aliases to ClawBio's intent planner and
plans the demo only when the user explicitly asks for a demo; a real analysis
needs the user's file, and --analysis selects modules other than the default
polymorphism summary.
Chaining Partners
- Alignment upstream. Sequences must be aligned before this skill.
phylogenetics-builder aligns with MAFFT, MUSCLE and other aligners. Versions
of that skill that save their alignment write alignment/aligned.fasta; use
that untrimmed file rather than the trimAl output, because trimming removes
gapped or poorly aligned columns and so changes S, pi and the InDel results.
Otherwise align the sequences separately and pass the aligned FASTA.
fastreer. Builds distance trees from the same multi-sample VCF: run this
skill for diversity and neutrality statistics, then fastreeR for sample
relationships.
claw-ancestry-pca. Gives population-structure context before samples are
grouped in a --pop-file for Fst or divergence.
equity-scorer. Reports HEIM heterozygosity and Fst from VCF or ancestry
data with its own estimators; this skill's Hudson Fst and diversity statistics
follow DnaSP 6, so the two sets of values are not interchangeable.
- VCF preparation. A filtering or phasing workflow may prepare input, but
every filter and phasing choice must be recorded; unphased heterozygotes stay
unresolved here.
- Reporting downstream. Use
report.md, summary.json, result.json and
the TSV files; the TSV does not contain every module's results.
Maintenance
Recheck source/help-derived regression cases and the 170 historical comparison
fixtures after changes to formulas, masks or parsers. Review GUI differences
when the target DnaSP build or analysis mode changes. Keep this file, the method
reference, CLI metadata, version and catalogue consistent. New Windows GUI
observations must be reviewed before changing published concordance counts.
1---2name: dnasp3description: Population genetics of pre-aligned DNA sequences or multi-sample VCFs4 using selected DnaSP 6 methods. Use for diversity, neutrality statistics, linkage5 disequilibrium, InDel polymorphism, divergence, MK, Ka/Ks and codon usage; not alignment,6 phasing or clinical interpretation.7license: MIT8metadata:9 source: https://skillmd.com/skills/clawbio/dnasp10 version: 0.6.111 author: David De Lorenzo12 domain: molecular-evolution13 tags:14 - population-genetics15 - molecular-evolution16 - DNA-polymorphism17 - neutrality-tests18 - linkage-disequilibrium19 - recombination20 - divergence21 - sequence-analysis22 inputs:23 - name: alignment24 type: file25 format:26 - fasta27 - fas28 - nexus29 - nex30 description: Aligned DNA sequences (pre-aligned, equal-length). FASTA (including31 DnaSP-style >'name' [comment] headers) or NEXUS (MATCHCHAR, INTERLEAVE).32 required: false33 cli_flag: --input34 - name: vcf35 type: file36 format:37 - vcf38 description: Multi-sample VCF (--vcf). Converted to one aligned MSA per CHROM39 (biallelic SNPs only; phased -> haplotype rows). Alternative to --input. Optional40 --region CHROM, --vcf-merge to pool all CHROMs.41 required: false42 cli_flag: --vcf43 - name: alignment244 type: file45 format:46 - fasta47 - fas48 - nexus49 - nex50 description: Second-population alignment for divergence analysis (--input2). Alternative51 to --pop-file. Sequences must have same length as --input.52 required: false53 cli_flag: --input254 - name: pop_file55 type: file56 format:57 - tsv58 - txt59 description: 'Population assignment file: one row per sequence, tab-separated60 (sequence_name<TAB>population_name). Required for Fst; alternative to --input2 for divergence.'61 required: false62 cli_flag: --pop-file63 - name: outgroup64 type: string65 description: Unique sequence identifier removed from the ingroup. Required for66 fuliout, mk and faywu; also polarises SFS/TsTv and selects ingroup-versus-outgroup67 Ka/Ks.68 required: false69 cli_flag: --outgroup70 - name: hka_file71 type: file72 format:73 - tsv74 - txt75 description: 'HKA locus file: whitespace-separated, exactly two loci, columns76 locus n S L_poly D [L_div] [chrom]. Required for --analysis hka.'77 required: false78 cli_flag: --hka-file79 - name: analyses80 type: string81 description: Comma-separated polymorphism, ld, recombination, popsize, indel,82 divergence, fuliout, hka, mk, kaks, fufs, sfs, tstv, codon, faywu, fst; or all.83 Polymorphism runs with alignment input.84 required: false85 cli_flag: --analysis86 - name: window_size87 type: integer88 description: Sliding window size in bp (0 = whole alignment only, default 0)89 required: false90 cli_flag: --window91 - name: step_size92 type: integer93 description: Sliding window step in bp (default = window_size)94 required: false95 cli_flag: --step96 - name: genetic_code97 type: string98 description: 'Codon table for mk/kaks/codon: "standard" or "vertebrate-mitochondrial"99 (TGA=Trp, AGA/AGG=stop, ATA=Met; for COII/cytb/ND-type loci). Default: standard.'100 required: false101 cli_flag: --genetic-code102 - name: n_sim103 type: integer104 description: Coalescent replicates for whole-region P-values of Tajima's D, R2105 and Fu's Fs (0 = no simulation, default). 10000 is typical.106 required: false107 cli_flag: --n-sim108 - name: sim_given109 type: string110 description: 'Simulation conditioned on the observed segregating sites ("S",111 default) or on Watterson''s theta ("theta").'112 required: false113 cli_flag: --sim-given114 - name: sim_seed115 type: integer116 description: Seed for --n-sim; generated and recorded when omitted.117 required: false118 cli_flag: --sim-seed119 outputs:120 - name: report121 type: file122 format:123 - md124 description: Markdown analysis report with statistics and interpretation125 - name: results_table126 type: file127 format:128 - tsv129 description: Polymorphism and sliding-window TSV only; other modules appear in130 report.md.131 - name: result132 type: file133 format:134 - json135 description: ClawBio result.json envelope (skill, version, input checksum,136 headline summary, the summary.json payload plus artifact list,137 chat_summary_lines and preferred_artifacts for the runner). A multi-CHROM138 VCF run writes one envelope per CHROM directory and a root envelope that139 summarises them with relative paths.140 - name: summary141 type: file142 format:143 - json144 description: Module summaries (global and per-window statistics with DnaSP145 midpoints, LD/recombination/mismatch/InDel/divergence/MK/Ka-Ks/codon results146 including named per-sequence ENC); LD pair grids are in ld_pairs, not here.147 - name: ld_pairs148 type: file149 format:150 - tsv151 description: Pairwise LD table (only when --analysis ld is active)152 - name: figures153 type: directory154 description: Sliding-window plots, LD decay scatter, mismatch histogram (PNG)155 - name: reproducibility156 type: directory157 description: Archived inputs, commands.sh, environment.yml, manifest.json and158 output-relative checksums.sha256.159 dependencies:160 python: '>=3.10'161 packages:162 - matplotlib>=3.7163 - numpy>=1.24164 - pandas>=2.0165 - opentelemetry-sdk>=1.20166 demo_data:167 - path: examples/demo_simple.fas168 description: Synthetic 6-sequence × 10-bp alignment with known statistics169 - path: examples/demo_rp49.fas170 description: rp49 region, 17 Drosophila sequences, 300 bp171 endpoints:172 cli: python skills/dnasp/dnasp.py --input {alignment} --analysis {analyses} --output173 {output_dir}174 openclaw:175 requires:176 bins:177 - python3178 always: false179 emoji: ''180 homepage: https://github.com/ClawBio/ClawBio181 os:182 - darwin183 - linux184 - win32185 install:186 - kind: pip187 package: matplotlib>=3.7188 - kind: pip189 package: numpy>=1.24190 - kind: pip191 package: pandas>=2.0192 - kind: pip193 package: opentelemetry-sdk>=1.20194 trigger_keywords:195 - nucleotide diversity196 - Tajima's D197 - DNA polymorphism198 - population genetics sequences199 - haplotype diversity200 - DnaSP201 - segregating sites202 - Fu and Li test203 - neutrality test alignment204 - Watterson theta205 - linkage disequilibrium206 - recombination events207 - mismatch distribution208 - population expansion209 - InDel polymorphism210 - divergence between populations211 - Dxy Da net divergence212 - fixed differences populations213 - Ramos-Onsins Rozas R2214 - Fu Li D F outgroup215 - outgroup polarised mutations216 - HKA test neutrality217 - Hudson Kreitman Aguade218 - two-locus neutrality219 - polymorphism divergence ratio220 - McDonald-Kreitman test221 - MK test222 - adaptive evolution test223 - alpha McDonald-Kreitman224 - neutrality index NI225 - direction of selection DoS226 - Ka/Ks227 - dN/dS228 - omega synonymous nonsynonymous229 - synonymous substitution rate230 - nonsynonymous substitution rate231 - coding sequence neutrality232 - Nei-Gojobori method233 - Fu's Fs test234 - Fu 1997 Fs235 - site frequency spectrum236 - SFS folded unfolded237 - allele frequency spectrum238 - singleton excess239 - minor allele frequency distribution240 - VCF population genetics241 - multi-sample VCF nucleotide diversity242 - VCF to haplotypes243 - population genomics from VCF244---245246# DnaSP247248## Trigger249250Fire when a user requests population-genetic analysis of aligned DNA, a supported251VCF, or a DnaSP-compatible statistic listed below. Do NOT fire for sequence252alignment, read mapping, haplotype phasing, clinical advice, or significance253tests other than the coalescent P-values `--n-sim` gives for D, R2 and Fs.254255## Scope256257Analyse genetic variation in supplied alignments using 16 selected DnaSP methods.258This is not a complete replacement for the DnaSP GUI or all its analysis modes.259Read [the statistical reference](docs/index.md) for definitions, exclusions,260source conventions, file formats, examples and release validation evidence.261262## Core Capabilities263264- Polymorphism: S, Eta, haplotypes, Hd, VarHd, pi, k, theta-W, G+C,265 Tajima's D, Fu and Li D*/F*, Ramos-Onsins and Rozas R2.266- LD: D, D', R2, ZnS, Za, ZZ and original-column pair labels; recombination Rm.267- Mismatch distribution with unbiased variance over unordered pairs and Sokal &268 Rohlf corrected CV; Harpending (1994) raggedness; Model 1 diallelic InDel diversity.269- Divergence and Hudson Fst between populations; outgroup Fu and Li D/F.270- Two-locus HKA, McDonald-Kreitman, Nei-Gojobori Ka/Ks, Fu's Fs and SFS.271- Opt-in coalescent P-values (`--n-sim`) for Tajima's D, R2 and Fu's Fs under a272 null with no recombination. A statistic whose simulated null takes one value273 (R2 with two sequences; Fu's Fs with two sequences given S; Tajima's D below274 four, its variance being zero at three) is reported without a P-value. A seed275 replays only on the same Python.276- Ts/Tv, codon counts/RSCU including stops, named per-sequence ENC and its277 synonymous-codon-weighted summary.278- Sliding windows mirror DnaSP's **Gaps in Sliding Window = considered** mode:279 starts advance from 1 by the step, capped at alignment length; ends are capped280 there too, and the first window reaching the end terminates the loop. Empty281 windows are retained. The not-considered mode is not implemented.282- Window midpoints are the alignment position of the ceil(net/2)-th gap-free283 column, or the window start if none exists; exported in TSV, JSON and report284 and used for the plot. VCF windows use retained SNP indices, including the285 final partial window.286- Raw per-site Fay-Wu H and theta-L minus theta-W; normalised Hn/ZE are absent.287288Fu and Li D*/F* and outgroup D/F mirror **Data > Segregating Sites/Mutations =289Segregating sites**, using DnaSP's v5-style panels. The rp49 Eta-setting D*/F*290figures can be reproduced by substituting eta for S, but this is not a general291conversion: `FULI.vb` also changes singleton and external-mutation capping292(`SingleMut` and `ExternaMut` subtraction). No Eta-mode switch is implemented.293294## Workflow2952961. Confirm the input is pre-aligned and identify the scientific comparison:297 ingroup, explicit outgroup, populations, coding interval and genetic code.298 Do not infer an outgroup from record order or silently select a code.2992. Use the full repository checkout or supplied validation code snapshot so the300 shared reproducibility helpers are available. Install the declared dependencies.3013. Choose an empty output directory. For alignment input use `--input`; for VCF302 use `--vcf`; for two-locus HKA alone use `--hka-file --analysis hka`.3034. Select actual implemented names with `--analysis`. Supply `--outgroup`,304 `--input2` or `--pop-file` when needed. Use `--genetic-code305 vertebrate-mitochondrial` for the matching mitochondrial table. The default is306 standard. Coding intervals must be preselected and divisible by three.3075. Execute the CLI. An explicit analysis that cannot run returns a non-zero code.308 `--analysis all` is opportunistic: inspect its completed/skipped manifest.3096. Read stderr diagnostics, `report.md` and `reproducibility/manifest.json`.310 Distinguish a failed analysis, an undefined statistic and an excluded site.3117. Interpret the chosen statistic within its documented assumptions. Do not turn312 a signed value or a threshold into a significance claim; only `--n-sim` P-values313 assess significance, and a rejection does not by itself identify its cause.3148. Retain the input archive, settings, hashes and environment with the report.315 `commands.sh` replays on the recorded host/code path into a new output folder;316 moving a run requires the code and dependencies as well as its input archive.3179. For Windows GUI comparison, follow the separate validation checklist and318 capture raw DnaSP output. Source-derived expectations are not GUI observations.319320## Example Output321322```bash323python skills/dnasp/dnasp.py --demo --output new_demo_run324python skills/dnasp/dnasp.py --input alignment.fas --analysis polymorphism,ld --output new_run325python skills/dnasp/dnasp.py --input coding.fas --outgroup OutSeq --genetic-code vertebrate-mitochondrial --analysis mk,kaks,codon --output new_coding_run326python skills/dnasp/dnasp.py --vcf samples.vcf --analysis polymorphism,sfs,fufs --output new_vcf_run327```328329The synthetic demo contains 10 ingroup sequences, one outgroup and 300 sites:330331| Quantity | Demo value |332|---|---:|333| S / haplotypes | 5 / 8 |334| Hd / Tajima D | 0.9556 / 0.6789 |335| MK Pn / Ps / Dn / Ds | 2 / 3 / 2 / 1 |336| MK alpha | 0.6667 |337| Ka / Ks / omega | 0.010239 / 0.030291 / 0.3380 |338| Ts / Tv | 4 / 1 |339340The demo runs 15 modules; HKA uses a separate two-locus input. The regression341suite, rather than the printed banner alone, checks the expected figures.342343## Output Structure344345```text346output/347 report.md348 results.tsv # polymorphism and windows349 summary.json # module summaries, window midpoints, named ENC/null350 result.json # ClawBio envelope: headline summary, summary.json payload, artifacts351 ld_pairs.tsv # when LD pairs exist352 figures/ # when matplotlib is available353 reproducibility/354 inputs/355 commands.sh356 environment.yml357 manifest.json358 checksums.sha256359```360361## Dependencies362363Python 3.10 or later. Core estimators use the standard library. Plotting uses364matplotlib; the repository's shared reproducibility package also imports NumPy,365pandas and OpenTelemetry. Use `environment.yml` or the validation package's366pinned requirements. The Windows validation runner targets Python 3.12.367368## Gotchas369370- The model will want to count IUPAC symbols as alleles. Do not. Supported371 ambiguity symbols are missing data and the nucleotide mask excludes their columns.372- The model will want to analyse an unknown outgroup as an ingroup-only run.373 Do not. Identifiers must be unique and an explicit outgroup must resolve.374- The model will want to call VCF diversity per-base diversity. Do not. VCF375 columns represent retained variant records; invariant callable bases are absent.376- The model will want to use any coding annotation in a NEXUS file. Do not.377 This implementation requires a preselected coding alignment and does not read378 CHARSET coding annotations. In COII, use positions 1-681 for codon usage.379- The model will want to apply one stop-codon rule everywhere. Do not. Selected380 stops count in RSCU and as family 21 in MK/KaKs; ENC and coding G+C use sense codons.381- The model will want to read raw H/E as normalised DnaSP Hn/ZE. Do not.382 These outputs are explicitly different, and no significance test is supplied.383- The model will want to overwrite an earlier output folder. Do not. Choose a384 fresh folder; runs reject non-empty destinations to preserve prior artefacts.385- The model will want to infer genomic-scale performance from the tiny bundled386 VCF examples. Do not. LD enumerates all biallelic-site pairs and uses quadratic387 storage; read the measured limits in the reference before a large run.388389## Known Differences from DnaSP 6.12.03390391Four values compared with DnaSP 6.12.03 are unresolved. They come from the DnaSP392VCF examples with a single variant site: the phased diploid `Scaffold_2`393(n = 20) and the haploid `Region_MSA_2` (n = 10). The skill follows the DnaSP 6394source code and the result files shipped with DnaSP 6.0.60; the captures cannot395tell whether DnaSP's build or its analysis route changed.396397| Statistic | Skill | DnaSP 6.0.60 | DnaSP 6.12.03 |398|-----------|-------|--------------|---------------|399| Pi, Scaffold_2 | 0.1 | 0.1 | n.a. |400| R2, Scaffold_2 | 0.217945 | 0.217945 | 0.259808 |401| Pi, Region_MSA_2 | 0.2 | 0.2 | n.a. |402| R2, Region_MSA_2 | 0.3 | 0.3 | 0.346410 |403404Differences of setting or definition, not errors:405406- Fu and Li's tests follow DnaSP's *Segregating sites* setting; DnaSP's default407 *Eta* setting gives different D*, F*, D and F.408- DnaSP prints two F* forms; the skill reproduces the "DnaSP v5" form (Simonsen409 et al. 1995), not the biallelic-positions form (Achaz 2009) that DnaSP's410 multi-alignment output reports.411- A coding region whose final codon is a stop in every sequence is analysed412 without that codon; DnaSP keeps it if the user declines its prompt.413- The folded SFS excludes multiallelic sites; DnaSP's segregating-sites spectrum414 places them in a frequency class.415- Sliding windows with no segregating site report Tajima's D as undefined;416 DnaSP prints 0.0000.417- Coalescent simulation (`--n-sim`): the null has no recombination, so for a418 recombining region a low Fu's Fs P-value may reflect recombination rather than419 growth (Tajima's D and R2 are conservative there). DnaSP 6 offers a420 recombination setting; DnaSP 6's own one-locus module conditions on theta only,421 fixed S being its v5 routine; and DnaSP reports the one-tailed P(Sim <= Obs),422 where this skill reports twice the smaller tail for Tajima's D.423- Ts/Tv has no DnaSP 6 counterpart, and raw Fay and Wu H and Zeng E are not424 DnaSP's normalised Hn and ZE.425426## Version History427428Current version 0.6.1. Every change that alters a result, and the version compared429with DnaSP 6.12.03 (0.5.2), is recorded in `docs/version_history.md`.430431## Safety432433All sequence analysis and output remain local. ClawBio is a research and434educational tool. It is not a medical device and does not provide clinical435diagnoses. Consult a healthcare professional before making any medical decisions.436437## Agent Boundary438439The agent selects documented inputs/options, executes the skill and explains440reported results. The code computes the statistics. Neither the agent nor the441skill may fabricate GUI validation, P-values or missing results.442443## Integration with Bio Orchestrator444445CLI alias: `dnasp`. Use `--analysis` for module selection, not invented flags446such as `--pi`, `--kaks` or `--tajima`. The repository dispatcher permits the447implemented options, including VCF, populations and genetic-code selection.448449Route here when the user asks for a statistic this skill computes (for example450nucleotide or haplotype diversity, Tajima's D, Fu and Li's tests, Fu's Fs,451McDonald-Kreitman, Ka/Ks, HKA, the mismatch distribution, InDel polymorphism or452codon usage bias) on an aligned FASTA or NEXUS file or a multi-sample VCF.453`INTENTS.json` publishes the `dnasp` aliases to ClawBio's intent planner and454plans the demo only when the user explicitly asks for a demo; a real analysis455needs the user's file, and `--analysis` selects modules other than the default456polymorphism summary.457458## Chaining Partners459460- **Alignment upstream.** Sequences must be aligned before this skill.461 `phylogenetics-builder` aligns with MAFFT, MUSCLE and other aligners. Versions462 of that skill that save their alignment write `alignment/aligned.fasta`; use463 that untrimmed file rather than the trimAl output, because trimming removes464 gapped or poorly aligned columns and so changes S, pi and the InDel results.465 Otherwise align the sequences separately and pass the aligned FASTA.466- **`fastreer`.** Builds distance trees from the same multi-sample VCF: run this467 skill for diversity and neutrality statistics, then fastreeR for sample468 relationships.469- **`claw-ancestry-pca`.** Gives population-structure context before samples are470 grouped in a `--pop-file` for Fst or divergence.471- **`equity-scorer`.** Reports HEIM heterozygosity and Fst from VCF or ancestry472 data with its own estimators; this skill's Hudson Fst and diversity statistics473 follow DnaSP 6, so the two sets of values are not interchangeable.474- **VCF preparation.** A filtering or phasing workflow may prepare input, but475 every filter and phasing choice must be recorded; unphased heterozygotes stay476 unresolved here.477- **Reporting downstream.** Use `report.md`, `summary.json`, `result.json` and478 the TSV files; the TSV does not contain every module's results.479480## Maintenance481482Recheck source/help-derived regression cases and the 170 historical comparison483fixtures after changes to formulas, masks or parsers. Review GUI differences484when the target DnaSP build or analysis mode changes. Keep this file, the method485reference, CLI metadata, version and catalogue consistent. New Windows GUI486observations must be reviewed before changing published concordance counts.