How to Reconstruct Ancestral DNA Sequences with ancseq and IQ-TREE

Table of contents

• Scientific introduction
  • What the task means
  • Why reproducible inputs matter
  • Method and interpretation
  • Validation strategy
  • Common failure modes
  • How to inspect the output
  • Using the result responsibly
  • Scaling beyond the demonstration
  • Quality assurance
  • Reading quantitative evidence
  • Provenance and auditability
• Test progress
• Demo user request
• Demo data
• Validated workflow
• Results and artifacts
• Installation and transparent reproduction
• Reproducibility
• Limitations
• References
• Try this workflow

The validated workflow selected the IQ-TREE model from the supplied alignment, rooted the analysis with AVR-Mgk5_GE16_2, reconstructed 13 ancestral records, and produced all six required final deliverables. The sorted state table contained 68,807 bytes of explicit state probabilities; intermediate IQ-TREE files were not misreported as final results. This result passed native execution, real chat-driven execution, and semantic artifact validation in retained attempt 1. It should be interpreted only within the limits of the supplied demonstration.

Scientific introduction

What the task means

A useful maximum-likelihood ancestral sequence reconstruction workflow must separate a computable output from the broader scientific claim a reader may be tempted to make. Inputs need declared provenance, algorithms need named versions, and outputs need units or an explicit statement that they are dimensionless. Validation should test internal consistency and expected behavior, while interpretation should stay within the scope of the data. This distinction matters because a technically valid file can still support an invalid scientific conclusion. The retained run therefore records both the result and the boundary around that result.

Why reproducible inputs matter

Reproducibility begins before execution. A small, inspectable input makes assumptions visible and lets another investigator distinguish data errors from software errors. The demonstration uses data/sources.json, the retained provenance manifest for the declared nucleotide alignment and upstream example source. This fixture is intentionally bounded: it exercises a representative path without pretending to cover all possible experimental designs. Preserving the exact input beside the command and outputs also prevents a common failure in computational work, where a polished report survives but the parameters that created it disappear.

Method and interpretation

The demonstrated method is ancseq DNA-mode orchestration with IQ-TREE maximum-likelihood tree and ancestral-state inference. A method name alone is insufficient: version, execution mode, accelerator, and whether physical hardware was involved change what the result means. Here the run was performed on Linux x86_64 with CPU execution. Its central observation is: The validated workflow selected the IQ-TREE model from the supplied alignment, rooted the analysis with AVR-Mgk5_GE16_2, reconstructed 13 ancestral records, and produced all six required final deliverables. The sorted state table contained 68,807 bytes of explicit state probabilities; intermediate IQ-TREE files were not misreported as final results. That statement is deliberately quantitative and qualified. It is evidence for the tested case, not an unrestricted performance or accuracy claim.

Validation strategy

Three layers were required. Native execution established that the installed package could perform the key calculation. A natural-language chat request then tested whether the skill instructions could cause the same scientific intent to be translated into a runnable workflow. Finally, a semantic validator inspected fields, counts, signs, expected values, and safety flags rather than merely checking that files existed. This layered approach catches empty artifacts, plausible fabricated summaries, wrong units, and outputs generated by unrelated code.

Common failure modes

Installation success is not scientific success. Dependency resolution can choose incompatible versions, scripts can import the wrong module, and a command can exit successfully while producing incomplete output. At the interpretation layer, users may confuse simulation with experiment, a score with a physical measurement, or a planning draft with an approved document. The test therefore fails closed: missing deliverables, failed semantic assertions, unsupported claims, or a blocked chat run prevent publication.

How to inspect the output

Start with the human-readable report, then inspect machine-readable artifacts. Confirm identifiers, units, row counts, numeric ranges, and explicit status fields. Compare the report against source data rather than trusting prose in isolation. For calculated values, independently evaluate a known identity or expected example when available. For workflow records, count the underlying operations. For drafted documents, trace every number and consequential claim back to the brief or an authoritative source.

Using the result responsibly

A result becomes useful when its intended decision is stated. This demonstration answers whether a defined small workflow can execute and produce internally consistent artifacts. It does not answer every downstream question in the domain. Readers should decide in advance what evidence would cause them to accept, repeat, revise, or abandon a workflow. That decision rule reduces hindsight bias and prevents a successful software run from being promoted into stronger evidence than it provides.

Scaling beyond the demonstration

Larger inputs add more than runtime. They increase opportunities for malformed records, numerical instability, hidden defaults, version-sensitive behavior, and difficult review. Scale gradually: add one source of complexity at a time, preserve a known-good case, and compare new outputs against it. Use checksums and environment manifests for high-value work. When stochastic methods or experimental measurements enter the workflow, add replicates, uncertainty estimates, and domain-appropriate controls rather than relying on a single successful execution.

Quality assurance

Quality assurance should be proportional to consequence. Exploratory work may need schema checks and visual inspection; decisions affecting experiments, funding, clinical work, or expensive hardware require independent review and formal controls. Automated validation is valuable because it is repeatable, but it cannot determine whether the original scientific question was well posed. A domain expert should review assumptions, exclusions, and the relationship between the computed endpoint and the real decision.

Reading quantitative evidence

Quantitative evidence should be read with its representation in mind. Counts describe discrete events, continuous values require units and precision, model scores require a documented scale, and logical flags record a decision made by a validator. Extra decimal places do not create extra scientific certainty. The most defensible report preserves the original machine value while explaining how many digits matter for interpretation. It also states whether uncertainty was calculated. When no uncertainty estimate is available, the report should not imply confidence intervals, repeatability, or population-level accuracy. In this case the retained fields are treated as deterministic outputs of a defined fixture and software version. Their agreement with an expected identity, operation morphology, bundled example, or source brief is a software validation check. It is not a substitute for experimental replication, prospective evaluation, or formal review. Readers should therefore quote the observed result together with the method, attempt, and limitation rather than extracting an isolated number.

