triohap 0.4.0__tar.gz

triohap-0.4.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.4.0
+
+- License TrioHap under MIT and include the licence in both PyPI distributions.
+- Prepare the first PyPI distribution under the name `triohap` (previous local
+  wheels used `triohap-prototype`); the Python import and command stay `triohap`.
+- Add Trusted Publishing, wheel/source-archive validation, project metadata,
+  complete source-distribution test fixtures, and `triohap --version`.
+- Automatically detect VCF and conventional END-based gVCF input from content,
+  using the existing joint and three-file arguments; mixed input is supported.
+- Materialize explicit homozygous-reference block evidence only at panel SNPs
+  and explicit trio SNP anchors, with per-sample quality and coverage checks.
+- Preserve unknown calls, explicit-record precedence, wildcard allele indices,
+  and overlapping unsupported-variant exclusions. Reject ambiguous blocks and
+  unsupported sample-specific FORMAT/LEN blocks rather than guessing calls.
+- Report detected formats, reference-block processing counts, and call sources.
+- Add synthetic VCF/gVCF equivalence tests and reproducible examples.
+
+## 0.3.0
+
+- Preserve the original SCN5A source-table line endings so saved byte checksums
+  remain reproducible after checkout; test exact catalogue reimport.
+
+- Establish `comparativechrono/TrioHap` as the project repository.
+- Accept either a joint VCF or three individual VCFs with explicit role/sample
+  selections. Decode each file's REF/ALT allele dictionary independently.
+- Preserve child phase sets and the same quality filters in both input modes.
+  Absent records remain unknown; only complete usable trio sites are scored.
+- Report input files, per-file metadata and exclusions. Reject incompatible
+  references and contig lengths before combining individual inputs.
+- Add deterministic synthetic equivalence and truth-recovery validation, plus
+  automated unit tests and report-generation checks.
+- Result schema is now `0.2`: individual inputs use a structured `sources.trio`
+  object; joint inputs retain the original path string.
+
+## 0.2.0
+
+- Import the SCN5A source catalogue, retaining all 46 class identities and
+  full-variant graph topology while matching on the 37 supported SNP records.
+- Preserve SNP-equivalent candidate sets and panel provenance.
+
+## 0.1.0
+
+- Initial joint-trio SNP matcher, phase-block handling, ambiguity-aware ranking,
+  optional Unfazed annotation, and self-contained reports.

triohap-0.4.0/GVCF.md

