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.
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.
The plot catalogue covers 30 kinds, each with a paper path, including animation posters and table/text evidence.
| Research task | Supported capability |
|---|---|
| Choose a representation | Inspect the catalogue and intent guidance for supported plots, defaults, and constraints |
| Keep a study visually coherent | One immutable manifest controls typography, axes, dimensions, and semantic color bindings |
| Prepare a paper figure | Single- or double-column physical sizes, vector exports, retained fonts, and final-size verification |
| Declare a scientific computation | Explicit supported estimation, resampling, comparison, association, regression, and longitudinal protocols |
| Inspect what a mark means | Numerical tables, original input positions, observation identities, methods, and verified upstream preparation receipts |
| Audit and repeat a result | Sealed evidence, atomic publication, integrity checks, strict replay, and comparison of changed results |
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.
Install the current 2.0 API from PyPI:
python -m pip install astetikUse 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.
| File | Retained evidence |
|---|---|
figure.pdf, figure.svg, figure.png |
Vector figures and a raster companion |
input.json, input.csv |
Exact typed input snapshot and a readable companion |
summary.json, summary.csv |
Numerical output and a readable companion |
spec.json, manifest.json |
Resolved scientific and design declarations |
marks.json |
Mark values, computations, and contributing observation origins |
receipt.json |
Source, methods, environment, verification, result identity, and artifact digests |
font.ttf, font-notices.txt |
Selected font bytes and notices for the bundled families |
The same evidence can be inspected and repeated from a shell or an agent:
astetik catalog
astetik replay country-regionsThe bundle guide covers inspection, publication, and replay; the command-line reference defines JSON output and structured failures.
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.
| Job | Start here |
|---|---|
| Create and inspect a first figure | First figure |
| Use final paper dimensions and study colors | Paper figure |
| Declare a method for measured study data | Research protocols |
| Select a plot and its supported options | Plot catalogue |
| Integrate verified prepared data | Data and Prepared |
| Retain, inspect, and repeat evidence | Evidence bundle |
| Integrate Python or a command-line agent | Specification; command line |
| Replace an older notebook call | Migration |
| Navigate the whole manual | Documentation hub |
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.
Start with CONTRIBUTING.md and developer setup and validation. Propose work through Autonomio Astetik issues.
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.
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.
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.
MIT License. Third-party notices retain template attribution and Finlandica's separate font license.