Metadata-Version: 2.4
Name: kasm-pkg
Version: 0.1.0
Summary: Kernel allelic series model for rare-variant heritability from exome summary statistics.
Keywords: genetics,heritability,rare variants,exome,summary statistics
Author: Kangcheng Hou
Author-email: Kangcheng Hou <kangchenghou@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: clarabel>=0.11.1
Requires-Dist: numpy
Requires-Dist: polars>=1.30
Requires-Dist: scipy
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: cvxpy>=1.7.5 ; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8.0 ; extra == 'dev'
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/KangchengHou/kasm-pkg
Project-URL: Documentation, https://github.com/KangchengHou/kasm-pkg/blob/main/DOCS.md
Provides-Extra: dev
Description-Content-Type: text/markdown

# KASM

The Kernel Allelic Series Model (KASM) integrates functional annotations to
form a covariance kernel describing how allelic effects within a gene covary.
Using data from exome association studies, KASM estimates the heritability of
rare protein coding variants, its enrichment in structural and functional
annotations, and the concordance of effects between pairs of variants. Our
paper describes the methodology and applications in detail.

KASM can be installed with `pip install kasm-pkg` or `uv add kasm-pkg`.

[Documentation](https://github.com/KangchengHou/kasm-pkg/blob/main/DOCS.md) · [Quick start](#quick-start) · [Development](#development)

## Quick start

Here is an example of using KASM to estimate heritability from exome-wide
association statistics. KASM takes variant-level association statistics: one
row per variant, with a canonical `chr:pos:ref:alt` ID, its gene, the effect
estimate and SE, allele frequency, and annotations used as burden weights.
Within-gene LD comes from an LD matrix file passed to `Dataset` as `ldm`;
without one, as in this toy example, KASM assumes no LD between variants.

```python
import kasm
import polars as pl

variant_df = pl.DataFrame(
    {
        "variant": [f"1:{pos}:A:G" for pos in range(100, 1000, 100)],
        "gene": ["G1"] * 3 + ["G2"] * 3 + ["G3"] * 3,
        "beta": [-0.12, 0.19, -0.15, 0.01, 0.17, -0.05, 0.15, 0.25, 0.22],
        "se": [0.10, 0.12, 0.09, 0.11, 0.10, 0.13, 0.08, 0.10, 0.12],
        "af": [2e-4, 5e-5, 3e-4, 1e-4, 2e-4, 4e-5, 5e-4, 2e-4, 6e-5],
        "constant": 1.0,
        "score1": [0.9, 0.1, 0.0, 0.9, 0.1, 0.0, 0.1, 0.8, 0.9],
        "score2": [0.8, 0.3, 0.1, 0.7, 0.2, 0.0, 0.3, 0.6, 0.9],
    }
)
print(variant_df)

dataset = kasm.Dataset(variant_df, beta_col="beta", se_col="se", sample_size=300_000)
model = kasm.Model(
    dataset,
    kasm.KernelOptions(
        maf_col="af",
        burden_cols=["constant", "score1", "score2"],
        overdispersion_cols=["constant"],
    ),
).compute_suffstats()
fit = kasm.fit_random_effects(model, exclude_genes=[], n_jk_blocks=3)
print(f"heritability: {fit.hsq:.2e} (SE {fit.hsq_se:.2e})")
print(fit.components.select("kernel", "kernel_coef", "kernel_coef_se"))
```

See more examples in the [documentation](https://github.com/KangchengHou/kasm-pkg/blob/main/DOCS.md).

## Development

Development uses [uv](https://docs.astral.sh/uv/):

```bash
uv run --extra dev pytest
uv run --extra dev pytest --full
uv run --extra dev pre-commit install
```
