kasm-pkg 0.1.0__tar.gz

kasm_pkg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kangcheng Hou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kasm_pkg-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+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
+```

kasm_pkg-0.1.0/README.md

@@ -0,0 +1,65 @@
+# 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
+```

kasm_pkg-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "kasm-pkg"
+version = "0.1.0"
+description = "Kernel allelic series model for rare-variant heritability from exome summary statistics."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "genetics",
+    "heritability",
+    "rare variants",
+    "exome",
+    "summary statistics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "clarabel>=0.11.1",
+    "numpy",
+    "polars>=1.30",
+    "scipy",
+]
+
+[[project.authors]]
+name = "Kangcheng Hou"
+email = "kangchenghou@gmail.com"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+    "pre-commit",
+    "cvxpy>=1.7.5",
+    "pytest-xdist>=3.8.0",
+]
+
+[project.urls]
+Repository = "https://github.com/KangchengHou/kasm-pkg"
+Documentation = "https://github.com/KangchengHou/kasm-pkg/blob/main/DOCS.md"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "kasm"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+addopts = "-q --strict-markers -n auto"

kasm_pkg-0.1.0/pyproject.toml.orig

@@ -0,0 +1,52 @@
+[project]
+name = "kasm-pkg"
+version = "0.1.0"
+description = "Kernel allelic series model for rare-variant heritability from exome summary statistics."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kangcheng Hou", email = "kangchenghou@gmail.com" }]
+requires-python = ">=3.12"
+keywords = ["genetics", "heritability", "rare variants", "exome", "summary statistics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "clarabel>=0.11.1",
+    "numpy",
+    "polars>=1.30",
+    "scipy",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff",
+    "pre-commit",
+    "cvxpy>=1.7.5",
+    "pytest-xdist>=3.8.0",
+]
+
+[project.urls]
+Repository = "https://github.com/KangchengHou/kasm-pkg"
+Documentation = "https://github.com/KangchengHou/kasm-pkg/blob/main/DOCS.md"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "kasm"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+addopts = "-q --strict-markers -n auto"

kasm_pkg-0.1.0/src/kasm/__init__.py

@@ -0,0 +1,70 @@
+"""kasm — kernel allelic series model."""
+
+from kasm import covar
+from kasm._logging import configure_logging, logger
+from kasm.api import (
+    RandomFit,
+    combine_mixed_effects,
+    combine_random_hsq,
+    fit_fixed_effects,
+    fit_random_effects,
+)
+from kasm.covar import (
+    CovarResult,
+    compute_random_covar,
+)
+from kasm.dataset import (
+    Dataset,
+    parse_variant_ids,
+    sort_variant_df,
+)
+from kasm.enrichment import EnrichResult, pool_enrichment
+from kasm.fixed_effects import FixedFit
+from kasm.fitting import jackknife_se
+from kasm.kernels import KernelId, KernelLayout, KernelOptions
+from kasm.ldm import LDM, LDMLoader
+from kasm.model import Model
+from kasm.simulation import (
+    simulate_burden_effects,
+    simulate_sumstats,
+)
+from kasm.suffstats import (
+    ExtraEnrichCols,
+    ExtSuffStats,
+    JKSuffStats,
+    SuffStats,
+    compute_jk_suffstats,
+)
+
+__all__ = [
+    "LDM",
+    "CovarResult",
+    "Dataset",
+    "EnrichResult",
+    "ExtSuffStats",
+    "ExtraEnrichCols",
+    "FixedFit",
+    "JKSuffStats",
+    "KernelId",
+    "KernelLayout",
+    "KernelOptions",
+    "LDMLoader",
+    "Model",
+    "RandomFit",
+    "SuffStats",
+    "combine_mixed_effects",
+    "combine_random_hsq",
+    "covar",
+    "configure_logging",
+    "compute_jk_suffstats",
+    "compute_random_covar",
+    "fit_fixed_effects",
+    "fit_random_effects",
+    "jackknife_se",
+    "logger",
+    "parse_variant_ids",
+    "pool_enrichment",
+    "simulate_burden_effects",
+    "simulate_sumstats",
+    "sort_variant_df",
+]

kasm_pkg-0.1.0/src/kasm/_logging.py

@@ -0,0 +1,42 @@
+"""Logging configuration for kasm workflows."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("kasm")
+
+
+def configure_logging(
+    level: int | str = "INFO", *, filename: str | Path | None = None
+) -> None:
+    """Configure console logging, and optionally file logging, for ``kasm.*``.
+
+    Only handlers previously installed by this function are replaced. This
+    leaves application-owned handlers and the root logger untouched.
+    """
+    resolved_level = (
+        logging._nameToLevel.get(level.upper()) if isinstance(level, str) else level
+    )
+    if not isinstance(resolved_level, int):
+        raise ValueError(f"unknown logging level {level!r}")
+    formatter = logging.Formatter(
+        "%(asctime)s %(module)s %(levelname)s %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    for handler in tuple(logger.handlers):
+        if getattr(handler, "_kasm_managed", False):
+            logger.removeHandler(handler)
+            handler.close()
+    handlers: list[logging.Handler] = [logging.StreamHandler()]
+    if filename is not None:
+        path = Path(filename)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handlers.append(logging.FileHandler(path, mode="a"))
+    for handler in handlers:
+        handler.setFormatter(formatter)
+        handler._kasm_managed = True
+        logger.addHandler(handler)
+    logger.setLevel(resolved_level)
+    logger.propagate = False