Provenance and auditability

A trustworthy computational narrative connects every claim to evidence. The fixture identifies what entered the workflow; the environment record identifies what executed it; the artifact inventory identifies what emerged; and the semantic report explains why those outputs passed. Cryptographic digests help detect accidental replacement, but a checksum only establishes byte identity, not scientific truth. Likewise, a screenshot demonstrates presentation in the application but cannot prove that the displayed calculation was honestly produced. This dossier uses both provenance and independent semantic assertions so that each evidence type does the job it can actually support. For long-lived projects, record licenses, upstream release locations, retrieval dates, and transformations in addition to hashes. If an input contains confidential or personal information, apply access control and minimization before preservation. Auditability should never become an excuse to retain secrets unnecessarily. The practical objective is a reviewable chain that another qualified person can follow without relying on memory or on an unqualified summary.

Test progress

Demo user request

Use the source manifest sources.json to obtain its declared test_nt.fasta alignment, reconstruct DNA ancestors with ancseq in fast IQ-TREE mode, root with AVR-Mgk5_GE16_2, and preserve the final tree, ancestral FASTA files, state table, and codon probabilities.

The request is intentionally phrased as a scientific objective rather than a shell command. It names the desired endpoint and constraints while leaving the installed instructions to select the transparent execution path.

Demo data

The retained input is data/sources.json, the retained provenance manifest for the declared nucleotide alignment and upstream example source. It is small enough to inspect directly and has no claim of representing a population, production run, or comprehensive benchmark. The input belongs to this test dossier, so a reviewer can reconstruct the exact input → method → output relationship.

Validated workflow

The workflow first inspected the skill contract, then checked or installed the bounded dependency set, executed the native key feature, and repeated the intent through a real chat request. Required artifacts were preserved before validation. The validator read scientific content rather than accepting filenames. No cleanup removed the environment, allowing a later failure investigation to examine the exact retained state.

input fixture → validated package runtime → key-feature execution
             → structured artifacts → semantic assertions → report

This sequence is especially important because a language model can write a persuasive answer without executing the correct package. Native evidence anchors the calculation, while chat evidence demonstrates that a user-style request reaches the intended path. Semantic checks prevent either route from receiving credit for an unrelated or fabricated artifact.

Results and artifacts

The validated workflow selected the IQ-TREE model from the supplied alignment, rooted the analysis with AVR-Mgk5_GE16_2, reconstructed 13 ancestral records, and produced all six required final deliverables. The sorted state table contained 68,807 bytes of explicit state probabilities; intermediate IQ-TREE files were not misreported as final results.

The focused application capture shows the validated report rather than a file list, raw JSON editor, or prompt composer. It is tied to the retained report through the screenshot manifest and SHA-256 digest.

The table image is generated from retained output fields. It provides a compact visual check while the underlying machine-readable artifact remains the authoritative source.

The inventory records actual deliverables and byte sizes. A non-empty artifact is necessary but not sufficient; the semantic validator remains the criterion for scientific pass status.

Installation and transparent reproduction

The validated path used the skill-provided installer or bounded runtime wrapper rather than an unrelated system executable. Package downloads remained below the local lightweight-test ceiling. Environments were retained under the managed local prefix so failures can be repaired without discarding evidence. Exact commands are intentionally kept in case.json and the attempt logs, where quoting and resolved paths can be audited.

python test/scientific-skills/run_skill_cycle.py ancestral-reconstruction
python test/scientific-skills/skills/ancestral-reconstruction/chat_e2e.py
python test/scientific-skills/validate_how_to.py test/scientific-skills/skills/ancestral-reconstruction

These commands are reproducibility details, not a requirement that a scientific user become a programmer. They make the tested chain inspectable and help developers diagnose dependency or prompt failures.

Reproducibility

The recorded attempt identifier is 1 and the validation date is 2026-07-26. The host was Linux on x86_64, using CPU execution and no CUDA validation. The principal method was ancseq DNA-mode orchestration with IQ-TREE maximum-likelihood tree and ancestral-state inference. Screenshot and visual-asset manifests store provenance, generator or Playwright specification, source artifact, focused locator where applicable, capture route, timestamp, and SHA-256 digest.

For an independent repetition, preserve the exact fixture, compare dependency versions, rerun the native calculation, rerun the natural-language case, and apply the semantic validator before interpreting the report. A changed upstream version should be treated as a new validation condition rather than silently assumed equivalent.

Limitations

Ancestral sequences are model-based reconstructions, not directly observed historical molecules. The small demonstration does not test alignment uncertainty, alternative substitution models, topology uncertainty, recombination, horizontal transfer, taxon sampling, or experimental resurrection.

The demonstration is deliberately small and cannot measure performance at production scale. It does not establish regulatory compliance, clinical validity, universal scientific accuracy, or fitness for a consequential use. External services and rapidly changing official policies should be checked again at the time of use. Human review remains necessary whenever the output informs experiments, spending, hardware operation, or formal submission.

References

• IQ-TREE 2: New Models and Efficient Methods for Phylogenetic Inference
• Maximum-likelihood ancestral reconstruction in IQ-TREE
• ancseq project documentation

Try this workflow

MindPlot has built-in support for the demonstrated scientific skill. Users can state the scientific goal in ordinary language; the MindPlot agent writes and runs the necessary code from the installed skill, preserves deliverables, and presents the result for inspection. Try it at https://mindplot.ai, or download the desktop version for a better integrated experience and stronger local-data privacy.