pyaging 0.5.0__tar.gz → 0.5.2__tar.gz

{pyaging-0.5.0 → pyaging-0.5.2}/.gitignore

@@ -36,6 +36,8 @@ example_data/
 # Generated clock weights and aggregate metadata (published to Hugging Face)
 clocks/weights/
 clocks/metadata/all_clock_metadata.pt
+clocks/blood_chemistry_example.pkl
+clocks/blood_chemistry_example.csv
 
 # Source datasets downloaded during clock-notebook execution; only the
 # notebooks themselves are tracked
@@ -60,3 +62,12 @@ docs/source/clock_notebooks/
 # Local scratch
 tmp/
 /data/
+
+# Uncompressed tAge fixtures: regenerating writes ~50 MB of .csv into a tracked
+# directory. Only the gzipped copies are committed.
+tests/data/tage/*.csv
+!tests/data/tage/input_metadata.csv
+
+# Published tAge model pickles: regenerating the fixtures re-downloads them from
+# Zenodo into the same directory. They are inputs, never committed artifacts.
+tests/data/tage/*.pkl

{pyaging-0.5.0 → pyaging-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyaging
-Version: 0.5.0
+Version: 0.5.2
 Summary: A Python-based compendium of GPU-optimized aging clocks.
 Project-URL: homepage, https://github.com/lucascamillomd/pyaging
 Project-URL: repository, https://github.com/lucascamillomd/pyaging

{pyaging-0.5.0 → pyaging-0.5.2}/pyproject.toml

@@ -100,7 +100,7 @@ only-include = ["src/pyaging", "README.md", "LICENSE", "pyproject.toml"]
 
 [tool.ruff]
 line-length = 120
-extend-exclude = ["*.ipynb", "dev"]
+extend-exclude = ["*.ipynb", "dev", "docs/superpowers"]
 
 [tool.ruff.lint]
 select = [

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/__init__.py

@@ -4,4 +4,4 @@ from . import data, logger, models, utils
 from . import predict as pred
 from . import preprocess as pp
 
-__version__ = "0.5.0"
+__version__ = "0.5.2"

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/data/feature_ranges.json

@@ -3,6 +3,7 @@
   "modality_defaults": {
     "DNA methylation": {"unit": "beta value", "low": 0.0, "high": 1.0},
     "transcriptomics": {"unit": null, "low": 0.0, "high": null},
+    "transcriptomics (relative)": {"unit": null, "low": null, "high": null},
     "histone modification": {"unit": null, "low": 0.0, "high": null},
     "chromatin accessibility": {"unit": null, "low": 0.0, "high": null}
   },

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/models/__init__.py

@@ -34,10 +34,8 @@ from ._models import (
     DepressionBarbu,
     DNAmFILi,
     DNAmFitAge,
-    DNAmFitAgeGaitF,
-    DNAmFitAgeGaitM,
-    DNAmFitAgeGripF,
-    DNAmFitAgeGripM,
+    DNAmFitAgeGait,
+    DNAmFitAgeGrip,
     DNAmFitAgeVO2Max,
     DNAmIC,
     DNAmPhenoAge,
@@ -154,6 +152,8 @@ from ._models import (
     SystemsAgeLung,
     SystemsAgeMetabolic,
     SystemsAgeMusculoSkeletal,
+    TAge,
+    TAgeMortality,
     Thompson,
     TwelveCellDeconvoluteBloodEPIC,
     VidalBralo,
@@ -199,10 +199,8 @@ __all__ = [
     "CpGPTPCGrimAge3",
     "DNAmFILi",
     "DNAmFitAge",
-    "DNAmFitAgeGaitF",
-    "DNAmFitAgeGaitM",
-    "DNAmFitAgeGripF",
-    "DNAmFitAgeGripM",
+    "DNAmFitAgeGait",
+    "DNAmFitAgeGrip",
     "DNAmFitAgeVO2Max",
     "DNAmIC",
     "DNAmPhenoAge",
@@ -325,6 +323,8 @@ __all__ = [
     "SystemsAgeLung",
     "SystemsAgeMetabolic",
     "SystemsAgeMusculoSkeletal",
+    "TAge",
+    "TAgeMortality",
     "Thompson",
     "TwelveCellDeconvoluteBloodEPIC",
     "VidalBralo",

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/models/_base_models.py

@@ -24,6 +24,15 @@ class pyagingModel(nn.Module, ABC):
 
         self.reference_values = None
 
+        # Name of an ``adata.uns`` key that must be truthy before this clock may
+        # run, for a clock whose input contract nothing can satisfy for it.
+        self.required_uns_flag = None
+
+        # Name of a cohort transform ``predict_age`` runs before aligning this
+        # clock's features; cohort-relative clocks set it so their whole-cohort
+        # preprocessing happens automatically, and it supersedes the flag above.
+        self.cohort_transform = None
+
         self.preprocess_name = None
         self.preprocess_dependencies = None
 
@@ -32,6 +41,10 @@ class pyagingModel(nn.Module, ABC):
 
         self.features = None
         self.feature_units = None
+        # Optional internal range profile when the model consumes values that
+        # differ from the public assay modality (for example, cohort-centered
+        # transcriptomic values derived from raw RNA-seq counts).
+        self.feature_range_data_type = None
         self.base_model_features = self.features
 
         self.base_model = None

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/models/_models.py

@@ -7,8 +7,7 @@ import torch.nn as nn
 # It holds because ``_pred_utils`` only takes names ``models/__init__`` has already bound
 # from ``_base_models`` by the time this module runs; importing a name defined here would
 # break it.
-from ..predict._inverse_transforms import mortality_to_phenoage_saopaulo
-from ..predict._transforms import PHENOAGE_CRP_FLOOR_MG_DL, crp_index, log1p_crp
+from ..predict._transforms import PHENOAGE_CRP_FLOOR_MG_DL, crp_index, log1p_crp, mortality_to_phenoage_saopaulo
 from ._base_models import pyagingModel
 
 # LinAge2's ``foldOutliers`` cap, in MAD-scaled z units, applied to every feature.
@@ -2117,66 +2116,50 @@ class DNAmFitAge(pyagingModel):
     def __init__(self):
         super().__init__()
 
-        self.GaitF = None
-        self.GripF = None
-        self.GaitM = None
-        self.GripM = None
+        self.Gait = None
+        self.Grip = None
         self.VO2Max = None
+        self.GrimAge = None
 
-        self.features_GaitF = None
-        self.features_GripF = None
-        self.features_GaitM = None
-        self.features_GripM = None
+        self.features_Gait = None
+        self.features_Grip = None
         self.features_VO2Max = None
+        self.features_GrimAge = None
+        self.female_index = None
+        self.age_index = None
 
-    def forward(self, x):
-        Female = x[:, -3]  # .unsqueeze(1)
-        GrimAge = x[:, -1].unsqueeze(1)
-
-        is_female = Female == 1
-        is_male = Female == 0
-
-        x_f = x[is_female]
-        x_m = x[is_male]
-
-        GaitF = self.GaitF(x_f[:, self.features_GaitF])
-        GripF = self.GripF(x_f[:, self.features_GripF])
-        VO2MaxF = self.VO2Max(x_f[:, self.features_VO2Max])
-        GrimAgeF = GrimAge[is_female, :]
+    def _component_input(self, x, indices, component):
+        values = x[:, indices]
+        return _fill_dnamfitage_references(values, component.reference_values)
 
-        GaitM = self.GaitM(x_m[:, self.features_GaitM])
-        GripM = self.GripM(x_m[:, self.features_GripM])
-        VO2MaxM = self.VO2Max(x_m[:, self.features_VO2Max])
-        GrimAgeM = GrimAge[is_male, :]
+    def forward(self, x):
+        female = x[:, self.female_index].unsqueeze(1)
+        gait = self.Gait(self._component_input(x, self.features_Gait, self.Gait))
+        grip = self.Grip(self._component_input(x, self.features_Grip, self.Grip))
+        vo2max = self.VO2Max(self._component_input(x, self.features_VO2Max, self.VO2Max))
+        grimage = self.GrimAge(self._component_input(x, self.features_GrimAge, self.GrimAge))
 
-        x_f = torch.concat(
+        female_components = torch.concat(
             [
-                (VO2MaxF - 46.825091) / (-0.13620215),
-                (GripF - 39.857718) / (-0.22074456),
-                (GaitF - 2.508547) / (-0.01245682),
-                (GrimAgeF - 7.978487) / (0.80928530),
+                (vo2max - 46.825091) / -0.13620215,
+                (grip - 39.857718) / -0.22074456,
+                (gait - 2.508547) / -0.01245682,
+                (grimage - 7.978487) / 0.80928530,
             ],
             dim=1,
         )
-
-        x_m = torch.concat(
+        male_components = torch.concat(
             [
-                (VO2MaxM - 49.836389) / (-0.141862925),
-                (GripM - 57.514016) / (-0.253179827),
-                (GaitM - 2.349080) / (-0.009380061),
-                (GrimAgeM - 9.549733) / (0.835120557),
+                (vo2max - 49.836389) / -0.141862925,
+                (grip - 57.514016) / -0.253179827,
+                (gait - 2.349080) / -0.009380061,
+                (grimage - 9.549733) / 0.835120557,
             ],
             dim=1,
         )
-
-        y_f = self.base_model_f(x_f)
-        y_m = self.base_model_m(x_m)
-
-        y = torch.zeros((x.size(0), 1), dtype=x.dtype, device=x.device)
-        y[is_female] = y_f
-        y[is_male] = y_m
-
-        return y
+        female_prediction = self.base_model_f(female_components)
+        male_prediction = self.base_model_m(male_components)
+        return male_prediction + female * (female_prediction - male_prediction)
 
     def preprocess(self, x):
         if self.reference_values is None:
@@ -2191,6 +2174,45 @@ class DNAmFitAge(pyagingModel):
         return x
 
 
+def _fill_dnamfitage_references(x, reference_values):
+    reference = torch.as_tensor(reference_values, device=x.device, dtype=x.dtype)
+    return torch.where(torch.isnan(x), reference, x)
+
+
+class _DNAmFitAgeSexGated(pyagingModel):
+    def __init__(self):
+        super().__init__()
+        self.female_model = None
+        self.male_model = None
+        self.female_feature_indices = None
+        self.male_feature_indices = None
+        self.female_reference_values = None
+        self.male_reference_values = None
+        self.female_index = None
+
+    def forward(self, x):
+        female = x[:, self.female_index].unsqueeze(1)
+        female_x = _fill_dnamfitage_references(x[:, self.female_feature_indices], self.female_reference_values)
+        male_x = _fill_dnamfitage_references(x[:, self.male_feature_indices], self.male_reference_values)
+        female_prediction = self.female_model(female_x)
+        male_prediction = self.male_model(male_x)
+        return male_prediction + female * (female_prediction - male_prediction)
+
+    def preprocess(self, x):
+        return x
+
+    def postprocess(self, x):
+        return x
+
+
+class DNAmFitAgeGait(_DNAmFitAgeSexGated):
+    pass
+
+
+class DNAmFitAgeGrip(_DNAmFitAgeSexGated):
+    pass
+
+
 class StocH(pyagingModel):
     def __init__(self):
         super().__init__()
@@ -2681,74 +2703,6 @@ class GrimAge2LogCRP(pyagingModel):
         return x
 
 
-class DNAmFitAgeGaitF(pyagingModel):
-    def __init__(self):
-        super().__init__()
-
-    def preprocess(self, x):
-        if self.reference_values is None:
-            return x
-        if isinstance(self.reference_values, torch.Tensor):
-            reference = self.reference_values.to(device=x.device, dtype=x.dtype)
-        else:
-            reference = torch.tensor(self.reference_values, device=x.device, dtype=x.dtype)
-        return torch.where(torch.isnan(x), reference, x)
-
-    def postprocess(self, x):
-        return x
-
-
-class DNAmFitAgeGaitM(pyagingModel):
-    def __init__(self):
-        super().__init__()
-
-    def preprocess(self, x):
-        if self.reference_values is None:
-            return x
-        if isinstance(self.reference_values, torch.Tensor):
-            reference = self.reference_values.to(device=x.device, dtype=x.dtype)
-        else:
-            reference = torch.tensor(self.reference_values, device=x.device, dtype=x.dtype)
-        return torch.where(torch.isnan(x), reference, x)
-
-    def postprocess(self, x):
-        return x
-
-
-class DNAmFitAgeGripF(pyagingModel):
-    def __init__(self):
-        super().__init__()
-
-    def preprocess(self, x):
-        if self.reference_values is None:
-            return x
-        if isinstance(self.reference_values, torch.Tensor):
-            reference = self.reference_values.to(device=x.device, dtype=x.dtype)
-        else:
-            reference = torch.tensor(self.reference_values, device=x.device, dtype=x.dtype)
-        return torch.where(torch.isnan(x), reference, x)
-
-    def postprocess(self, x):
-        return x
-
-
-class DNAmFitAgeGripM(pyagingModel):
-    def __init__(self):
-        super().__init__()
-
-    def preprocess(self, x):
-        if self.reference_values is None:
-            return x
-        if isinstance(self.reference_values, torch.Tensor):
-            reference = self.reference_values.to(device=x.device, dtype=x.dtype)
-        else:
-            reference = torch.tensor(self.reference_values, device=x.device, dtype=x.dtype)
-        return torch.where(torch.isnan(x), reference, x)
-
-    def postprocess(self, x):
-        return x
-
-
 class DNAmFitAgeVO2Max(pyagingModel):
     def __init__(self):
         super().__init__()
@@ -3271,3 +3225,36 @@ class EpiCMITHypo(epiTOC1):
 
 class EpiTOC3(epiTOC2):
     pass
+
+
+class TAge(pyagingModel):
+    def __init__(self):
+        super().__init__()
+        # Cohort-relative clock: ``predict_age`` runs the tAge cohort
+        # preprocessing on the raw counts before aligning these features.
+        self.cohort_transform = "tage"
+        self.feature_range_data_type = "transcriptomics (relative)"
+
+    def preprocess(self, x):
+        """Substitute the fitted imputer statistics for genes absent from the sample.
+
+        ``reference_values`` holds the published pipeline's ``SimpleImputer`` fill
+        values, so a gene the aligned list carries but the sample does not gets the
+        exact value the model was fitted to expect. For a cohort-centered clock that
+        is the least-biased choice available: the gene contributes its training median
+        rather than pulling the score toward zero or toward this cohort's center.
+        """
+        if self.reference_values is None:
+            return x
+        if isinstance(self.reference_values, torch.Tensor):
+            reference = self.reference_values.to(device=x.device, dtype=x.dtype)
+        else:
+            reference = torch.tensor(self.reference_values, device=x.device, dtype=x.dtype)
+        return torch.where(torch.isnan(x), reference, x)
+
+    def postprocess(self, x):
+        return x
+
+
+class TAgeMortality(TAge):
+    """Mortality head of the same pipeline family, with the same cohort-relative input contract."""

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/predict/__init__.py

@@ -1,15 +1,5 @@
 # pyaging/predict/__init__.py
 
-from ._inverse_transforms import (
-    anti_log,
-    anti_log_linear,
-    anti_log_log,
-    anti_logp2,
-    mortality_to_phenoage,
-    mortality_to_phenoage_saopaulo,
-    petkovichblood,
-    stubbsmultitissue,
-)
 from ._pred import predict_age
 from ._pred_utils import (
     add_pred_ages_and_clock_metadata_adata,
@@ -22,6 +12,7 @@ from ._pred_utils import (
 )
 from ._transforms import (
     binarize,
+    mortality_to_phenoage_saopaulo,
     quantile_normalize_with_gold_standard,
     scale,
     scale_row,
@@ -31,18 +22,12 @@ from ._transforms import (
 
 __all__ = [
     "add_pred_ages_and_clock_metadata_adata",
-    "anti_log",
-    "anti_log_linear",
-    "anti_log_log",
-    "anti_logp2",
     "binarize",
     "check_feature_ranges",
     "check_features_in_adata",
     "cleanup_clock_memory",
     "load_clock",
-    "mortality_to_phenoage",
     "mortality_to_phenoage_saopaulo",
-    "petkovichblood",
     "predict_age",
     "predict_ages_with_model",
     "quantile_normalize_with_gold_standard",
@@ -50,6 +35,5 @@ __all__ = [
     "scale_row",
     "scale_with_gold_standard",
     "set_torch_device",
-    "stubbsmultitissue",
     "tpm_norm_log1p",
 ]

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/predict/_pred.py

@@ -6,6 +6,8 @@ import torch
 from ..logger._live import ClockRunDisplay, DisplayLogger, display_enabled, quiet_hf_bars
 from ._pred_utils import (
     add_pred_ages_and_clock_metadata_adata,
+    apply_cohort_transform,
+    build_cohort_feature_matrix,
     check_feature_ranges,
     check_features_in_adata,
     load_clock,
@@ -70,6 +72,21 @@ def predict_age(
     It is important that the input AnnData object's .X attribute contains data suitable for age
     prediction.
 
+    A few clocks are cohort-relative: they read a sample only in the context of the samples
+    predicted alongside it, so their preprocessing is computed here, over the whole input, before
+    any batching. The tAge clocks (`tage`, `tagemortality`) work this way. Pass them raw RNA-seq
+    counts and at least two samples; .X itself is never modified, and what the preprocessing did is
+    recorded in .uns["tage_preparation"]. Two optional columns steer it:
+
+    - Species: a column named `mouse`, `rat`, `macaque`, or `human` among .var_names, set to 1 for
+      every sample, the same idiom the mammalian clocks use for covariates such as `female`. Only
+      one may be set, and it is dropped before the gene pipeline rather than read as a gene. With
+      no such column — or with the columns present but zero everywhere — the cohort is taken to be
+      mouse and a warning says so, on the display and as a UserWarning.
+    - Reference group: .obs["tage_reference_group"], boolean or numeric 0/1, whose truthy rows are
+      the samples to centre against. Without it the cohort centres on every sample. Predictions are
+      differences against that reference, not absolute values.
+
     The function automatically handles the transfer of data and models to the appropriate compute
     device (CPU or GPU) based on system configuration.
 
@@ -90,6 +107,10 @@ def predict_age(
 
     enabled = display_enabled(verbose)
     display = ClockRunDisplay(clock_names, str(device), enabled=enabled)
+    # Whole-cohort preprocessing, keyed by transform name and computed at most
+    # once per call: tage and tagemortality read the same transformed frame, and
+    # recomputing it per clock would be both slow and pointless.
+    cohort_frames = {}
     with quiet_hf_bars(verbose), display:
         for clock_name in clock_names:
             display.start_clock(clock_name, "loading weights")
@@ -99,13 +120,34 @@ def predict_age(
             # Load and prepare the clock
             model = load_clock(clock_name, device, dir, pipeline_logger)
 
+            # Clocks saved before either attribute existed lack both.
+            transform_name = getattr(model, "cohort_transform", None)
+            required_flag = getattr(model, "required_uns_flag", None)
+            # A clock whose input contract nothing can satisfy for it refuses to
+            # run unmarked input. A declared transform supersedes the flag: it
+            # produces exactly what the flag was there to demand, and weights
+            # built before the transform existed still carry the flag.
+            if transform_name is None and required_flag is not None and not adata.uns.get(required_flag, False):
+                raise ValueError(
+                    f"Clock '{clock_name}' needs preprocessed input (adata.uns['{required_flag}'] is missing)."
+                )
+
             # Disclaimer for commercial clocks
             if model.metadata.get("research_only", False):
                 display.warn(clock_name, "research use only")
 
             # Check and update adata for missing features
-            display.stage(clock_name, "matching features")
-            check_features_in_adata(adata, model, pipeline_logger)
+            if transform_name is not None:
+                # Cohort-relative clock: its features live in the space the
+                # transform produces, not in adata.X.
+                if transform_name not in cohort_frames:
+                    display.stage(clock_name, "preprocessing the cohort")
+                    cohort_frames[transform_name] = apply_cohort_transform(adata, transform_name, dir, pipeline_logger)
+                display.stage(clock_name, "matching features")
+                build_cohort_feature_matrix(adata, model, cohort_frames[transform_name], pipeline_logger)
+            else:
+                display.stage(clock_name, "matching features")
+                check_features_in_adata(adata, model, pipeline_logger)
 
             # Warn if the input values look implausible for these features
             display.stage(clock_name, "checking feature ranges")

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/predict/_pred_utils.py

@@ -14,10 +14,38 @@ except Exception:
 import gc
 
 from ..models import pyagingModel
+from ..preprocess._tage import _prepare_tage
 from ..utils._feature_ranges import resolve_feature_bounds
 from ..utils._hf import PyAgingResourceNotFoundError, download_clock_weights
 from ..utils._utils import progress
 
+# Whole-cohort preprocessing a clock can ask ``predict_age`` to run for it, by
+# name. A transform takes the raw AnnData and returns a samples x features
+# frame; it must not write to ``adata.X``, since the other clocks in the same
+# call still read the original matrix.
+COHORT_TRANSFORMS = {"tage": _prepare_tage}
+
+
+@progress("Run the cohort transform")
+def apply_cohort_transform(
+    adata: anndata.AnnData,
+    transform_name: str,
+    dir: str,
+    logger,
+    indent_level: int = 2,
+):
+    """Run the named cohort transform over the whole input and return its frame."""
+    try:
+        transform = COHORT_TRANSFORMS[transform_name]
+    except KeyError:
+        message = (
+            f"This clock asks for a cohort transform named {transform_name!r}, which this version of "
+            f"pyaging does not provide. Known transforms: {sorted(COHORT_TRANSFORMS)}."
+        )
+        logger.error(message, indent_level=indent_level + 1)
+        raise ValueError(message) from None
+    return transform(adata, dir=dir, logger=logger)
+
 
 def load_clock(
     clock_name: str,
@@ -94,8 +122,12 @@ def _load_clock_impl(clock_name: str, device: str, dir: str, logger, indent_leve
     try:
         weights_path = download_clock_weights(clock_name, dir, logger, indent_level=indent_level)
     except PyAgingResourceNotFoundError as exc:
+        from pyaging import __version__
+
         message = (
-            f"Clock {clock_name} is not available on pyaging. "
+            f"Clock {clock_name} is not available on pyaging {__version__}. "
+            "This clock may require a newer pyaging release; check PyPI and run "
+            "`pip install --upgrade pyaging` if a newer version is available. "
             "Please refer to the clock names in the clock glossary table "
             "in the package documentation page: pyaging.readthedocs.io"
         )
@@ -173,6 +205,81 @@ def check_features_in_adata(
     >>> updated_adata.var_names
     Index(['gene1', 'gene2', ...], dtype='object')
 
+    """
+    _align_features_into_obsm(adata, model, adata.X, adata.var_names, logger, indent_level)
+
+
+@progress("Build the cohort feature matrix")
+def build_cohort_feature_matrix(
+    adata: anndata.AnnData,
+    model: pyagingModel,
+    frame,
+    logger,
+    indent_level: int = 2,
+) -> None:
+    """
+    Assemble a cohort-relative clock's feature matrix from its transformed frame.
+
+    A clock declaring ``cohort_transform`` is not scored against ``adata.X``: its
+    features live in the space the transform produces (for tAge, cohort-centred
+    mouse Entrez columns), so alignment reads that frame instead. Everything else
+    -- reference-value substitution for features the transform did not yield, the
+    missing-feature bookkeeping, and the supplied-features mask that
+    :func:`check_feature_ranges` reads -- is identical to
+    :func:`check_features_in_adata`, which is why both share one implementation.
+
+    Parameters
+    ----------
+    adata : anndata.AnnData
+        The object the matrix and the bookkeeping are written to. Its ``.X`` is
+        only read by the transform, never here.
+
+    model : pyagingModel
+        The clock being aligned.
+
+    frame : pandas.DataFrame
+        Samples x transformed-features, in the row order of ``adata``.
+
+    logger : Logger
+        A logger object used for logging information about the process.
+
+    indent_level : int, optional
+        The indentation level for the logger, by default 2.
+
+    Returns
+    -------
+    None
+        The AnnData object is updated in place.
+
+    Raises
+    ------
+    ValueError
+        If the frame's rows are not the cohort's samples. The matrix is filled
+        positionally, so a frame holding different samples -- or the same ones
+        under duplicated labels -- would attach one sample's expression to
+        another's predicted age, which is worse than not predicting at all. A
+        frame that merely orders the same samples differently is reordered to
+        match rather than rejected.
+    """
+    if not frame.index.equals(adata.obs_names):
+        if frame.index.has_duplicates or set(frame.index) != set(adata.obs_names):
+            message = (
+                f"The cohort transform returned {len(frame.index)} rows that are not this cohort's "
+                f"{adata.n_obs} samples, so its values cannot be matched to them."
+            )
+            logger.error(message, indent_level=indent_level + 1)
+            raise ValueError(message)
+        frame = frame.reindex(adata.obs_names)
+
+    _align_features_into_obsm(adata, model, frame.to_numpy(), frame.columns, logger, indent_level)
+
+
+def _align_features_into_obsm(adata, model, source_values, source_features, logger, indent_level: int) -> None:
+    """Fill ``obsm["X_{clock}"]`` from ``source_values``, one column per model feature.
+
+    Features the source does not carry take the model's reference value (or 0
+    when it has none), and the substitutions are recorded so downstream checks
+    can tell the input's own values apart from the pipeline's.
     """
 
     # Preallocate the data matrix
@@ -182,8 +289,8 @@ def check_features_in_adata(
         else np.empty((adata.n_obs, len(model.features)), order="F")
     )
 
-    # Find indices of matching features in adata.var_names
-    feature_indices = {feature: i for i, feature in enumerate(adata.var_names)}
+    # Find indices of matching features among the source's own feature names
+    feature_indices = {feature: i for i, feature in enumerate(source_features)}
     model_feature_indices = np.array([feature_indices.get(feature, -1) for feature in model.features])
 
     # Identify missing features
@@ -193,7 +300,9 @@ def check_features_in_adata(
     # Assign values for existing features
     existing_features_mask = ~missing_features_mask
     existing_features_indices = model_feature_indices[existing_features_mask]
-    adata.obsm[f"X_{model.metadata['clock_name']}"][:, existing_features_mask] = adata.X[:, existing_features_indices]
+    adata.obsm[f"X_{model.metadata['clock_name']}"][:, existing_features_mask] = source_values[
+        :, existing_features_indices
+    ]
 
     # Handle missing features
     adata.obsm[f"X_{model.metadata['clock_name']}"][:, missing_features_mask] = (
@@ -347,7 +456,7 @@ def check_feature_ranges(
     try:
         units, low, high = resolve_feature_bounds(
             model.features,
-            model.metadata.get("data_type"),
+            getattr(model, "feature_range_data_type", None) or model.metadata.get("data_type"),
             getattr(model, "feature_units", None),
         )
     except Exception as exc:

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/predict/_transforms.py

@@ -99,6 +99,35 @@ def quantile_normalize_with_gold_standard(x, gold_standard_means):
     return x_normalized
 
 
+def mortality_to_phenoage_saopaulo(x, m_n, m_d, ba_n, ba_d, ba_i):
+    """
+    Applies a convertion from a CDF of the mortality score from a Gompertz
+    distribution to phenotypic age, using constants supplied by the caller.
+
+    Levine's 2018 PhenoAge hardcodes its published constants. A refit of that
+    model fits its own mortality-to-age constants alongside its coefficients,
+    so they are passed in rather than baked in.
+
+    Parameters
+    ----------
+    x : torch.Tensor
+        The linear predictor, one value per sample.
+
+    m_n, m_d : torch.Tensor
+        Numerator and denominator of the Gompertz mortality exponent.
+
+    ba_n, ba_d, ba_i : torch.Tensor
+        Scale, rate, and intercept converting mortality back to years.
+
+    Returns
+    -------
+    torch.Tensor
+        Phenotypic age in years.
+    """
+    mortality_score = 1 - torch.exp(m_n * torch.exp(x) / m_d)
+    return torch.log(ba_n * torch.log(1 - mortality_score)) / ba_d + ba_i
+
+
 # Lowest C-reactive protein ``PhenoAge`` will take the natural log of, in mg/dL. Its
 # clamp is the only CRP transform that needs a floor, and the value matches the registry
 # floor in data/feature_ranges.json so that anything the clamp touches has already been

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/preprocess/__init__.py

@@ -9,8 +9,10 @@ from ._preprocess_utils import (
     load_ensembl_metadata,
     log_data_statistics,
 )
+from ._tage import TAGE_SPECIES
 
 __all__ = [
+    "TAGE_SPECIES",
     "add_metadata_to_anndata",
     "add_unstructured_data",
     "bigwig_to_df",

pyaging-0.5.2/src/pyaging/preprocess/_tage.py

@@ -0,0 +1,366 @@
+"""Cohort preprocessing for the tAge transcriptomic clocks (Tyshkovskiy 2026).
+
+The tAge models live in mouse Entrez gene space, so expression from any of the
+four supported species has to be translated before anything else happens.
+``_map_to_mouse_entrez`` mirrors ``map_genes`` in the reference package's
+``R/genes.R``: an unrecognised gene is dropped, and several source genes landing
+on the same mouse Entrez ID have their values **summed** into one column
+(``tapply(x, mapped_ids, sum)`` in ``.apply_gene_mapping``). Summing is correct
+here because mapping happens on raw counts, before normalisation.
+
+The reference resolves IDs in two hops (source ID -> source-species Entrez ->
+mouse Entrez, the second hop skipped for mouse and macaque) and, unlike the
+first hop, breaks ties in the second by keeping the first row rather than
+summing. The mapping asset built by ``clocks/build_tage_gene_mapping.py``
+flattens both hops into a single lookup, which is exact rather than an
+approximation only because every ortholog hop is injective on the reference
+tables; the build script asserts that invariant.
+"""
+
+import warnings
+
+import numpy as np
+import pandas as pd
+
+from ..utils._hf import download_hf_file
+
+TAGE_SPECIES = ("mouse", "rat", "macaque", "human")
+
+# ``var_names`` that carry the cohort's species rather than a gene, one 0/1
+# value per sample. The clocks reuse the mammalian-array idiom, where a
+# covariate such as ``female`` is simply another column of the matrix.
+SPECIES_COLUMNS = TAGE_SPECIES
+
+# ``obs`` column naming the samples to centre against.
+REFERENCE_COLUMN = "tage_reference_group"
+
+# filter_genes' defaults in the reference pipeline (R/preprocessing.R:68).
+COUNT_THRESHOLD = 10
+PERCENT_THRESHOLD = 20
+
+
+def _warn(logger, message: str) -> None:
+    """Raise a warning on both the predict display and Python's warnings channel.
+
+    The display logger renders nothing at ``verbose=False``, so a warning that
+    only went there would be invisible in exactly the scripted runs where it
+    matters most -- notably the silent default to mouse, which can score a human
+    cohort as a mouse one. Both channels are fed from one string so their
+    wording cannot drift apart.
+
+    ``stacklevel=2`` blames the pipeline stage that called this, not this line.
+    Reaching the user's ``predict_age`` call would mean hard-coding the depth of
+    ``predict_age -> apply_cohort_transform -> _prepare_tage``, which is more
+    fragile than it is worth.
+    """
+    logger.warning(message, indent_level=2)
+    warnings.warn(message, UserWarning, stacklevel=2)
+
+
+def _filter_genes(
+    df: pd.DataFrame, count_threshold: int = COUNT_THRESHOLD, percent_threshold: float = PERCENT_THRESHOLD
+) -> pd.DataFrame:
+    """Drop genes not expressed in enough samples, as ``filter_genes`` does.
+
+    The reference (``R/preprocessing.R:72``) keeps a gene when
+    ``sum(x >= count_threshold, na.rm = TRUE) >= ncol * (percent_threshold/100)``.
+    Both comparisons are inclusive, and ``na.rm`` means a missing count never
+    counts toward the quota -- which ``NaN >= threshold`` reproduces, since that
+    comparison is ``False``.
+
+    The filter is not cosmetic: on the authors' own example data it takes 57 010
+    genes down to 19 550, and running the mapper without it yields a different
+    gene set (28 266 columns) and different RLE factors downstream.
+    """
+    passing = (df >= count_threshold).sum(axis=0) >= df.shape[0] * (percent_threshold / 100)
+    return df.loc[:, passing]
+
+
+def _map_to_mouse_entrez(df: pd.DataFrame, species: str, mapping: pd.DataFrame) -> pd.DataFrame:
+    """Translate a samples x genes frame into samples x mouse-Entrez columns.
+
+    Genes with no mapping are dropped; genes sharing a mouse Entrez ID are summed.
+    """
+    if species not in TAGE_SPECIES:
+        raise ValueError(f"species must be one of {TAGE_SPECIES}, got {species!r}")
+
+    rows = mapping[mapping["species"] == species]
+    lookup = dict(zip(rows["source_id"], rows["mouse_entrez"], strict=True))
+
+    # Entrez IDs read from a CSV arrive as integers, so normalise before lookup.
+    targets = df.columns.astype(str).str.upper().map(lookup)
+    kept = targets.notna()
+
+    mapped = df.loc[:, kept].copy()
+    mapped.columns = targets[kept]
+    return mapped.T.groupby(level=0).sum().T
+
+
+def _rle_normalize(df: pd.DataFrame) -> pd.DataFrame:
+    """Scale raw counts by edgeR's RLE factors, as ``RLE_normalization`` does.
+
+    The reference (``R/preprocessing.R:111``) divides the counts by
+    ``lib.size * calcNormFactors(counts, method = "RLE")`` and multiplies by
+    1e7, so the result is counts per 10 million RLE-adjusted library size.
+
+    edgeR's RLE factor for a sample is the median ratio of its counts to the
+    per-gene geometric mean over the cohort, taken over the genes whose
+    geometric mean is nonzero (``.calcFactorRLE``); ``calcNormFactors`` then
+    divides by the library size and rescales the factors to a geometric mean of
+    one. A gene that is zero in any sample has a zero geometric mean and so
+    drops out, which also covers edgeR's up-front removal of all-zero genes.
+    """
+    counts = df.to_numpy(dtype=float)
+    if counts.shape[1] == 0:
+        raise ValueError("RLE normalization needs at least one gene")
+    if np.isnan(counts).any():
+        # calcNormFactors stops on NA counts rather than propagating them.
+        raise ValueError("RLE normalization needs counts without missing values")
+
+    library_sizes = counts.sum(axis=1)
+    with np.errstate(divide="ignore"):
+        # log(0) -> -inf -> a zero geometric mean, which is what excludes the gene.
+        geometric_means = np.exp(np.log(counts).mean(axis=0))
+    usable = geometric_means > 0
+    if not usable.any():
+        raise ValueError("RLE normalization needs a gene expressed in every sample")
+
+    ratios = counts[:, usable] / geometric_means[usable]
+    factors = np.median(ratios, axis=1) / library_sizes
+    factors /= np.exp(np.log(factors).mean())
+
+    return df.div(library_sizes * factors, axis=0) * 1e7
+
+
+def _log_transform(df: pd.DataFrame) -> pd.DataFrame:
+    """Apply ``log10(x + 1)``, matching ``log_transform`` (``R/preprocessing.R:218``)."""
+    return np.log10(df + 1.0)
+
+
+def _scale_samples(df: pd.DataFrame) -> pd.DataFrame:
+    """Z-score each sample across its genes, as ``scale_eset`` does.
+
+    ``scale_eset`` (``R/preprocessing.R:254``) calls base R's ``scale()`` on a
+    genes x samples matrix, and ``scale()`` works down the columns -- so despite
+    the reference's name for the stage the standardisation is per sample, over
+    the gene axis, with the sample standard deviation (``ddof=1``). A sample with
+    no variation yields ``NaN`` here exactly as it does in R; nothing fills it in.
+    """
+    return df.sub(df.mean(axis=1), axis=0).div(df.std(axis=1, ddof=1), axis=0)
+
+
+def _center_against_reference(df: pd.DataFrame, reference_index=None) -> pd.DataFrame:
+    """Subtract the reference group's per-gene median from every sample.
+
+    Mirrors ``control_subtraction`` (``R/preprocessing.R:298``): with no
+    reference group the median is taken over all samples, and the median skips
+    missing values (``na.rm = TRUE``), so a gene the alignment stage padded with
+    ``NaN`` stays ``NaN`` for the model's imputer to fill.
+
+    ``reference_index`` is a list of sample labels; ``None`` centres on the whole
+    cohort.
+    """
+    reference = df if reference_index is None else df.loc[reference_index]
+    if reference.empty:
+        raise ValueError("reference_index selects no samples")
+    return df.sub(reference.median(axis=0), axis=1)
+
+
+def _load_mapping(dir: str) -> pd.DataFrame:
+    """Fetch the flattened source-ID -> mouse-Entrez lookup from the Hub."""
+    path = download_hf_file("tage_gene_mapping.csv.gz", dir, repo_id="pyaging/tage")
+    return pd.read_csv(path, dtype=str)
+
+
+def _resolve_species(frame: pd.DataFrame, logger) -> tuple[str, pd.DataFrame]:
+    """Read the cohort's species off its indicator columns and drop them.
+
+    A species indicator is a column of the matrix, not a gene: one 0/1 value per
+    sample, the same for every sample, named after the species. Exactly one
+    indicator set to 1 picks the species; none at all -- or all of them zero --
+    means mouse, which is what the clocks were trained in. Names are matched
+    case-insensitively, so a ``Human`` column can never be read as an unlabelled
+    mouse cohort.
+
+    The indicators are dropped whether or not they were used. The gene mapping
+    would drop them anyway, but only after the gene filter had counted them, and
+    a column of ones is not a gene.
+    """
+    indicators = [name for name in frame.columns if str(name).strip().lower() in SPECIES_COLUMNS]
+    selected = []
+    for name in indicators:
+        values = frame[name].to_numpy(dtype=float)
+        unique = np.unique(values)
+        if unique.size != 1:
+            raise ValueError(
+                f"the {name!r} species indicator must hold the same value for every sample, "
+                f"got {unique.size} distinct values"
+            )
+        if unique[0] not in (0.0, 1.0):
+            raise ValueError(f"the {name!r} species indicator must be 0 or 1, got {unique[0]:g}")
+        if unique[0] == 1.0:
+            selected.append(str(name).strip().lower())
+
+    if len(selected) > 1:
+        raise ValueError(f"more than one species indicator is set to 1: {sorted(selected)}")
+
+    remaining = frame.drop(columns=indicators)
+    if not selected:
+        _warn(
+            logger,
+            "no species indicator column found; defaulting to mouse (add a column named "
+            f"{'/'.join(SPECIES_COLUMNS)}, set to 1 for every sample, to say otherwise)",
+        )
+        return "mouse", remaining
+    return selected[0], remaining
+
+
+def _resolve_reference_group(adata) -> list | None:
+    """Read the samples to centre against from ``obs[REFERENCE_COLUMN]``.
+
+    Absent, the cohort centres on every sample -- the reference pipeline's own
+    default. Present, the truthy rows are the reference group.
+    """
+    if REFERENCE_COLUMN not in adata.obs.columns:
+        return None
+    column = adata.obs[REFERENCE_COLUMN]
+    values = np.asarray(column)
+    if values.dtype == bool:
+        mask = values
+    elif np.issubdtype(values.dtype, np.number):
+        mask = values != 0
+    else:
+        raise ValueError(f"adata.obs[{REFERENCE_COLUMN!r}] must be boolean (or 0/1), got dtype {values.dtype}")
+    names = list(adata.obs_names[mask])
+    if len(names) == 0:
+        raise ValueError(f"adata.obs[{REFERENCE_COLUMN!r}] selects no samples")
+    return names
+
+
+def _prepare_tage(adata, dir: str = "pyaging_data", logger=None) -> pd.DataFrame:
+    """
+    Run the tAge cohort preprocessing on a matrix of raw RNA-seq counts.
+
+    Reproduces the ``scaled_diff`` branch of the reference package's
+    ``tAge_preprocessing()`` (Tyshkovskiy 2026): drop the species indicator
+    columns -> filter genes -> map to mouse Entrez IDs -> RLE normalise ->
+    ``log10(x + 1)`` -> z-score each sample -> subtract the reference group's
+    per-gene median. Matching the clocks' feature lists happens afterwards, back
+    in ``predict_age``.
+
+    ``predict_age`` calls this for any clock declaring ``cohort_transform =
+    "tage"``, once per call however many such clocks are requested; it is not a
+    step users perform themselves. The species and the reference group are read
+    off the input rather than passed as arguments, because by the time this runs
+    there is no user call to pass them to: the species comes from a 0/1
+    indicator column among ``var_names``, and the reference group from
+    ``obs["tage_reference_group"]``.
+
+    The tAge clocks are cohort-relative: every stage above uses statistics of the
+    whole input, so predictions depend on which samples are predicted together. A
+    single sample cannot be prepared, and a prediction is an age difference
+    against the reference group rather than an absolute age.
+
+    Two samples clear the hard minimum but are not enough to normalise against:
+    the RLE factors, the reference median, and the gene filter are all cohort
+    statistics, so a very small cohort (roughly fewer than ten samples, or a
+    reference group that small) makes them noisy and the resulting predictions
+    correspondingly unstable. Nothing here rejects such an input; interpret it
+    with that in mind.
+
+    Parameters
+    ----------
+    adata : anndata.AnnData
+        Samples x genes raw counts. ``var_names`` must be gene identifiers
+        (symbols, Ensembl, or Entrez IDs) of the cohort's species, optionally
+        alongside a species indicator column.
+    dir : str
+        Directory the gene mapping is downloaded to. Defaults to "pyaging_data".
+    logger : optional
+        Internal pipeline logger; warnings surface on the predict display, and
+        the two that would otherwise pass unnoticed -- the default to mouse and
+        a poor gene overlap -- are also raised as ``UserWarning`` so they survive
+        ``verbose=False``.
+
+    Returns
+    -------
+    pandas.DataFrame
+        The centred matrix, samples x mouse Entrez IDs. ``adata`` itself is left
+        untouched apart from ``uns["tage_preparation"]``, which records the run's
+        parameters and mapping statistics.
+
+    Raises
+    ------
+    ValueError
+        If the species indicators are inconsistent, fewer than two samples are
+        given, the reference column selects no samples, or no gene survives
+        filtering and mapping.
+
+    Notes
+    -----
+    One deliberate divergence from the reference: when its ``control_group_label``
+    matches no sample, ``control_subtraction`` falls back to centring on the whole
+    cohort with only a printed message. That silently answers a different question
+    than the one asked, so an empty reference column raises here instead.
+    """
+    if logger is None:
+        logger = _NullLogger()
+    if adata.n_obs < 2:
+        raise ValueError("the tAge clocks are cohort-relative and need at least two samples")
+
+    reference_index = _resolve_reference_group(adata)
+
+    # ``to_df`` densifies a sparse matrix and labels the axes; the ``astype``
+    # copies, so nothing downstream can reach the caller's counts and the other
+    # clocks in the same predict_age call still see the original data.
+    frame = adata.to_df().astype(np.float64)
+    species, frame = _resolve_species(frame, logger)
+    if species != "mouse":
+        logger.warning(
+            f"tage is calibrated in months of mouse age; a {species} cohort needs rescaling by its own "
+            "maximum lifespan over 48 months (tagemortality, a log hazard ratio, is never rescaled)",
+            indent_level=2,
+        )
+
+    filtered = _filter_genes(frame)
+    if filtered.shape[1] == 0:
+        raise ValueError(
+            f"no gene reached {COUNT_THRESHOLD} counts in {PERCENT_THRESHOLD}% of samples; "
+            "the tAge clocks expect raw RNA-seq counts, not normalized expression"
+        )
+
+    mapped = _map_to_mouse_entrez(filtered, species, _load_mapping(dir))
+    if mapped.shape[1] == 0:
+        raise ValueError(f"no input gene could be mapped to a mouse Entrez ID for species {species!r}")
+    # Overlap is judged against the filtered genes, not the raw input: an
+    # RNA-seq matrix carries tens of thousands of unexpressed genes that the
+    # filter drops, so the raw fraction says more about annotation size than
+    # about how well the input matches the mapping table.
+    if mapped.shape[1] < 0.5 * filtered.shape[1]:
+        _warn(
+            logger,
+            f"only {mapped.shape[1]} of {filtered.shape[1]} expressed genes mapped to mouse "
+            f"Entrez IDs; check that var_names are {species} gene identifiers",
+        )
+
+    centered = _center_against_reference(_scale_samples(_log_transform(_rle_normalize(mapped))), reference_index)
+
+    adata.uns["tage_preparation"] = {
+        "species": species,
+        "n_input_genes": int(frame.shape[1]),
+        "n_filtered_genes": int(filtered.shape[1]),
+        "n_mapped_genes": int(mapped.shape[1]),
+        "n_reference_samples": len(reference_index) if reference_index is not None else int(adata.n_obs),
+        "reference_group": list(reference_index) if reference_index is not None else "all_samples",
+    }
+    return centered
+
+
+class _NullLogger:
+    """Swallow the pipeline log when the transform is called without a display."""
+
+    def __getattr__(self, name):
+        def _noop(*args, **kwargs):
+            return None
+
+        return _noop

{pyaging-0.5.0 → pyaging-0.5.2}/src/pyaging/utils/_feature_ranges.py

@@ -159,7 +159,7 @@ def get_feature_ranges(clock_name: str):
         raise ValueError(f"clock {clock_name!r} has no feature list, so its feature ranges cannot be resolved")
     records = resolve_feature_ranges(
         model.features,
-        model.metadata.get("data_type"),
+        getattr(model, "feature_range_data_type", None) or model.metadata.get("data_type"),
         getattr(model, "feature_units", None),
     )
     return pd.DataFrame.from_records(records)

pyaging-0.5.0/src/pyaging/predict/_inverse_transforms.py

@@ -1,101 +0,0 @@
-import math
-
-import torch
-
-
-def anti_log_linear(x, adult_age=20):
-    """
-    Applies an anti-logarithmic linear transformation to a value.
-    """
-    if x < 0:
-        # Apply exponential transformation for negative values
-        return (1 + adult_age) * math.exp(x) - 1
-    else:
-        # Apply linear transformation for non-negative values
-        return (1 + adult_age) * x + adult_age
-
-
-def anti_logp2(x):
-    """
-    Applies an anti-logarithmic transformation with an offset of -2.
-    """
-    # Exponential transformation with an offset
-    return math.exp(x) - 2
-
-
-def anti_log(x):
-    """
-    Applies a simple anti-logarithmic transformation.
-    """
-    # Simple exponential transformation
-    return math.exp(x)
-
-
-def anti_log_log(x):
-    """
-    Applies a double transformation: logarithmic followed by anti-logarithmic.
-    """
-    # Double transformation: logarithmic followed by anti-logarithmic
-    return math.exp(-math.exp(-x))
-
-
-def mortality_to_phenoage(x):
-    """
-    Applies a convertion from a CDF of the mortality score from a Gompertz
-    distribution to phenotypic age.
-    """
-    # lambda
-    lambda_ = 0.0192
-    mortality_score = 1 - math.exp(-math.exp(x) * (math.exp(120 * lambda_) - 1) / lambda_)
-    age = 141.50225 + math.log(-0.00553 * math.log(1 - mortality_score)) / 0.090165
-    return age
-
-
-def mortality_to_phenoage_saopaulo(x, m_n, m_d, ba_n, ba_d, ba_i):
-    """
-    Applies a convertion from a CDF of the mortality score from a Gompertz
-    distribution to phenotypic age, using constants supplied by the caller.
-
-    ``mortality_to_phenoage`` hardcodes Levine's 2018 published constants. A
-    refit of that model fits its own mortality-to-age constants alongside its
-    coefficients, so they are passed in rather than baked in.
-
-    Parameters
-    ----------
-    x : torch.Tensor
-        The linear predictor, one value per sample.
-
-    m_n, m_d : torch.Tensor
-        Numerator and denominator of the Gompertz mortality exponent.
-
-    ba_n, ba_d, ba_i : torch.Tensor
-        Scale, rate, and intercept converting mortality back to years.
-
-    Returns
-    -------
-    torch.Tensor
-        Phenotypic age in years.
-    """
-    mortality_score = 1 - torch.exp(m_n * torch.exp(x) / m_d)
-    return torch.log(ba_n * torch.log(1 - mortality_score)) / ba_d + ba_i
-
-
-def petkovichblood(x):
-    """
-    Applies a convertion from the output of an ElasticNet to mouse age in months.
-    """
-    a = 0.1666
-    b = 0.4185
-    c = -1.712
-    age = ((x - c) / a) ** (1 / b)
-    age = age / 30.5  # days to months
-    return age
-
-
-def stubbsmultitissue(x):
-    """
-    Applies a convertion from the output of an ElasticNet to mouse age in months.
-    """
-    age = math.exp(0.1207 * (x**2) + 1.2424 * x + 2.5440) - 3
-    age = age * (7 / 30.5)  # weeks to months
-    return age