aging-metaclock 0.1.0__tar.gz

aging_metaclock-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: aging_metaclock
+Version: 0.1.0
+Summary: Reproducible analysis and plotting workflows for MetaClock
+Requires-Python: <3.12,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: anndata==0.12.7
+Requires-Dist: joblib==1.5.2
+Requires-Dist: lightgbm==4.6.0
+Requires-Dist: lifelines==0.30.3
+Requires-Dist: matplotlib==3.10.8
+Requires-Dist: mrmr-selection==0.2.8
+Requires-Dist: numpy==2.3.5
+Requires-Dist: pandas==2.3.3
+Requires-Dist: pymupdf==1.26.6
+Requires-Dist: pyarrow==23.0.1
+Requires-Dist: pyaging==0.1.30
+Requires-Dist: rdata==1.0.0
+Requires-Dist: scikit-learn==1.8.0
+Requires-Dist: scipy==1.17.0
+Requires-Dist: statsmodels==0.14.6
+Requires-Dist: torch==2.9.1
+
+# MetaClock workflow
+
+![MetaClock workflow diagram](diagram.png)
+
+This repository contains workflows for chronological-age
+prediction, cross-domain generalization, biological-age and disease analysis,
+functional enrichment, and intervention analysis. GEO workflows download inputs
+into repository-local data directories. The workflow READMEs describe the required files and preparation
+steps.
+
+## Project overview
+
+MetaClock is an integrated framework that combines
+predictions from multiple established epigenetic clocks into meta
+models. This repository organizes the reproducible downstream workflows used
+to evaluate chronological-age prediction, quantify generalization across array
+platforms, tissues, and species, and study biological-age associations with
+disease and interventions.
+
+## Environment
+
+Install [uv](https://docs.astral.sh/uv/) and create the locked Python 3.11
+environment from the repository root:
+
+```bash
+uv sync --frozen
+```
+
+## MetaClock Python package
+
+The `aging_metaclock` distribution provides the importable `metaclock` package.
+Install it from PyPI using Python 3.11:
+
+```bash
+python -m pip install aging_metaclock
+```
+
+For local development, install from the repository root:
+
+```bash
+python -m pip install -e .
+```
+
+### Input contract
+
+`metaclock.fit()` accepts an in-memory `anndata.AnnData` object or an `.h5ad`
+file in pyaging's standard orientation:
+
+- rows are samples;
+- columns are DNAm or phenotype features;
+- feature names are stored in `adata.var_names`;
+- the numeric training response is stored in `adata.obs["age"]` by default.
+
+Clocks that use phenotype covariates, such as GrimAge, require those covariates
+in the input matrix and `adata.var_names` according to pyaging's input rules.
+
+### Fit and predict
+
+Pass any ordered list of pyaging component-model names. The fitted result is an
+sklearn-compatible pipeline whose `predict()` method first runs the same
+components in the same order and then applies the trained meta-regressor:
+
+```
+import metaclock
+
+component_model_list = [
+    "horvath2013",
+    "hannum",
+    "dnamphenoage",
+]
+
+model = metaclock.fit(
+    train_adata,
+    component_model_list,
+    "elastic_net",
+    target="age",
+)
+
+predicted_age = model.predict(test_adata)
+```
+
+The three positional arguments are the input data, component-model list, and
+model architecture. Set `pyaging_dir` when using a specific local pyaging
+weight cache. The component ordering used for fitting is retained for every
+later prediction.
+
+To run the component clocks without fitting a meta-model:
+
+```python
+component_outputs = metaclock.predict_components(
+    test_adata,
+    component_model_list,
+)
+```
+
+Supported architectures are `elastic_net`, `lasso`, `ridge`,
+`linear_regression`, `random_forest`, `svr`, `mlp`, and `lightgbm`. The `mlp`
+architecture uses `StandardScaler` followed by sklearn's `MLPRegressor`; its
+network parameters can be overridden through `model_params`. LightGBM is part
+of the standard locked environment and uses its sklearn-compatible
+`LGBMRegressor` interface.
+
+Fitted models can be saved with joblib and loaded for later prediction:
+
+```python
+import joblib
+
+joblib.dump(model, model_output_path)
+loaded_model = joblib.load(model_output_path)
+predicted_age = loaded_model.predict(test_adata)
+```
+

aging_metaclock-0.1.0/README.md

@@ -0,0 +1,112 @@
+# MetaClock workflow
+
+![MetaClock workflow diagram](diagram.png)
+
+This repository contains workflows for chronological-age
+prediction, cross-domain generalization, biological-age and disease analysis,
+functional enrichment, and intervention analysis. GEO workflows download inputs
+into repository-local data directories. The workflow READMEs describe the required files and preparation
+steps.
+
+## Project overview
+
+MetaClock is an integrated framework that combines
+predictions from multiple established epigenetic clocks into meta
+models. This repository organizes the reproducible downstream workflows used
+to evaluate chronological-age prediction, quantify generalization across array
+platforms, tissues, and species, and study biological-age associations with
+disease and interventions.
+
+## Environment
+
+Install [uv](https://docs.astral.sh/uv/) and create the locked Python 3.11
+environment from the repository root:
+
+```bash
+uv sync --frozen
+```
+
+## MetaClock Python package
+
+The `aging_metaclock` distribution provides the importable `metaclock` package.
+Install it from PyPI using Python 3.11:
+
+```bash
+python -m pip install aging_metaclock
+```
+
+For local development, install from the repository root:
+
+```bash
+python -m pip install -e .
+```
+
+### Input contract
+
+`metaclock.fit()` accepts an in-memory `anndata.AnnData` object or an `.h5ad`
+file in pyaging's standard orientation:
+
+- rows are samples;
+- columns are DNAm or phenotype features;
+- feature names are stored in `adata.var_names`;
+- the numeric training response is stored in `adata.obs["age"]` by default.
+
+Clocks that use phenotype covariates, such as GrimAge, require those covariates
+in the input matrix and `adata.var_names` according to pyaging's input rules.
+
+### Fit and predict
+
+Pass any ordered list of pyaging component-model names. The fitted result is an
+sklearn-compatible pipeline whose `predict()` method first runs the same
+components in the same order and then applies the trained meta-regressor:
+
+```
+import metaclock
+
+component_model_list = [
+    "horvath2013",
+    "hannum",
+    "dnamphenoage",
+]
+
+model = metaclock.fit(
+    train_adata,
+    component_model_list,
+    "elastic_net",
+    target="age",
+)
+
+predicted_age = model.predict(test_adata)
+```
+
+The three positional arguments are the input data, component-model list, and
+model architecture. Set `pyaging_dir` when using a specific local pyaging
+weight cache. The component ordering used for fitting is retained for every
+later prediction.
+
+To run the component clocks without fitting a meta-model:
+
+```python
+component_outputs = metaclock.predict_components(
+    test_adata,
+    component_model_list,
+)
+```
+
+Supported architectures are `elastic_net`, `lasso`, `ridge`,
+`linear_regression`, `random_forest`, `svr`, `mlp`, and `lightgbm`. The `mlp`
+architecture uses `StandardScaler` followed by sklearn's `MLPRegressor`; its
+network parameters can be overridden through `model_params`. LightGBM is part
+of the standard locked environment and uses its sklearn-compatible
+`LGBMRegressor` interface.
+
+Fitted models can be saved with joblib and loaded for later prediction:
+
+```python
+import joblib
+
+joblib.dump(model, model_output_path)
+loaded_model = joblib.load(model_output_path)
+predicted_age = loaded_model.predict(test_adata)
+```
+

aging_metaclock-0.1.0/aging_metaclock.egg-info/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: aging_metaclock
+Version: 0.1.0
+Summary: Reproducible analysis and plotting workflows for MetaClock
+Requires-Python: <3.12,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: anndata==0.12.7
+Requires-Dist: joblib==1.5.2
+Requires-Dist: lightgbm==4.6.0
+Requires-Dist: lifelines==0.30.3
+Requires-Dist: matplotlib==3.10.8
+Requires-Dist: mrmr-selection==0.2.8
+Requires-Dist: numpy==2.3.5
+Requires-Dist: pandas==2.3.3
+Requires-Dist: pymupdf==1.26.6
+Requires-Dist: pyarrow==23.0.1
+Requires-Dist: pyaging==0.1.30
+Requires-Dist: rdata==1.0.0
+Requires-Dist: scikit-learn==1.8.0
+Requires-Dist: scipy==1.17.0
+Requires-Dist: statsmodels==0.14.6
+Requires-Dist: torch==2.9.1
+
+# MetaClock workflow
+
+![MetaClock workflow diagram](diagram.png)
+
+This repository contains workflows for chronological-age
+prediction, cross-domain generalization, biological-age and disease analysis,
+functional enrichment, and intervention analysis. GEO workflows download inputs
+into repository-local data directories. The workflow READMEs describe the required files and preparation
+steps.
+
+## Project overview
+
+MetaClock is an integrated framework that combines
+predictions from multiple established epigenetic clocks into meta
+models. This repository organizes the reproducible downstream workflows used
+to evaluate chronological-age prediction, quantify generalization across array
+platforms, tissues, and species, and study biological-age associations with
+disease and interventions.
+
+## Environment
+
+Install [uv](https://docs.astral.sh/uv/) and create the locked Python 3.11
+environment from the repository root:
+
+```bash
+uv sync --frozen
+```
+
+## MetaClock Python package
+
+The `aging_metaclock` distribution provides the importable `metaclock` package.
+Install it from PyPI using Python 3.11:
+
+```bash
+python -m pip install aging_metaclock
+```
+
+For local development, install from the repository root:
+
+```bash
+python -m pip install -e .
+```
+
+### Input contract
+
+`metaclock.fit()` accepts an in-memory `anndata.AnnData` object or an `.h5ad`
+file in pyaging's standard orientation:
+
+- rows are samples;
+- columns are DNAm or phenotype features;
+- feature names are stored in `adata.var_names`;
+- the numeric training response is stored in `adata.obs["age"]` by default.
+
+Clocks that use phenotype covariates, such as GrimAge, require those covariates
+in the input matrix and `adata.var_names` according to pyaging's input rules.
+
+### Fit and predict
+
+Pass any ordered list of pyaging component-model names. The fitted result is an
+sklearn-compatible pipeline whose `predict()` method first runs the same
+components in the same order and then applies the trained meta-regressor:
+
+```
+import metaclock
+
+component_model_list = [
+    "horvath2013",
+    "hannum",
+    "dnamphenoage",
+]
+
+model = metaclock.fit(
+    train_adata,
+    component_model_list,
+    "elastic_net",
+    target="age",
+)
+
+predicted_age = model.predict(test_adata)
+```
+
+The three positional arguments are the input data, component-model list, and
+model architecture. Set `pyaging_dir` when using a specific local pyaging
+weight cache. The component ordering used for fitting is retained for every
+later prediction.
+
+To run the component clocks without fitting a meta-model:
+
+```python
+component_outputs = metaclock.predict_components(
+    test_adata,
+    component_model_list,
+)
+```
+
+Supported architectures are `elastic_net`, `lasso`, `ridge`,
+`linear_regression`, `random_forest`, `svr`, `mlp`, and `lightgbm`. The `mlp`
+architecture uses `StandardScaler` followed by sklearn's `MLPRegressor`; its
+network parameters can be overridden through `model_params`. LightGBM is part
+of the standard locked environment and uses its sklearn-compatible
+`LGBMRegressor` interface.
+
+Fitted models can be saved with joblib and loaded for later prediction:
+
+```python
+import joblib
+
+joblib.dump(model, model_output_path)
+loaded_model = joblib.load(model_output_path)
+predicted_age = loaded_model.predict(test_adata)
+```
+

aging_metaclock-0.1.0/aging_metaclock.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+aging_metaclock.egg-info/PKG-INFO
+aging_metaclock.egg-info/SOURCES.txt
+aging_metaclock.egg-info/dependency_links.txt
+aging_metaclock.egg-info/requires.txt
+aging_metaclock.egg-info/top_level.txt
+metaclock/__init__.py
+metaclock/_version.py
+metaclock/api.py
+metaclock/components.py
+metaclock/models.py
+metaclock/presets.py

aging_metaclock-0.1.0/aging_metaclock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aging_metaclock-0.1.0/aging_metaclock.egg-info/requires.txt

@@ -0,0 +1,16 @@
+anndata==0.12.7
+joblib==1.5.2
+lightgbm==4.6.0
+lifelines==0.30.3
+matplotlib==3.10.8
+mrmr-selection==0.2.8
+numpy==2.3.5
+pandas==2.3.3
+pymupdf==1.26.6
+pyarrow==23.0.1
+pyaging==0.1.30
+rdata==1.0.0
+scikit-learn==1.8.0
+scipy==1.17.0
+statsmodels==0.14.6
+torch==2.9.1

aging_metaclock-0.1.0/aging_metaclock.egg-info/top_level.txt

@@ -0,0 +1 @@
+metaclock

aging_metaclock-0.1.0/metaclock/__init__.py

@@ -0,0 +1,17 @@
+"""MetaClock: fit meta-regressors from pyaging component clocks."""
+
+from ._version import __version__
+from .api import fit
+from .components import PyAgingTransformer, predict_components
+from .models import available_architectures, make_estimator
+from .presets import CHRONOLOGICAL_16_COMPONENT_MODELS
+
+__all__ = [
+    "PyAgingTransformer",
+    "CHRONOLOGICAL_16_COMPONENT_MODELS",
+    "__version__",
+    "available_architectures",
+    "fit",
+    "make_estimator",
+    "predict_components",
+]

aging_metaclock-0.1.0/metaclock/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.1.0"

aging_metaclock-0.1.0/metaclock/api.py

@@ -0,0 +1,165 @@
+"""Public MetaClock fitting API."""
+
+from __future__ import annotations
+
+import platform
+from importlib.metadata import PackageNotFoundError, version
+from os import PathLike
+from typing import TYPE_CHECKING, Any, Mapping, Sequence
+
+import numpy as np
+import pandas as pd
+from sklearn.pipeline import Pipeline
+
+from ._version import __version__
+from .components import (
+    InputData,
+    PyAgingTransformer,
+    load_anndata,
+    normalize_component_models,
+)
+from .models import make_estimator, normalize_architecture
+
+if TYPE_CHECKING:
+    from anndata import AnnData
+
+
+def _package_version(distribution: str) -> str:
+    try:
+        return version(distribution)
+    except PackageNotFoundError:
+        return "not-installed"
+
+
+def _extract_target(adata: AnnData, target: str) -> np.ndarray:
+    if not isinstance(target, str) or not target.strip():
+        raise TypeError("target must be a non-empty adata.obs column name.")
+    if target not in adata.obs.columns:
+        raise KeyError(f"AnnData obs does not contain target column {target!r}.")
+    series = pd.to_numeric(adata.obs[target], errors="coerce")
+    values = series.to_numpy(dtype=np.float64, copy=True)
+    if not np.isfinite(values).all():
+        affected = adata.obs_names[~np.isfinite(values)].astype(str).tolist()[:5]
+        raise ValueError(
+            f"Target column {target!r} contains missing or non-finite values; "
+            f"first affected samples: {affected}"
+        )
+    return values
+
+
+def _safe_params(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, Mapping):
+        return {str(key): _safe_params(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_safe_params(item) for item in value]
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    return repr(value)
+
+
+def fit(
+    input_data: InputData,
+    component_models: Sequence[str] | str,
+    architecture: str,
+    *,
+    target: str = "age",
+    pyaging_dir: str | PathLike[str] | None = "pyaging_data",
+    batch_size: int = 1024,
+    clean: bool = True,
+    verbose: bool = False,
+    copy: bool = False,
+    random_state: int = 42,
+    n_jobs: int | None = 1,
+    model_params: Mapping[str, Any] | None = None,
+) -> Pipeline:
+    """Fit a MetaClock from a pyaging-standard AnnData input.
+
+    Parameters
+    ----------
+    input_data
+        An ``AnnData`` object or an ``.h5ad`` path. Rows are samples, columns
+        are pyaging features, and ``adata.obs[target]`` supplies the response.
+    component_models
+        One or more pyaging clock names. Their prediction order is preserved.
+    architecture
+        A name returned by ``metaclock.available_architectures()``.
+    target
+        Numeric ``adata.obs`` target column. Defaults to ``"age"``.
+    pyaging_dir
+        PyAging model-cache directory, or ``None`` to use PyAging's default.
+    batch_size, clean, verbose
+        Values forwarded to PyAging component-clock inference.
+    copy
+        If true, copy in-memory ``AnnData`` before PyAging inference. With the
+        default false, PyAging may update the supplied object in place.
+    random_state
+        Seed used by regressors and shuffled cross-validation where supported.
+    n_jobs
+        Worker count forwarded to regressors that support parallel execution.
+    model_params
+        Overrides passed directly to the final regression estimator.
+
+    Returns
+    -------
+    sklearn.pipeline.Pipeline
+        A fitted pipeline. Calling ``predict()`` with another pyaging-standard
+        ``AnnData`` object or ``.h5ad`` path reruns the same component clocks
+        before applying the fitted regressor.
+    """
+    adata = load_anndata(input_data)
+    components = normalize_component_models(component_models)
+    architecture_name = normalize_architecture(architecture)
+    if target.lower() in components:
+        raise ValueError("target cannot also be a component-model output column.")
+    y = _extract_target(adata, target)
+
+    transformer = PyAgingTransformer(
+        components,
+        pyaging_dir=pyaging_dir,
+        batch_size=batch_size,
+        clean=clean,
+        verbose=verbose,
+        copy=copy,
+    )
+    estimator = make_estimator(
+        architecture_name,
+        random_state=random_state,
+        n_jobs=n_jobs,
+        model_params=model_params,
+    )
+    model = Pipeline([("components", transformer), ("regressor", estimator)])
+    model.fit(adata, y)
+
+    model.metaclock_architecture_ = architecture_name
+    model.metaclock_component_models_ = components
+    model.metaclock_target_ = target
+    model.metaclock_provenance_ = {
+        "package_versions": {
+            "python": platform.python_version(),
+            "metaclock": __version__,
+            "pyaging": _package_version("pyaging"),
+            "anndata": _package_version("anndata"),
+            "numpy": _package_version("numpy"),
+            "pandas": _package_version("pandas"),
+            "scikit-learn": _package_version("scikit-learn"),
+            "lightgbm": _package_version("lightgbm")
+            if architecture_name == "lightgbm"
+            else None,
+        },
+        "fit_parameters": {
+            "target": target,
+            "component_models": list(components),
+            "architecture": architecture_name,
+            "pyaging_dir": None if pyaging_dir is None else str(pyaging_dir),
+            "batch_size": batch_size,
+            "clean": clean,
+            "random_state": random_state,
+            "n_jobs": n_jobs,
+            "model_params": _safe_params(dict(model_params or {})),
+        },
+        "training_samples": int(adata.n_obs),
+        "component_missing_feature_percent": dict(transformer.missing_feature_percent_),
+    }
+    return model

aging_metaclock-0.1.0/metaclock/components.py

@@ -0,0 +1,210 @@
+"""pyaging adapter for generating MetaClock component-model features."""
+
+from __future__ import annotations
+
+from os import PathLike
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Sequence, TypeAlias, Union
+
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils.validation import check_is_fitted
+
+
+if TYPE_CHECKING:
+    from anndata import AnnData
+
+InputData: TypeAlias = Union["AnnData", str, PathLike[str]]
+
+
+def normalize_component_models(
+    component_models: Sequence[str] | str,
+) -> tuple[str, ...]:
+    """Return non-empty, unique, lower-case pyaging clock names."""
+    if isinstance(component_models, str):
+        raw_models = [component_models]
+    else:
+        try:
+            raw_models = list(component_models)
+        except TypeError as exc:
+            raise TypeError(
+                "component_models must be a clock name or a sequence of names."
+            ) from exc
+
+    normalized: list[str] = []
+    for model in raw_models:
+        if not isinstance(model, str):
+            raise TypeError("Every component model name must be a string.")
+        name = model.strip().lower()
+        if not name:
+            raise ValueError("Component model names cannot be empty.")
+        normalized.append(name)
+
+    if not normalized:
+        raise ValueError("At least one component model is required.")
+    duplicates = sorted({name for name in normalized if normalized.count(name) > 1})
+    if duplicates:
+        raise ValueError(f"component_models contains duplicates: {duplicates}")
+    return tuple(normalized)
+
+
+def load_anndata(input_data: InputData) -> AnnData:
+    """Load a pyaging-standard AnnData object from memory or an .h5ad file."""
+    try:
+        import anndata as ad
+    except ImportError as exc:  # pragma: no cover - declared core dependency
+        raise ImportError("anndata is required to load MetaClock input data.") from exc
+
+    if isinstance(input_data, ad.AnnData):
+        adata = input_data
+    elif isinstance(input_data, (str, PathLike)):
+        path = Path(input_data).expanduser()
+        if not path.is_file():
+            raise FileNotFoundError(f"AnnData input file does not exist: {path}")
+        try:
+            adata = ad.read_h5ad(path)
+        except Exception as exc:
+            raise ValueError(f"Could not read AnnData .h5ad input: {path}") from exc
+    else:
+        raise TypeError(
+            "input_data must be an anndata.AnnData object or a path to an .h5ad file."
+        )
+
+    if adata.n_obs == 0:
+        raise ValueError("AnnData input has no samples.")
+    if adata.n_vars == 0:
+        raise ValueError("AnnData input has no features.")
+    if not adata.obs_names.is_unique:
+        raise ValueError("AnnData obs_names must be unique.")
+    if not adata.var_names.is_unique:
+        raise ValueError("AnnData var_names must be unique.")
+    return adata.copy() if adata.is_view else adata
+
+
+class PyAgingTransformer(TransformerMixin, BaseEstimator):
+    """Transform a pyaging-standard AnnData object into component predictions.
+
+    The transformer deliberately delegates clock loading, feature alignment,
+    preprocessing, inference, and postprocessing to pyaging. Its output column
+    order always matches ``component_models``.
+    """
+
+    def __init__(
+        self,
+        component_models: Sequence[str] | str,
+        *,
+        pyaging_dir: str | PathLike[str] | None = "pyaging_data",
+        batch_size: int = 1024,
+        clean: bool = True,
+        verbose: bool = False,
+        copy: bool = False,
+    ) -> None:
+        self.component_models = component_models
+        self.pyaging_dir = pyaging_dir
+        self.batch_size = batch_size
+        self.clean = clean
+        self.verbose = verbose
+        self.copy = copy
+
+    def fit(self, X: InputData, y: Any = None) -> PyAgingTransformer:
+        """Validate clock names and record their output order without fitting clocks."""
+        del X, y
+        self.component_models_ = normalize_component_models(self.component_models)
+        if not isinstance(self.batch_size, int) or self.batch_size < 1:
+            raise ValueError("batch_size must be a positive integer.")
+        self.n_features_out_ = len(self.component_models_)
+        return self
+
+    def transform(self, X: InputData) -> pd.DataFrame:
+        """Run PyAging in place (on a copy if requested) and return finite predictions."""
+        check_is_fitted(self, "component_models_")
+        adata = load_anndata(X)
+        if self.copy:
+            adata = adata.copy()
+
+        kwargs: dict[str, Any] = {
+            "clock_names": list(self.component_models_),
+            "batch_size": self.batch_size,
+            "clean": self.clean,
+            "verbose": self.verbose,
+        }
+        if self.pyaging_dir is not None:
+            kwargs["dir"] = str(self.pyaging_dir)
+
+        import pyaging as pya
+
+        # PyAging 0.1.30 populates adata.obs in place and returns None.
+        pya.pred.predict_age(adata, **kwargs)
+
+        column_lookup: dict[str, Any] = {}
+        for column in adata.obs.columns:
+            lowered = str(column).lower()
+            if lowered in column_lookup and column_lookup[lowered] != column:
+                raise ValueError(
+                    f"AnnData obs has ambiguous case-insensitive column {lowered!r}."
+                )
+            column_lookup[lowered] = column
+        missing = [name for name in self.component_models_ if name not in column_lookup]
+        if missing:
+            raise RuntimeError(
+                f"pyaging did not create component output columns: {missing}"
+            )
+
+        ordered_columns = [column_lookup[name] for name in self.component_models_]
+        frame = adata.obs.loc[:, ordered_columns].apply(pd.to_numeric, errors="coerce")
+        values = frame.to_numpy(dtype=np.float64, copy=True)
+        if not np.isfinite(values).all():
+            bad_rows, bad_columns = np.where(~np.isfinite(values))
+            examples = [
+                (str(adata.obs_names[row]), self.component_models_[column])
+                for row, column in zip(bad_rows[:5], bad_columns[:5])
+            ]
+            raise ValueError(
+                "pyaging component outputs contain missing or non-finite values; "
+                f"first affected (sample, component) pairs: {examples}"
+            )
+
+        self.missing_feature_percent_ = {
+            name: float(adata.uns.get(f"{name}_percent_na", np.nan))
+            for name in self.component_models_
+        }
+        return pd.DataFrame(
+            values,
+            index=adata.obs_names.copy(),
+            columns=self.get_feature_names_out(),
+        )
+
+    def get_feature_names_out(self, input_features: Any = None) -> np.ndarray:
+        """Return fitted component names in prediction-column order."""
+        del input_features
+        check_is_fitted(self, "component_models_")
+        return np.asarray(self.component_models_, dtype=object)
+
+
+def predict_components(
+    input_data: InputData,
+    component_models: Sequence[str] | str,
+    *,
+    pyaging_dir: str | PathLike[str] | None = "pyaging_data",
+    batch_size: int = 1024,
+    clean: bool = True,
+    verbose: bool = False,
+    copy: bool = False,
+) -> pd.DataFrame:
+    """Return ordered pyaging component predictions as a DataFrame."""
+    adata = load_anndata(input_data)
+    transformer = PyAgingTransformer(
+        component_models,
+        pyaging_dir=pyaging_dir,
+        batch_size=batch_size,
+        clean=clean,
+        verbose=verbose,
+        copy=copy,
+    )
+    values = transformer.fit_transform(adata)
+    return pd.DataFrame(
+        values,
+        index=adata.obs_names.copy(),
+        columns=transformer.get_feature_names_out(),
+    )

aging_metaclock-0.1.0/metaclock/models.py

@@ -0,0 +1,134 @@
+"""Maintained sklearn and LightGBM MetaClock estimator factory."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, Mapping
+
+import numpy as np
+from sklearn.base import BaseEstimator
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.linear_model import ElasticNetCV, LassoCV, LinearRegression, RidgeCV
+from sklearn.model_selection import KFold
+from sklearn.neural_network import MLPRegressor
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.svm import SVR
+
+
+_ARCHITECTURES = (
+    "elastic_net",
+    "lasso",
+    "ridge",
+    "linear_regression",
+    "random_forest",
+    "svr",
+    "mlp",
+    "lightgbm",
+)
+_ALIASES = {
+    "elasticnet": "elastic_net",
+    "enet": "elastic_net",
+    "linear": "linear_regression",
+    "ols": "linear_regression",
+    "rf": "random_forest",
+    "randomforest": "random_forest",
+    "svm": "svr",
+    "mlp_regressor": "mlp",
+    "neural_network": "mlp",
+    "lgbm": "lightgbm",
+}
+
+
+def available_architectures() -> tuple[str, ...]:
+    """Return supported canonical architecture names."""
+    return _ARCHITECTURES
+
+
+def normalize_architecture(architecture: str) -> str:
+    """Normalize architecture spelling and aliases."""
+    if not isinstance(architecture, str):
+        raise TypeError("architecture must be a string.")
+    name = architecture.strip().lower().replace("-", "_").replace(" ", "_")
+    name = _ALIASES.get(name, name)
+    if name not in _ARCHITECTURES:
+        choices = ", ".join(_ARCHITECTURES)
+        raise ValueError(
+            f"Unknown architecture {architecture!r}. Choose one of: {choices}."
+        )
+    return name
+
+
+def _scaled(model: BaseEstimator) -> Pipeline:
+    return Pipeline([("scaler", StandardScaler()), ("model", model)])
+
+
+def make_estimator(
+    architecture: str,
+    *,
+    random_state: int = 42,
+    n_jobs: int | None = 1,
+    model_params: Mapping[str, Any] | None = None,
+) -> BaseEstimator:
+    """Build an unfitted regressor using maintained package implementations.
+
+    ``model_params`` are passed directly to the final estimator. Scaled linear
+    models are returned as sklearn Pipelines with ``scaler`` and ``model``
+    steps. LightGBM is imported only when requested.
+    """
+    name = normalize_architecture(architecture)
+    params = dict(model_params or {})
+    alphas = np.logspace(-5, 0, 30)
+    cv = KFold(n_splits=5, shuffle=True, random_state=random_state)
+
+    if name == "elastic_net":
+        defaults: dict[str, Any] = {
+            "alphas": alphas,
+            "cv": cv,
+            "max_iter": 20_000,
+            "n_jobs": n_jobs,
+        }
+        defaults.update(params)
+        return _scaled(ElasticNetCV(**defaults))
+    if name == "lasso":
+        defaults = {
+            "alphas": alphas,
+            "cv": cv,
+            "max_iter": 20_000,
+            "n_jobs": n_jobs,
+            "random_state": random_state,
+        }
+        defaults.update(params)
+        return _scaled(LassoCV(**defaults))
+    if name == "ridge":
+        defaults = {"alphas": alphas, "cv": cv}
+        defaults.update(params)
+        return _scaled(RidgeCV(**defaults))
+    if name == "linear_regression":
+        defaults = {"n_jobs": n_jobs}
+        defaults.update(params)
+        return _scaled(LinearRegression(**defaults))
+    if name == "random_forest":
+        defaults = {"random_state": random_state, "n_jobs": n_jobs}
+        defaults.update(params)
+        return RandomForestRegressor(**defaults)
+    if name == "svr":
+        defaults = {"kernel": "linear"}
+        defaults.update(params)
+        return _scaled(SVR(**defaults))
+    if name == "mlp":
+        defaults = {"max_iter": 2_000, "random_state": random_state}
+        defaults.update(params)
+        return _scaled(MLPRegressor(**defaults))
+
+    try:
+        module = import_module("lightgbm")
+        regressor = module.LGBMRegressor
+    except (ImportError, AttributeError) as exc:
+        raise ImportError(
+            "architecture='lightgbm' requires LightGBM, which is a core "
+            "metaclock-bio dependency. Reinstall the package dependencies."
+        ) from exc
+    defaults = {"random_state": random_state, "n_jobs": n_jobs, "verbosity": -1}
+    defaults.update(params)
+    return regressor(**defaults)

aging_metaclock-0.1.0/metaclock/presets.py

@@ -0,0 +1,26 @@
+"""Published MetaClock component-model presets."""
+
+from __future__ import annotations
+
+
+CHRONOLOGICAL_16_COMPONENT_MODELS: tuple[str, ...] = (
+    "horvath2013",
+    "hannum",
+    "dnamphenoage",
+    "altumage",
+    "han",
+    "encen40",
+    "hrsinchphenoage",
+    "lin",
+    "skinandblood",
+    "yingcausage",
+    "zhangblup",
+    "zhangen",
+    "pchorvath2013",
+    "pchannum",
+    "pcphenoage",
+    "pcskinandblood",
+)
+
+
+__all__ = ["CHRONOLOGICAL_16_COMPONENT_MODELS"]

aging_metaclock-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aging_metaclock"
+version = "0.1.0"
+description = "Reproducible analysis and plotting workflows for MetaClock"
+readme = "README.md"
+requires-python = ">=3.11,<3.12"
+dependencies = [
+    "anndata==0.12.7",
+    "joblib==1.5.2",
+    "lightgbm==4.6.0",
+    "lifelines==0.30.3",
+    "matplotlib==3.10.8",
+    "mrmr-selection==0.2.8",
+    "numpy==2.3.5",
+    "pandas==2.3.3",
+    "pymupdf==1.26.6",
+    "pyarrow==23.0.1",
+    "pyaging==0.1.30",
+    "rdata==1.0.0",
+    "scikit-learn==1.8.0",
+    "scipy==1.17.0",
+    "statsmodels==0.14.6",
+    "torch==2.9.1",
+]
+
+[tool.uv]
+package = true
+
+[tool.setuptools]
+packages = ["metaclock"]

aging_metaclock-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+