@@ -0,0 +1,103 @@
+# Automatic VCF and gVCF input
+
+The same `--trio` or `--child-vcf` / `--mother-vcf` / `--father-vcf` arguments
+accept ordinary VCFs and conventional gVCFs. No format flag is required. The
+three individual inputs may use different encodings, and compressed input is
+supported. Explicit child GT order and PS blocks retain their existing meaning.
+
+## Detection and supported records
+
+Detection uses observed `<NON_REF>` or `<*>` alleles, GVCFBlock metadata, and
+nonvariant END records. A filename or a standalone NON_REF ALT declaration in
+the header is insufficient. Genotyped VCFs can retain that declaration without
+containing any gVCF blocks.
+
+The supported compressed representation is a nonvariant record with one
+reference base, `INFO/END`, and no literal alternate allele: `ALT=<NON_REF>`,
+`ALT=<*>`, or `ALT=.`. Both block endpoints are included. Unbanded wildcard
+reference records can also contribute evidence at their explicit position.
+END on a deletion or another structural variant is not a reference block.
+
+A SNP record with `ALT=C,<NON_REF>` and `GT=0/1` has a literal A/C call when
+REF is A. The unused symbolic allele is not scored. `GT=0/2` at the same record
+is unresolved and excluded. Allele indices are decoded before symbols are
+handled; they are never renumbered by stripping the ALT list. Bare `*` is a
+spanning-deletion allele and is not interchangeable with `<*>`.
+
+## Reference-call requirements
+
+Each selected sample is evaluated independently, including samples in a joint
+file. An expanded call requires:
+
+- A complete diploid homozygous-reference GT (`0/0` or `0|0`).
+- FILTER and sample FT equal to PASS, dot, or absent where allowed.
+- At least one supplied, finite, positive GQ, RGQ, or GQX value. The minimum
+  available value must meet `--min-gq`; zero-quality reference calls remain
+  unknown even when the requested threshold is zero.
+- No known zero DP or MIN_DP. Missing depth can be retained with usable
+  quality, but its absence is reported in provenance. MED_DP is not used as a
+  substitute for minimum depth.
+
+Malformed quality, depth, and interval fields are errors rather than invented
+confidence. Missing quality, failed filters, incomplete/non-reference GTs,
+and low quality produce exclusions. The program does not estimate missing
+genotypes from likelihoods or population frequency.
+
+For explicit SNP records, GQX is also honored alongside GQ, using the lower
+available value. RGQ applies to homozygous-reference genotypes. As in earlier
+versions, explicit SNP calls lacking quality fields are retained but counted
+as lacking quality; a threshold cannot validate missing quality.
+
+## Coordinates, precedence, and phasing
+
+Only panel SNPs and explicit SNPs from the trio are considered as targets.
+This retains trio-only phase anchors without expanding every base in a
+reference block. A block starting before the selected region can cover a
+target inside it. END is inclusive.
+
+The block REF identifies the nucleotide at its start only. For an interior
+target, the reference base comes from the panel or an explicit SNP record at
+that position. Inputs must share reference build and contig naming. Known
+build/contig-length conflicts and REF disagreements are rejected; no FASTA
+validation or liftover is performed.
+
+An explicit record always takes precedence at its position, including a
+no-call, failed filter, or unsupported variant. Unsupported variant spans
+also prevent a reference block from filling affected positions. Overlapping
+reference blocks in one input are rejected so a conflicting quality or call
+cannot be selected arbitrarily.
+
+Reference blocks provide homozygous calls, not new heterozygous phase links.
+Existing child variant GT/PS evidence is preserved. A trio-only SNP may orient
+a child phase block when the other members have usable covering reference
+blocks; a missing or rejected parental call cannot provide that anchor.
+
+## Reporting and API
+
+`input_metadata` in `matches.json` records each file's detected format,
+detection evidence, block count, and materialized/excluded reference-call
+counts. These input-processing counts precede the final shared-marker and
+Mendelian filters. Retained SNP records with expanded calls include
+`call_sources` identifying the contributing block. The HTML report summarizes
+input detection; detailed exclusions remain available in JSON and TSV.
+
+Python callers can pass `reference_sites=panel['records']` to either
+`read_trio_vcf` or `read_trio_vcfs`. Without this argument, only explicit trio
+SNP targets can be recovered; reference blocks do not supply an entire local
+reference sequence. The CLI passes the panel's sites automatically.
+
+## Limits and sources
+
+Newer VCF 4.5 sample-specific FORMAT/LEN blocks and implicit GT inheritance are
+not implemented and produce an explicit unsupported-encoding error. This
+restriction avoids applying sample-specific intervals as if they were shared
+END blocks. BCF and indexed random access remain future work.
+
+The implementation uses hard genotypes and confidence fields; it is not a
+replacement for a joint variant caller. It still matches diploid autosomal
+SNP backgrounds and has been tested only on synthetic trios.
+
+- [GATK gVCF format](https://gatk.broadinstitute.org/hc/en-us/articles/360035531812-GVCF-Genomic-Variant-Call-Format)
+- [DeepVariant gVCF support](https://github.com/google/deepvariant/blob/r1.10/docs/deepvariant-gvcf-support.md)
+- [Illumina gVCF conventions](https://help.basespace.illumina.com/files-used-by-basespace/gvcf-files)
+- [VCF 4.5 specification, reference blocks](https://samtools.github.io/hts-specs/VCFv4.5.pdf)

triohap-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 comparativechrono and TrioHap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

triohap-0.4.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md CHANGELOG.md GVCF.md SCN5A.md PUBLISHING.md VALIDATION.txt
+include MANIFEST.in LICENSE
+recursive-include tests *.py
+recursive-include scripts *.py
+recursive-include examples *.vcf *.tsv *.md
+recursive-include reference-data/scn5a-promoter-pangenome *.md *.cff *.yaml *.tsv *.json
+include reference-data/scn5a-promoter-pangenome/LICENSE
+include scn5a-panel/catalogue.json
+include scn5a-panel/panel.snps.tsv
+include scn5a-panel/markers.snps.bed
+include scn5a-panel/audit.json
+include scn5a-panel/validation.json
+recursive-include validation *.json
+global-exclude __pycache__ *.py[cod]

triohap-0.4.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: triohap
+Version: 0.4.0
+Summary: Trio-aware matching of VCF and gVCF genotypes to regional pangenome haplotypes
+Maintainer: comparativechrono
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/comparativechrono/TrioHap
+Project-URL: Documentation, https://github.com/comparativechrono/TrioHap/blob/main/README.md
+Project-URL: Source, https://github.com/comparativechrono/TrioHap
+Project-URL: Issues, https://github.com/comparativechrono/TrioHap/issues
+Project-URL: Changelog, https://github.com/comparativechrono/TrioHap/blob/main/CHANGELOG.md
+Keywords: bioinformatics,pangenome,haplotype,trio,VCF,gVCF
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: plots
+Requires-Dist: numpy>=1.24; extra == "plots"
+Requires-Dist: matplotlib>=3.7; extra == "plots"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Dynamic: license-file
+
+# TrioHap
+
+Rank assembly-derived regional haplotype matches for a child using the child,
+mother and father's SNP genotypes. Show the maternal and paternal assignments
+on a marker-similarity network, preserving ambiguous matches and extra variants.
+
+This is a small, inspectable research prototype, not a clinically validated
+genotyper. Development lives in
+[comparativechrono/TrioHap](https://github.com/comparativechrono/TrioHap).
+The matching engine uses Python's standard library. Plots require NumPy and
+Matplotlib. The PyPI distribution is named **`triohap`**.
+
+Version 0.4 automatically detects VCF and conventional gVCF input, including
+mixed individual files. Both input modes feed the same trio inference model
+and produce the same rankings for equivalent evidence. SCN5A catalogue import
+preserves full haplotype identities and graph topology; see [SCN5A.md](https://github.com/comparativechrono/TrioHap/blob/main/SCN5A.md).
+All trio testing so far is synthetic.
+
+## Installation
+
+Install with Python 3.10 or newer:
+
+```bash
+python -m pip install 'triohap[plots]'
+triohap --version
+triohap --help
+```
+
+For the standard-library matching engine without graph dependencies, install
+`triohap` and pass `--no-plot`. Plotting is optional, but enabled by default in
+the command, so the `[plots]` installation is recommended for normal use.
+
+The package name, command, and Python import are all `triohap`. Older local
+prototype wheels were called `triohap-prototype`; uninstall that distribution
+before installing `triohap`, because both contain the same Python package.
+The wheel contains the application. The source distribution also contains the
+examples, tests, documentation, and SCN5A provenance fixtures; these are not
+installed into Python's package directory. The source archive can be unpacked
+to run the examples below, or use a repository checkout.
+
+## Run the synthetic example
+
+From this directory, with Python 3.10 or newer:
+
+```bash
+python -m pip install '.[plots]'
+python -m triohap \
+  --trio examples/trio.vcf --panel examples/panel.tsv \
+  --child child --mother mother --father father \
+  --region chr1:100-290 --build synthetic \
+  --unfazed-vcf examples/unfazed.vcf \
+  --title 'Synthetic example: two inherited backgrounds' \
+  --out example-run
+python -m unittest discover -s tests -v
+python scripts/validate_synthetic.py
+python scripts/validate_gvcf.py
+```
+
+The expected result is maternal **H1/H1_like** (indistinguishable on observed
+SNPs), paternal **H2**, with an inherited mismatch at position 200. Position
+220 is Mendelian-inconsistent and excluded from the matching score; the
+separate synthetic Unfazed file places its alternate allele on the paternal
+background. Position 240 is present only in the trio file. Position 260 is
+present only in the panel and must not distinguish H1 from H1_like. Position
+280 has a missing father genotype and is excluded.
+
+## Inputs
+
+1. A joint trio VCF/gVCF (`--trio`), or three individual files (`--child-vcf`,
+   `--mother-vcf`, `--father-vcf`), with explicit diploid GTs. VCF versus gVCF
+   is detected automatically from content; no type flag is required. Plain and
+   gzip-compressed inputs are supported. Specify sample names through `--child`,
+   `--mother` and `--father`. Genotype quality filtering is available with
+   `--min-gq`; genotype likelihoods are not used.
+2. A panel VCF with phased diploid or haploid samples, or a tab-separated allele
+   matrix. Each panel column identifies an assembly haplotype. In a diploid VCF,
+   the two phased sample chromosomes become separate panel entries.
+3. One autosomal region, using `CHROM:START-END` (1-based, inclusive).
+4. `--build` records the coordinate reference you assert the inputs use. It is
+   provenance, **not** a liftover or reference-sequence validation procedure.
+
+Panel TSV example:
+
+```text
+CHROM  POS  REF  assembly_A_hap1  assembly_B_hap2
+chr1   100  A    G                A
+chr1   120  C    C                T
+```
+
+Use real tabs, A/C/G/T alleles, and `.` for missing. The same locus/reference
+coordinates must be used in both files. A VCF REF disagreement is an error.
+Allele order may differ: actual nucleotides, not numeric ALT indices, are
+compared. Duplicate positions must be reconciled upstream; this prototype
+does not silently combine split multiallelic records.
+
+Only shared usable SNP calls enter the matching calculation. Missing VCF
+records are **unknown**, never automatically homozygous reference. For gVCFs,
+explicit reference-confidence blocks can supply calls at the panel's SNP
+positions and explicit trio SNP anchors. Blocks must pass the checks described
+below; uncovered positions remain unknown.
+The panel must supply complete calls at each used marker across all candidate
+haplotypes; incomplete markers are dropped globally, with diagnostics.
+
+### Three individual VCFs
+
+```bash
+python -m triohap \
+  --child-vcf examples/individual/child.vcf \
+  --mother-vcf examples/individual/mother.vcf \
+  --father-vcf examples/individual/father.vcf \
+  --child child --mother mother --father father \
+  --panel examples/panel.tsv \
+  --region chr1:100-290 --build synthetic \
+  --out example-run-individual
+```
+
+Supply all three paths together; they cannot be mixed with `--trio`. Each
+sample ID selects a column in its corresponding file. Files may contain
+additional samples. The same sample name (for example `SAMPLE`) is allowed
+in different files; the CLI role specifies which family member it represents.
+
+The reader compares coordinates and REF alleles, decodes each file's ALT
+indices independently, and preserves the child's GT order and PS values.
+Different ALT ordering or different called alternate alleles do not require
+a joint-genotyping step. Known build/contig-length conflicts or disagreeing
+REF alleles are errors; no liftover or allele normalization is performed.
+
+Only sites with usable evidence for **all three** people enter the
+current model. A missing parent record, `./.`, a failed FILTER/FT, or a call
+below the requested GQ threshold cannot be replaced by `0/0`. Exclusions are
+reported. This means variant-only individual VCFs can provide much less
+evidence than joint VCFs with reference calls. Supply gVCFs, explicit all-sites
+VCFs, or targeted genotypes when reference evidence is needed. An explicit
+failed or missing call takes precedence over a covering reference block.
+
+The three-file mode preserves parental uncertainty in exactly the same way
+as the joint mode. It does not infer parental phase from the order of alleles
+in unphased GTs, and it does not equate phase-set numbers across family members.
+
+### Automatic gVCF input
+
+Use the same arguments for `.vcf`, `.g.vcf`, `.gvcf`, or their gzip-compressed
+versions. The filename does not decide the input type. For example:
+
+```bash
+triohap \
+  --child-vcf child.g.vcf.gz --mother-vcf mother.g.vcf.gz --father-vcf father.vcf.gz \
+  --child CHILD --mother MOTHER --father FATHER \
+  --panel scn5a-panel/catalogue.json \
+  --region chr3:38649188-38652187 --build GRCh38 \
+  --min-gq 20 --out family-scn5a
+```
+
+Conventional `INFO/END` blocks with `<NON_REF>`, `<*>`, or nonvariant `ALT=.`
+are supported. Block calls require diploid `0/0`, usable FILTER/FT, and a
+present positive quality meeting `--min-gq`. The most conservative available
+GQ/RGQ/GQX is used for blocks. Known zero DP or MIN_DP excludes a block call;
+missing depth is recorded but does not by itself override usable quality.
+Explicit SNP records may contain an unused wildcard ALT without losing their
+literal genotype calls. Calling the wildcard itself remains unresolved.
+
+Blocks are queried only at relevant SNP positions, including blocks beginning
+before the requested region. Interior reference bases come from the same-build
+panel or explicit SNP records, not the block's first base. The report shows
+detected formats and reference-call counts; JSON records each expanded call's
+source. See [GVCF.md](https://github.com/comparativechrono/TrioHap/blob/main/GVCF.md) for the precise rules and supported encodings.
+
+This consumes hard-called evidence; it does not perform joint genotyping or
+use PL/GL likelihoods. Newer VCF 4.5 sample-specific `FORMAT/LEN` blocks are
+currently rejected with an explicit error. Indel/SV genotypes remain outside
+the matching model.
+
+The prototype accepts neither raw unaligned haplotype FASTA nor a GFA graph.
+First project assembly haplotypes to comparable SNP coordinates, retaining
+their original assembly IDs. FASTA-to-panel preparation is a separate proposed
+module; it must resolve orthology, coordinate mapping and paralog ambiguity.
+
+## Inference
+
+At each Mendelian-consistent SNP, enumerate possible maternal and paternal
+transmitted alleles conditional on the trio GTs. Do not force origin when all
+three are heterozygous. For each ordered pair of panel haplotypes, sum over
+the possible transmissions using mismatch-tolerant emissions. A match has
+weight `1-epsilon`; a different nucleotide has weight `epsilon/3`.
+
+For externally phased child SNPs, marginalize two **whole-block** orientations.
+Informative trio SNPs anchor a block to parental origin. The first GT allele
+is not inherently maternal. Separate PS blocks orient independently. Following
+VCF semantics, phased GTs without PS share an implicit phase set on a chromosome.
+Contradictory Mendelian anchors in one phase block cause an explicit error;
+`--ignore-phase` deliberately discards external phase when investigating it.
+Parent GT phase blocks are not modeled in this first version.
+
+Panel haplotypes identical at the observed, scored markers form one equivalence
+class. Ranking gives each distinct observed class equal prior weight; adding
+duplicate assemblies does not inflate support. Pair scores are normalized
+across **all** ordered class pairs before the top-N rows are reported.
+
+The resulting relative weights are conditional on the chosen panel, markers,
+hard calls, phase and mismatch parameter. They are **not calibrated clinical
+posterior probabilities**. SNPs in LD are not independent observations of an
+ancestral history. The score does not establish unobserved SVs or prove identity
+to an entire assembly sequence. There is no 'none of the above' model: inspect
+absolute mismatches and marker coverage even when relative weight is high.
+
+## Outputs
+
+- `matches.json`: model, provenance, classes, top ordered pairs, marginal
+  rankings, marker evidence and diagnostics. It records input mode and file
+  provenance. Under result schema `0.2`, `sources.trio` is a path for joint
+  input and a role/file/sample object for individual input.
+- `ranked_pairs.tsv`: best maternal/paternal class combinations.
+- `diagnostics.tsv`: omitted, unmatched and problematic records.
+- `mismatches.tsv`: observed alleles differing from the first best-scoring pair.
+- `haplotype_graph.svg` / `.png`: SNP similarity network and observed-allele
+  comparison, with two virtual proband chromosome nodes.
+- `report.html`: self-contained report containing the graph and results.
+
+Graph edges between panel nodes show a deterministic minimum spanning tree
+of Hamming distances over the scored marker signatures. Edge labels count
+different marker alleles. This is a compact similarity network, not a
+genealogy, recombination graph or sequence-level pangenome graph. Dashed colored
+links show leading marginal placements of each proband chromosome, including
+ties. For large panels the image displays a stated subset; the JSON retains
+all classes and marginals. The first listed pair in a tie is not a unique call.
+
+## Optional Unfazed integration
+
+The PyPI package matching the discussion appears to be
+[unfazed-bioinformatics](https://pypi.org/project/unfazed-bioinformatics/), the
+maintained fork of Jonathan Belyeu's Unfazed. Its identity as the user's package
+has not been independently confirmed. It phases de novo variants to parental
+origin; it is not a general regional haplotype matching program.
+
+`--unfazed-vcf` accepts its documented parent-ordered VCF output as **annotation**
+of additional variants. A provenance header stating `1|0 is paternal, 0|1 is
+maternal` is required. Only confident evidence types UET 0/1/2 with phased GTs
+are assigned to a parental background. Ambiguous evidence is retained without
+an assignment. Sex-chromosome autophasing is outside this prototype. UOPS is
+reported as a count, not converted to probability. These annotations do not
+alter the panel ranking, avoiding double-counting the same reads/markers.
+Sample FT filters, obvious declared build conflicts, and disagreements with
+overlapping trio REF/GT calls are checked. Where metadata or trio calls are
+absent, annotation consistency cannot be established from this file alone.
+
+## Scope and next development steps
+
+The current model is diploid, autosomal, SNP-based and fixed to one panel
+haplotype per parental chromosome across the selected region. It excludes
+Mendelian-inconsistent sites rather than estimating de novo or genotyping-error
+probabilities. Indels/SVs/CNVs, sex chromosomes, mosaicism, PL/GL integration,
+within-region recombination, parent phase propagation and a sparse-panel
+missingness model remain future work. FASTA/GFA panel preparation and indexed
+BCF/VCF access are also future work. Large files are streamed but not region
+indexed. The pair search scales quadratically in distinct haplotype classes. Deterministic
+phase contributions are cached; ambiguous-block work is capped at 25 million
+pair/block combinations in this prototype.
+
+Before clinical use: test on independent trios with assembly/long-read truth;
+leave entire families out of the panel; evaluate private variants, phase-switch
+errors, ancestry representation and missingness; calibrate no-call/ambiguity
+criteria and sensitivity to epsilon. Do not infer clinical correctness from
+the synthetic unit tests.
+
+## Development and reproducibility
+
+Run `python -m unittest discover -s tests -v` and
+`python scripts/validate_synthetic.py` from the repository root. The latter
+constructs known inherited haplotypes and independently encodes equivalent
+joint and individual VCFs, then checks truth recovery and matching equivalence.
+It also checks deliberate missingness. These are software correctness checks,
+not estimates of performance on clinical data.
+
+GitHub Actions runs the test suite on Python 3.10–3.13 and exercises graph
+generation separately. `demo-output/` and `demo-individual-output/` contain equivalent synthetic
+reports from the two input modes;
+`scn5a-panel/` contains the imported reference catalogue and its panel audit.
+Source tables used to create that catalogue are retained under
+`reference-data/scn5a-promoter-pangenome/`, with their supplied license and
+provenance. See [CHANGELOG.md](https://github.com/comparativechrono/TrioHap/blob/main/CHANGELOG.md)
+and [VALIDATION.txt](https://github.com/comparativechrono/TrioHap/blob/main/VALIDATION.txt).
+
+Release preparation and the exact PyPI Trusted Publisher settings are in
+[PUBLISHING.md](https://github.com/comparativechrono/TrioHap/blob/main/PUBLISHING.md).
+Packaging CI builds a wheel from the source archive, checks PyPI metadata,
+and tests the installed wheel outside the checkout, including graph generation.
+The project version is maintained in `triohap/__init__.py`.
+
+TrioHap is licensed under the
+[MIT licence](https://github.com/comparativechrono/TrioHap/blob/main/LICENSE).
+The supplied SCN5A reference-data subset retains its own licence and attribution
+under `reference-data/scn5a-promoter-pangenome/`.
+
+The gVCF examples are in `examples/gvcf/`, with a rendered report in
+`demo-gvcf-output/`. Run `python scripts/validate_gvcf.py` to compare known
+synthetic families across ordinary VCF, joint gVCF, individual gVCF, and mixed
+inputs, including deliberate reference-block gaps. The saved summary is
+`validation/gvcf_summary.json`.
+
+## Related components and specifications
+
+- [Osprey](https://github.com/broadinstitute/Osprey): phased SNP reference
+  haplotype matching for CNV/VNTR imputation. Its documented matching uses SNPs
+  outside the target interval; it does not supply this combined trio workflow.
+- [trioPhaser](https://pmc.ncbi.nlm.nih.gov/articles/PMC8607709/): trio-based
+  phasing using Mendelian rules plus statistical phasing.
+- [VCF 4.5 specification](https://samtools.github.io/hts-specs/VCFv4.5.pdf): phase
+  set and genotype semantics.
+- [Unfazed paper](https://academic.oup.com/bioinformatics/article/37/24/4860/6306405)
+  and the maintained PyPI distribution linked above.
+
+No external tool's implementation is incorporated into the matching engine.

triohap-0.4.0/PUBLISHING.md

@@ -0,0 +1,98 @@
+# Publishing TrioHap to PyPI
+
+The first PyPI release is `triohap` version `0.4.0`. The older
+GitHub-only wheels used the distribution name `triohap-prototype`. The import
+package and executable remain `triohap`. Preparing or merging this workflow
+does not publish a package.
+
+## Register the pending publisher
+
+At <https://pypi.org/manage/account/publishing/>, select **GitHub** and enter:
+
+| Field | Exact value |
+| --- | --- |
+| PyPI project name | `triohap` |
+| Owner | `comparativechrono` |
+| Repository name | `TrioHap` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+Enter only `publish.yml`, not `.github/workflows/publish.yml` and not the workflow
+display title. The workflow lives at `.github/workflows/publish.yml`.
+There is no PyPI API token or GitHub secret to create. The pending publisher
+creates the PyPI project on its first successful use; it does not reserve the
+name. The project name in PyPI must match the distribution metadata.
+
+The GitHub environment `pypi` is configured to allow tags matching `v*` only.
+No secrets are needed. The current private-repository settings do not offer a
+required-reviewer gate; publishing a GitHub release is the deliberate publishing
+action. Keep release and workflow changes restricted to trusted maintainers.
+
+## Validate without publishing
+
+The **Build and publish to PyPI** workflow offers **Run workflow**. A manual run
+builds and validates the distributions and saves them as a workflow artifact;
+its publishing job is always skipped. Pushes and pull requests also run the
+distribution checks in the ordinary CI workflow.
+
+To run the same checks locally, from a clean checkout and virtual environment:
+
+```bash
+python -m pip install '.[dev]'
+python -m build
+python -m twine check --strict dist/*
+python scripts/validate_distribution.py --dist-dir dist --tag v0.4.0 --plots
+```
+
+Use an empty `dist/` directory for each version. `python -m build` creates a
+source archive and builds the wheel from that archive. Validation checks
+metadata, the entry point, runtime version, source/wheel module equality,
+reproducibility fixtures, and installed command behavior. It runs the complete
+unit suite against an isolated wheel installation outside the checkout,
+exercises joint VCF and individual gVCF inputs, and checks plot generation.
+The source archive is rebuilt independently, compared with the release wheel,
+and checked in a separate installation with both CLI examples. Plot dependencies
+are optional at runtime.
+
+## Publish a version
+
+1. Register the pending publisher above before publishing the first release.
+2. Preserve the root MIT `LICENSE` and the `MIT` SPDX expression in project
+   metadata. The source and wheel archives must include that licence. The
+   supplied reference-data subset retains its separate MIT licence and
+   attribution under `reference-data/scn5a-promoter-pangenome/`.
+3. Set `__version__` in `triohap/__init__.py` and update `CHANGELOG.md`. Package
+   metadata reads that version automatically. For the first release it is
+   `0.4.0`, and the tag must be exactly `v0.4.0`.
+4. Merge the release changes into `main` and confirm CI passes.
+5. Publish a GitHub release with the matching tag, targeting the tested commit.
+   A draft does not publish. Both published releases and published GitHub
+   prereleases trigger uploading; the Python version controls whether PyPI
+   treats the distribution as a prerelease. Use a version such as `0.4.1rc1`
+   for an actual Python prerelease, with tag `v0.4.1rc1`.
+6. Confirm the **Build and publish to PyPI** run succeeds and inspect the new
+   PyPI project/version. Then test installation in a fresh environment:
+
+   ```bash
+   python -m pip install 'triohap[plots]==0.4.0'
+   triohap --version
+   ```
+
+The build job checks the release tag against the built metadata and runtime
+version. Only its validated wheel and source archive are handed to the separate
+publishing job. That job runs in `pypi`, requests a short-lived OIDC identity,
+and uses PyPA's publishing action with attestations enabled by default. It does
+not execute the source checkout or hold a persistent PyPI token. Actions are
+pinned to reviewed upstream commits.
+
+Pushing a tag alone, pushing a branch, opening a pull request, and manually
+running the validation workflow do not publish. The existing `v0.3.0` release
+does not trigger retroactively. Do not reuse a version already uploaded to
+PyPI; publish a new version for corrections. No TestPyPI publisher is configured.
+
+## References
+
+- [PyPI pending publishers](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- [PyPA release workflow guidance](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
+- [PyPI Trusted Publishing security model](https://docs.pypi.org/trusted-publishers/security-model/)
+- [PyPA publishing action](https://github.com/pypa/gh-action-pypi-publish)