dnasp

Files (48)

• CONTRIBUTORS.md
• INTENTS.json
• SKILL.md
• dnasp.py
• index.md · docs/
• version_history.md · docs/
• environment.yml
• demo_rp49.fas · examples/
• demo_simple.fas · examples/
• historical_comparisons.json · tests/fixtures/
• COII_Apes.nex · tests/fixtures/inputs/
• COII_Apes_HsaPtr_pops.txt · tests/fixtures/inputs/
• COII_HsaPtr_outPpy.fas · tests/fixtures/inputs/
• COII_Hsa_outPpy.fas · tests/fixtures/inputs/
• COII_coding_1_681.fas · tests/fixtures/inputs/
• DmelOSRegion.nex · tests/fixtures/inputs/
• Ex_n1.fas · tests/fixtures/inputs/
• README.md · tests/fixtures/inputs/
• hka_synthetic.tsv · tests/fixtures/inputs/
• indel_help.fas · tests/fixtures/inputs/
• ld_help.fas · tests/fixtures/inputs/
• rp49_36.nex · tests/fixtures/inputs/
• rp49_36_pops.txt · tests/fixtures/inputs/
• Region_1.fas · tests/fixtures/inputs/rp49_5regions/
• Region_2.fas · tests/fixtures/inputs/rp49_5regions/
• Region_3.fas · tests/fixtures/inputs/rp49_5regions/
• Region_4.fas · tests/fixtures/inputs/rp49_5regions/
• Region_5.fas · tests/fixtures/inputs/rp49_5regions/
• rp49_ing34_outGUA.fas · tests/fixtures/inputs/
• stop_family.fas · tests/fixtures/inputs/
• Data_Example_DiploidPhased.vcf · tests/fixtures/inputs/vcf/
• Data_Example_DiploidUnphased.vcf · tests/fixtures/inputs/vcf/
• Data_Example_Haploid.vcf · tests/fixtures/inputs/vcf/
• Data_Example_vcf.SG.txt · tests/fixtures/inputs/vcf/
• A2_rp49_win100_25.out · tests/fixtures/validation5/
• C3_COII_win100_50.out · tests/fixtures/validation5/
• E2_Dmel_win500_250.out · tests/fixtures/validation5/
• M_ENC_standard_GUI_tables_transcribed.txt · tests/fixtures/validation5/
• M_ENC_vertebrate-mitochondrial_GUI_tables_transcribed.txt · tests/fixtures/validation5/
• README.md · tests/fixtures/validation5/
• test_clawbio_intents.py · tests/
• test_coalescent_pvalues.py · tests/
• test_dnasp.py · tests/
• test_historical_comparisons.py · tests/
• test_release_regressions.py · tests/
• test_skill_contract.py · tests/
• test_validation5_regressions.py · tests/
• test_windows_encoding.py · tests/

SKILL.md (first lines)

# 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](docs/index.md) 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

1. 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.
2. Use the full repository checkout or supplied validation code snapshot so the
   shared reproducibility helpers are available. Install the declared dependencies.
3. Choose an empty output directory. For alignment input use `--input`; for VCF
   use `--vcf`; for two-locus HKA alone use `--hka-file --analysis hka`.
4. 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.
5. Execute the CLI. An explicit analysis that cannot run returns a non-zero code.
   `--analysis all` is opportunistic: inspect its completed/skipped manifest.
6. Read stderr diagnostics, `report.md` and `reproducibility/manifest.json`.
   Distinguish a failed analysis, an undefined statistic and an excluded site.
7. 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.
8. 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.
9. For Windows GUI comparison, follow the separate validation checklist and
   capture raw DnaSP output. Source-derived expectations are not GUI observations.

## Example Output

```bash
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

```text
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,

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio