OnePhylogeny

A source-available, species-agnostic framework for acquiring sequence evidence, building reference panels and testing samples against them, with provenance and honest uncertainty. For developers, labs, researchers and keepers.

Status: early alpha. The core science, NCBI acquisition, engine, CLI, React views, bridges, Payload plugin and Mac app work and are tested. The packages are on npm as early alphas, the Mac app isn't notarized, and results aren't forensically validated. See the roadmap and limitations.

OnePhylogeny is part of the OneOrigin suite: three independent tools, with no subscriptions, that work alone or together.

Tool	Question it answers
OneTaxonomy	What do sources claim, and how do we browse those classifications and trees?
OnePedigree	How is this individual related to known relatives?
OnePhylogeny	Given DNA, what does the evidence support, and where does this sample fit?

Principles

• Species agnostic. No taxon, gene, region or threshold is hardcoded. A test fails if package source names a taxon.
• Everything is programmatic and saved. Profiles describe a run; runs are immutable records of what actually happened.
• Evidence is traceable. Every record keeps its accession version, hash, publication and provenance class.
• Honest results. Results are candidate sets, including not_evaluable; no shared sites never means excluded.
• Your sources, your choice. OnePhylogeny ships adapters, not authoritative data or panels.

The full rules are in scientific invariants.

Packages

Package	What it does
onephylogeny-core	Records, GenBank and FASTA parsing, pure TypeScript reference anchoring, gates, haplotypes, panels, sample evaluation, hold-out validation. No dependencies
onephylogeny-acquire	NCBI searches and downloads with safe retries; outgroup suggestions outward through the taxonomy; SRA, BioSample and NCBI Datasets listings, and GBIF, iDigBio and BOLD counts, never coordinates
onephylogeny-engine	Runs from profiles: fetch, anchor, gate, build panels, test samples, build trees, with immutable records and logs
onephylogeny-cli	The onephylogeny command
onephylogeny-react	Sample results and reasons, coverage, validation, logs, trees and a compact lineage card
onephylogeny-onetaxonomy	Optional: exports trees as OneTaxonomy phylogenies
onephylogeny-onepedigree	Optional: checks results against OnePedigree maternal lines
payload-plugin-onephylogeny	Payload: immutable panels and reviewed, released results
apps/desktop	OnePhylogeny for Mac (Tauri 2)

All published under @extantape/.

How it runs

onephylogeny outgroups --workspace DIR --profile ID   # suggest outgroups outward from the ingroup
onephylogeny fetch     --workspace DIR --profile ID   # download, anchor, gate; write the sheet and log
onephylogeny panel     --workspace DIR --profile ID   # build and validate a panel
onephylogeny test      --workspace DIR --profile ID --fasta sample.fasta
onephylogeny tree      --workspace DIR --profile ID   # needs IQ-TREE
onephylogeny trace     --workspace DIR --profile ID --type T --key K   # everything that produced an artifact
onephylogeny sources   --taxon NAME_OR_TAXID   # what SRA, NCBI Datasets, GBIF, iDigBio and BOLD list; counts only, never coordinates

A profile is plain JSON and holds every choice: taxa, marker, reference, filters, outgroups, groups and rules.

sources needs the network and no profile. It lists and counts, and downloads nothing: SRA runs, genome assemblies, and how many GBIF, iDigBio and BOLD records there are by country. These say what exists, not where any animal came from. A service that doesn't answer is named and the command exits 1, so a missing count never reads as zero. The Mac app shows the same under Public data in the Study tab, when you press its button.

Install the Mac app

Download the latest .dmg from this repository's Releases page (tags desktop-v*) and drag OnePhylogeny to Applications. The app isn't notarized, so macOS blocks the first launch. Use either way past the warning:

• System Settings: try to open the app once, then go to System Settings > Privacy & Security, scroll down, click Open Anyway, and click Open when the warning comes back. Apple says to do this only for an app you trust.
• Terminal: xattr -dr com.apple.quarantine "/Applications/OnePhylogeny.app"

It can't update itself yet: download the newest .dmg to update.

Develop

pnpm install
pnpm build && pnpm typecheck && pnpm test
pnpm --filter onephylogeny-desktop app:dev   # the Mac app
pnpm --filter @extantape/onephylogeny-playground build   # every view on invented data: open apps/playground/dist/index.html
pnpm --filter onephylogeny-desktop dev       # browser preview with made-up data

Documentation

• Tutorial: build a panel, test samples and read a report on example data, offline, then the concept pages
• Architecture, data schema, technical decisions, owner decisions
• The OneOrigin suite and its guidelines (draft)
• Analysis protocol: what results can claim, and the rules fixed before testing
• Roadmap, phase plan, limitations

Changes are listed in the changelog.

License

PolyForm Noncommercial 1.0.0 for the software: free for noncommercial use, with attribution; commercial use needs a separate license from EXTANT APE. Data you import keeps its own license. This software is research tooling and is not forensically validated.