Skip to main content

Asterism ⁂

Asterism is statistical software for fitting the kinds of variance-component models typically found in quantitative genetics. It comprises a compiled numerical core written in Rust and a Python API, which takes NumPy arrays and returns ordinary Python objects.

Two important things to note before using Asterism in your own research. First, almost every Asterism capability can be replicated in other software by design — care has been taken to ensure the numbers you get from Asterism closely match those from SOLAR or R wherever they have the same capabilities. Second, Asterism code is 100% AI authored. I (Sam Mathias) planned development carefully and I stand by the results, but I did not write the code myself. If this bothers you, feel free to use the code provided here to replicate analysis in other software.

Installation

Wheels are published for macOS on Apple silicon and for Linux on x86-64, and carry a compiled binary, so nothing is built on your machine and no Rust toolchain is needed. Python 3.13 or 3.14. The only runtime dependency is NumPy. Install in the usual way:

pip install asterism

To work on Asterism itself, see development.md.

Quickstart

The following builds a pedigree, simulates one trait with a true heritability of 0.5, and fits it — no data required.

import numpy as np
import asterism

FAMILIES, CHILDREN = 80, 4

# Two founders and four full siblings per family.
parents = [(f"{f}-dad", f"{f}-mum") for f in range(FAMILIES)]
ids = [name for pair in parents for name in pair] + [
    f"{f}-child{c}" for f in range(FAMILIES) for c in range(CHILDREN)
]
father = [None] * (2 * FAMILIES) + [
    parents[f][0] for f in range(FAMILIES) for _ in range(CHILDREN)
]
mother = [None] * (2 * FAMILIES) + [
    parents[f][1] for f in range(FAMILIES) for _ in range(CHILDREN)
]

relationship, order = asterism.relationship_matrix(ids, father, mother)
people = len(order)

# Simulate a trait that really is 50% heritable.
covariance = 0.5 * relationship + 0.5 * np.eye(people)
trait = np.linalg.cholesky(covariance) @ np.random.default_rng(0).normal(size=people)

model = asterism.prepare(np.ones((people, 1)), relationship)
fit = model.fit(trait)          # REML by default

print(f"h2 (true 0.5): {fit['h2']:.3f}")
print(f"95% interval:  [{fit['interval']['lower']:.3f}, {fit['interval']['upper']:.3f}]")
print(f"p (h2 = 0):    {fit['test']['p_value']:.2e}")
h2 (true 0.5): 0.605
95% interval:  [0.455, 0.745]
p (h2 = 0):    1.11e-19

Every capability has a complete runnable program behind it in examples/, which lives in the repository rather than in the installed package.

Capabilities

Eight models are currently supported. Each one has checks that measure it against a known truth or an independent implementation. They are listed in api-support.md, which also names the public objects that fall outside current support (models whose numbers have not been established to the same standard yet; see outside-support.md).

Capability Runnable example
One trait, one component quickstart.py
Several components components.py
Two traits bivariate.py
Binary traits liability.py
Censored traits censored.py
Mixed pairs mixed.py
Gene by environment, measured gxe.py
Gene by environment, binary discrete_gxe.py

Matrices can come from anywhere. relationship_matrix builds one from a pedigree and kinship_classes splits a pedigree into separate bases, but every model accepts any finite, symmetric, positive-semidefinite matrix — a genomic relationship matrix, an estimated kinship, whatever you have. align lines a matrix up with your values by identifier, which matters because the numerical interface is positional and a misaligned fit does not warn, it silently destroys the signal.

Each model has a page of its own carrying everything it needs: how to use it, its equations, a summary of what has been measured about it, and its interface. What they share is in statistical-methods.md, the comparisons and simulations in full are in the validation record, and the whole public surface in the API reference.

For an analysis whose provenance has to be recorded — which wheel, which commit, which inputs — run_analysis returns a receipt alongside the fit. See analysis-receipts.md.

Citing Asterism

Cite the version you actually ran. A development checkout is not a citable version: only a release wheel carries the build identity a result can be traced to.

CITATION.cff carries the second, so GitHub's "Cite this repository" and most reference managers will pick it up.

Licence

MIT. See LICENSE.

Asterism is original work that depends on third-party packages used under their own licences. It has no affiliation with any other quantitative genetics package. Where its answers are compared with other software packages or a published analysis, those are benchmarks not dependencies.

Metadata

Release files for asterism 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for asterism 0.1.1
File Interpreter ABI Platform Actions
asterism-0.1.1-cp313-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.13 abi3 Linux glibc 2.17+ x86-64 Details for asterism-0.1.1-cp313-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
asterism-0.1.1-cp313-abi3-macosx_11_0_arm64.whl CPython 3.13 abi3 macOS 11.0+ ARM64 Details for asterism-0.1.1-cp313-abi3-macosx_11_0_arm64.whl

Total release size: 3.1 MB

Release files / asterism-0.1.1-cp313-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL asterism-0.1.1-cp313-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 1.9 MB
Tags CPython 3.13 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
c96d222417e6c27e58c98f12ea6b9d1ac69b7bcdb68b55857163bb9101b1bb63
BLAKE2b-256 checksum
How to use checksums
3b5d7110e7a4b3c5d53c298704b05737a5377f3ab86a7173ca5853c7592314ae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / asterism-0.1.1-cp313-abi3-macosx_11_0_arm64.whl

Download URL asterism-0.1.1-cp313-abi3-macosx_11_0_arm64.whl
Size 1.3 MB
Tags CPython 3.13 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
e93cddf23c770635772df35db58a1291c239d46d8694bd87c46727f9bc1c93ea
BLAKE2b-256 checksum
How to use checksums
89038e6037879802aa68593e0601f1abf91a66b0a667929728b485cf68fe2598
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for asterism 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page