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.
- Version 0.1.0: 10.5281/zenodo.22113715
- All versions: 10.5281/zenodo.22113714
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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.