Astetik — Scientific figures with evidence

Scientific figures from a declared specification and shared design, with numerical output and verifiable provenance.

Astetik compiles supplied data, a finite plot specification, and one design manifest into a figure and its evidence. Declare the scientific decision and visual encoding, inspect the computed values and their origins, then retain the result for publication and bounded replay. Python, notebooks, and command-line agents use the same contracts.

What Astetik Is Not

Astetik owns validation, rendering, supported statistical protocols, publication checks, and evidence bundles. Researchers own data preparation, sampling, study design, method selection, and interpretation. Astetik does not infer those decisions or establish independence, causality, or scientific suitability.

The product boundary defines that responsibility. Imports do not change notebook-global plotting styles; design is applied within the declared rendering workflow.

Capabilities

The plot catalogue covers 30 kinds, each with a paper path, including animation posters and table/text evidence.

Color binds to meaning and category identity across figures. Set your study's primary with manifest.with_primary("#235B60"); primary-bound categories update together. The manifest reference owns palette, contrast, typography, and physical-size rules.

First successful figure

Install the current 2.0 API from PyPI:

python -m pip install astetik

Use Python 3.11 or later. The example reads the bundled country/area metadata; no data download or invented research measurements are needed. Choose a new output directory; existing destinations are rejected.

from importlib.resources import as_file, files
from pathlib import Path
import astetik as ast

manifest = ast.Manifest(categories={
    "Africa": "primary", "Americas": "#A54532", "Asia": "#2D7D60",
    "Europe": "#7D5595", "Oceania": "secondary",
})
spec = {
    "schema_version": "1.0", "kind": "count", "x": "region",
    "key": ["alpha-3"],
    "order": ["Africa", "Americas", "Asia", "Europe", "Oceania"],
    "missing": "drop",
    "missing_reason": "The bundled metadata does not assign a region to these rows.",
    "options": {"orient": "h"},
    "title": "Recorded geographic entries by region",
    "paper": "double",
}
resource = files("astetik").joinpath("extras", "countries.csv")
with as_file(resource) as source:
    result = ast.render(source, spec, manifest)

assert result.table["estimate"].tolist() == [60, 57, 51, 51, 29]
assert result.receipt["observations"]["used"] == 248
assert result.verify()["passed"]
print(result.table[["category", "estimate"]].to_string(index=False))

bundle = result.write(Path("country-regions"))
repeated = ast.replay(bundle)
assert repeated.result_id == result.result_id
assert repeated.verify()["passed"]
print(bundle.resolve())

Expected result: Africa 60, Americas 57, Asia 51, Europe 51, and Oceania 29, followed by the absolute path of country-regions. Of the 249 retained geographic entries, 248 contribute; Antarctica (ATA) has no region and is explicitly excluded and accounted for. These counts describe the shipped snapshot, not a current geopolitical reference or a scientific inference. The first-figure guide owns the source and observation accounting.

render returns an EvidenceResult: a figure, numerical table, declarations, receipt, and mark-to-observation origins. paper="double" selects a 178 mm figure; use paper="single" for 89 mm, or paper=True for the manifest's declared preset. Verification checks the final physical artifact before publication. The paper-figure guide covers design revisions and failures.

Retain the evidence

The same evidence can be inspected and repeated from a shell or an agent:

astetik catalog
astetik replay country-regions

The bundle guide covers inspection, publication, and replay; the command-line reference defines JSON output and structured failures.

Risk Boundary

Strict replay requires the recorded compatibility envelope and verifies exact regenerated SVG plus scientific evidence. Explicit recomputation in a changed environment retains numerical and provenance checks without claiming identical rendering. Unsigned receipts establish integrity relative to retained evidence; they do not establish authorship or the truth of observations.

Publication checks cover declared dimensions, visible type sizes, font/glyph identity, clipping, and selected tick/table collisions. Journal-specific requirements and other graphical collisions remain the researcher's responsibility. The evidence reference defines these bounded contracts.

Choose the next task

Agents start with the scientific workflow, ast.catalog(), and ast.select(intent). Installed documentation entry points live beside astetik.__file__ under docs/. Structured AstetikError fields support recovery by correcting declarations rather than substituting a method.

Contributing

Start with CONTRIBUTING.md and developer setup and validation. Propose work through Autonomio Astetik issues.

Support

Use SUPPORT.md for bug reports, feature requests, and usage questions. Include Astetik and Python versions, the specification, manifest, result identifier, and full relevant error. Use small shareable actual data for a reproduction.

Vulnerabilities

Use SECURITY.md for supported source and the private reporting route. Arrange a private channel with the maintainer when private vulnerability reporting is unavailable. Do not put exploitable details or credentials in public issues.

Citations

Use CITATION.cff for software citation metadata. A reproducible research citation should identify Astetik, its exact version or source commit, and the retained specification, manifest, and result identifier. No DOI is supplied.

License

MIT License. Third-party notices retain template attribution and Finlandica's separate font license.