pyaging 0.5.3__tar.gz → 0.5.4__tar.gz

{pyaging-0.5.3 → pyaging-0.5.4}/.gitignore

@@ -10,6 +10,10 @@ __pycache__/
 # Tool caches
 .pytest_cache/
 .ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
 
 # Packaging artifacts
 build/
@@ -35,7 +39,7 @@ example_data/
 
 # Generated clock weights and aggregate metadata (published to Hugging Face)
 clocks/weights/
-clocks/metadata/all_clock_metadata.pt
+clocks/metadata/*.pt
 clocks/blood_chemistry_example.pkl
 clocks/blood_chemistry_example.csv
 

{pyaging-0.5.3 → pyaging-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyaging
-Version: 0.5.3
+Version: 0.5.4
 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
@@ -81,7 +81,7 @@ pya.pred.predict_age(adata, ["Horvath2013", "AltumAge", "DunedinPACE"])
 adata.obs.head()
 ```
 
-Clock weights are downloaded on demand from per-clock repositories under the [`pyaging` Hugging Face organization](https://huggingface.co/pyaging) (example data comes from [`lucascamillomd/pyaging-data`](https://huggingface.co/lucascamillomd/pyaging-data)). Set `PYAGING_DATA_REVISION` to an existing data release tag, such as `v0.5.2`, to pin downloads; it defaults to `main`. Package-only releases do not create new HF tags. Version 0.5.3 uses the existing model artifacts.
+Clock weights are downloaded on demand from per-clock repositories under the [`pyaging` Hugging Face organization](https://huggingface.co/pyaging) (example data comes from [`lucascamillomd/pyaging-data`](https://huggingface.co/lucascamillomd/pyaging-data)). Set `PYAGING_DATA_REVISION` to an existing data release tag, such as `v0.5.4`, to pin downloads; it defaults to `main`. Version 0.5.4 adds CellDRIFT, MiAge, PCBrainAge, IntrinClock370, PhenoAge partitions, standalone PCGrimAge proxies, and 90 proteomic OrganAge outputs. See the [input and output guide](https://pyaging.readthedocs.io/en/latest/clocks_0_5_4.html). Model weights retain the original authors’ licensing terms.
 
 ### Run the same clocks across datasets
 

{pyaging-0.5.3 → pyaging-0.5.4}/README.md

@@ -48,7 +48,7 @@ pya.pred.predict_age(adata, ["Horvath2013", "AltumAge", "DunedinPACE"])
 adata.obs.head()
 ```
 
-Clock weights are downloaded on demand from per-clock repositories under the [`pyaging` Hugging Face organization](https://huggingface.co/pyaging) (example data comes from [`lucascamillomd/pyaging-data`](https://huggingface.co/lucascamillomd/pyaging-data)). Set `PYAGING_DATA_REVISION` to an existing data release tag, such as `v0.5.2`, to pin downloads; it defaults to `main`. Package-only releases do not create new HF tags. Version 0.5.3 uses the existing model artifacts.
+Clock weights are downloaded on demand from per-clock repositories under the [`pyaging` Hugging Face organization](https://huggingface.co/pyaging) (example data comes from [`lucascamillomd/pyaging-data`](https://huggingface.co/lucascamillomd/pyaging-data)). Set `PYAGING_DATA_REVISION` to an existing data release tag, such as `v0.5.4`, to pin downloads; it defaults to `main`. Version 0.5.4 adds CellDRIFT, MiAge, PCBrainAge, IntrinClock370, PhenoAge partitions, standalone PCGrimAge proxies, and 90 proteomic OrganAge outputs. See the [input and output guide](https://pyaging.readthedocs.io/en/latest/clocks_0_5_4.html). Model weights retain the original authors’ licensing terms.
 
 ### Run the same clocks across datasets
 

{pyaging-0.5.3 → pyaging-0.5.4}/pyproject.toml

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

{pyaging-0.5.3 → pyaging-0.5.4}/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.3"
+__version__ = "0.5.4"

{pyaging-0.5.3 → pyaging-0.5.4}/src/pyaging/data/feature_ranges.json

@@ -2,6 +2,7 @@
   "schema_version": 1,
   "modality_defaults": {
     "DNA methylation": {"unit": "beta value", "low": 0.0, "high": 1.0},
+    "proteomics": {"unit": "NPX", "low": null, "high": null},
     "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},

{pyaging-0.5.3 → pyaging-0.5.4}/src/pyaging/logger/_logger.py

@@ -46,7 +46,7 @@ def format_logging_message(msg, logging_level, indent_level=1, indent_space_num=
 
 
 class Logger:
-    """Logger that sets up pyaging's legacy text progress output."""
+    """Logger for pyaging's text output and file logging."""
 
     FORMAT = "%(message)s"
 

{pyaging-0.5.3 → pyaging-0.5.4}/src/pyaging/models/__init__.py

@@ -1,5 +1,6 @@
 # pyaging/models/__init__.py
 
+from ._author_extensions import DNAmPhenoAgeNonPRC, DNAmPhenoAgePRC, IntrinClock370
 from ._base_models import (
     AltumAgeNeuralNetwork,
     LinearModel,
@@ -173,8 +174,36 @@ from ._models import (
     epiTOC2,
     stemTOC,
 )
+from ._organage import OrganAge
+from ._pc_extensions import (
+    PCBrainAge,
+    PCGrimAgeADM,
+    PCGrimAgeB2M,
+    PCGrimAgeCystatinC,
+    PCGrimAgeGDF15,
+    PCGrimAgeLeptin,
+    PCGrimAgePackYrs,
+    PCGrimAgePAI1,
+    PCGrimAgeTIMP1,
+)
+from ._replication import CellDRIFT, MiAge
 
 __all__ = [
+    "CellDRIFT",
+    "DNAmPhenoAgeNonPRC",
+    "DNAmPhenoAgePRC",
+    "IntrinClock370",
+    "MiAge",
+    "OrganAge",
+    "PCBrainAge",
+    "PCGrimAgeADM",
+    "PCGrimAgeB2M",
+    "PCGrimAgeCystatinC",
+    "PCGrimAgeGDF15",
+    "PCGrimAgeLeptin",
+    "PCGrimAgePackYrs",
+    "PCGrimAgePAI1",
+    "PCGrimAgeTIMP1",
     "ABEC",
     "ADBahadoSingh",
     "AltumAge",

pyaging-0.5.4/src/pyaging/models/_author_extensions.py

@@ -0,0 +1,28 @@
+"""Author-defined IntrinClock and PhenoAge variants."""
+
+import torch
+
+from ._base_models import pyagingModel
+from ._models import IntrinClock
+
+
+class IntrinClock370(IntrinClock):
+    """The original cv.glmnet model at lambda.1se, as used by the author demo."""
+
+
+class DNAmPhenoAgePRC(pyagingModel):
+    """Polycomb-related PhenoAge contribution, with no age intercept.
+
+    Matches the author's ``calcPRCPhenoAge(..., imputation = FALSE)``:
+    missing CpGs and supplied NA beta values make zero contribution.
+    """
+
+    def preprocess(self, x):
+        return torch.where(torch.isnan(x), torch.zeros_like(x), x)
+
+    def postprocess(self, x):
+        return x
+
+
+class DNAmPhenoAgeNonPRC(DNAmPhenoAgePRC):
+    """Complementary non-polycomb PhenoAge contribution, without intercept."""

pyaging-0.5.4/src/pyaging/models/_organage.py

@@ -0,0 +1,33 @@
+"""Goeminne et al. plasma-protein OrganAge models.
+
+Original author code and coefficients:
+https://github.com/ludgergoeminne/organAging
+DOI: 10.1016/j.cmet.2024.10.005
+
+The released coefficients are subject to the authors' Academic / Non-Commercial
+License. Each converted artifact carries that license and its pinned provenance.
+"""
+
+from ._base_models import pyagingModel
+
+
+class OrganAge(pyagingModel):
+    """Score Olink NPX values with a released OrganAge coefficient vector.
+
+    Protein names are the authors' case-sensitive symbols, including hyphens.
+    NPX values are already normalized; no cohort scaling is applied here. The
+    authors recommend fold one for new data. Chronological models include an
+    intercept and return years; mortality models have no intercept and return
+    relative natural-log mortality hazards.
+
+    The authors' example omits absent protein columns and propagates NaN values
+    in present columns. Zero-filled absent features preserve that omission in
+    pyaging, while present NaNs remain NaNs. Any imputation performed before
+    scoring is the caller's separate data-preparation decision.
+    """
+
+    def preprocess(self, x):
+        return x
+
+    def postprocess(self, x):
+        return x

pyaging-0.5.4/src/pyaging/models/_pc_extensions.py

@@ -0,0 +1,67 @@
+"""PC clocks evaluated with algebraically composed PCA/regression weights.
+
+The builders preserve the original authors' double-precision coefficients.
+Composing rotation and regression once avoids storing the large PCA rotation
+again for each standalone PCGrimAge proxy. This does not retrain the models.
+"""
+
+import torch
+
+from ._models import LinearReferenceClock
+
+
+class PCBrainAge(LinearReferenceClock):
+    """Thrush et al. brain chronological-age predictor, in years."""
+
+
+class _PCGrimAgeProxy(LinearReferenceClock):
+    """Keep the selected original demographic covariates mandatory."""
+
+    def __init__(self):
+        super().__init__()
+        self.required_covariates = []
+        self.register_buffer("required_covariate_indices", torch.empty(0, dtype=torch.long))
+
+    def preprocess(self, x):
+        selected = x[:, self.required_covariate_indices]
+        invalid = ~torch.isfinite(selected)
+        if invalid.any():
+            bad_columns = invalid.any(dim=0).nonzero().flatten().tolist()
+            names = ", ".join(self.required_covariates[i] for i in bad_columns)
+            raise ValueError(
+                f"{self.metadata.get('clock_name') or type(self).__name__} requires "
+                f"supplied finite demographic inputs for every sample: {names}."
+            )
+        return super().preprocess(x)
+
+
+class PCGrimAgePackYrs(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm smoking pack-years proxy."""
+
+
+class PCGrimAgeADM(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm adrenomedullin proxy."""
+
+
+class PCGrimAgeB2M(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm beta-2-microglobulin proxy."""
+
+
+class PCGrimAgeCystatinC(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm cystatin C proxy."""
+
+
+class PCGrimAgeGDF15(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm GDF15 proxy."""
+
+
+class PCGrimAgeLeptin(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm leptin proxy."""
+
+
+class PCGrimAgePAI1(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm PAI-1 proxy."""
+
+
+class PCGrimAgeTIMP1(_PCGrimAgeProxy):
+    """Higgins-Chen et al. PC-based DNAm TIMP-1 proxy."""

pyaging-0.5.4/src/pyaging/models/_replication.py

@@ -0,0 +1,88 @@
+"""DNA-methylation clocks of cellular replication from the authors' releases."""
+
+import torch
+
+from ._base_models import pyagingModel
+
+
+class CellDRIFT(pyagingModel):
+    """CellDRIFT with its two PCA projections folded into the linear weights.
+
+    The original authors set supplied NaNs to zero. Entirely absent CpGs use
+    the released module means, carried in ``reference_values`` for alignment.
+    """
+
+    def preprocess(self, x):
+        return torch.where(torch.isnan(x), torch.zeros_like(x), x)
+
+    def postprocess(self, x):
+        return x
+
+
+class MiAge(pyagingModel):
+    """The authors' five-start bounded nonlinear MiAge least-squares fit.
+
+    L-BFGS-B is evaluated on CPU in float64 and its result returns to the input
+    tensor's dtype/device. Missing beta values are omitted from the objective,
+    exactly as ``na.rm=TRUE`` in the original R functions. An all-NaN sample
+    therefore returns the first tied start (2008), which is not a valid
+    biological estimate; callers should ensure measured CpGs are available.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.register_buffer("b", torch.empty(0, dtype=torch.float64))
+        self.register_buffer("c", torch.empty(0, dtype=torch.float64))
+        self.register_buffer("d", torch.empty(0, dtype=torch.float64))
+
+    def set_parameters(self, b, c, d):
+        self.b = torch.tensor(b, dtype=torch.float64)
+        self.c = torch.tensor(c, dtype=torch.float64)
+        self.d = torch.tensor(d, dtype=torch.float64)
+
+    def preprocess(self, x):
+        return x
+
+    def postprocess(self, x):
+        return x
+
+    def forward(self, x):
+        import numpy as np
+        from scipy.optimize import fmin_l_bfgs_b
+
+        values = x.detach().to(device="cpu", dtype=torch.float64).numpy()
+        if np.isinf(values).any():
+            raise ValueError("MiAge beta values must be finite or NaN.")
+        b, c, d = (value.detach().to(device="cpu", dtype=torch.float64).numpy() for value in (self.b, self.c, self.d))
+        log_b = np.log(b)
+        result = np.empty((len(values), 1), dtype=np.float64)
+        for index, row in enumerate(values):
+            supplied = ~np.isnan(row)
+            observed, local_c, local_d = row[supplied], c[supplied], d[supplied]
+            local_b, local_log = b[supplied], log_b[supplied]
+
+            def objective(n, local_b=local_b, local_c=local_c, local_d=local_d, observed=observed, local_log=local_log):
+                power = np.power(local_b, n[0] - 1)
+                residual = local_c + power * local_d - observed
+                value = np.sum(residual * residual)
+                gradient = 2 * np.sum(residual * power * local_log * local_d)
+                return value, np.array([gradient])
+
+            best_value, best_n = np.inf, 2008.0
+            # R optim defaults: lmm=5, pgtol=0, maxit=100; author factr=1.
+            for start in (2008.0, 4006.0, 6004.0, 8002.0, 500.0):
+                n, value, _ = fmin_l_bfgs_b(
+                    objective,
+                    np.array([start]),
+                    bounds=[(10.0, 10000.0)],
+                    m=5,
+                    factr=1.0,
+                    pgtol=0.0,
+                    maxiter=100,
+                )
+                if value < best_value:
+                    best_value, best_n = value, n[0]
+            if not np.isfinite(best_value):
+                raise ValueError("MiAge could not obtain a finite least-squares objective for this sample.")
+            result[index, 0] = best_n
+        return torch.as_tensor(result, dtype=x.dtype, device=x.device)

{pyaging-0.5.3 → pyaging-0.5.4}/src/pyaging/predict/_pred.py

@@ -114,12 +114,10 @@ def predict_age(
     if adata.n_obs == 0:
         raise ValueError("Prediction requires at least one sample.")
 
-    # Ensure clock_names is a list with lowercase names
     if isinstance(clock_names, str):
         clock_names = [clock_names]
     clock_names = [clock_name.lower() for clock_name in clock_names]
 
-    # Set device for PyTorch operations
     device = set_torch_device()
 
     enabled = display_enabled(verbose)
@@ -131,10 +129,8 @@ def predict_age(
     with quiet_hf_bars(verbose), display:
         for clock_name in clock_names:
             display.start_clock(clock_name, "loading weights")
-            # Pipeline warnings surface on the display
             pipeline_logger = DisplayLogger(lambda m, name=clock_name: display.warn(name, m))
 
-            # Load and prepare the clock
             if clock_cache is None:
                 model = load_clock(clock_name, device, dir, pipeline_logger)
             else:
@@ -154,11 +150,9 @@ def predict_age(
                     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
             if transform_name is not None:
                 # Cohort-relative clock: its features live in the space the
                 # transform produces, not in adata.X.
@@ -171,11 +165,9 @@ def predict_age(
                 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")
             check_feature_ranges(adata, model, pipeline_logger)
 
-            # Perform age prediction applying preprocessing and postprocessing steps
             display.stage(clock_name, "predicting")
 
             def progress_callback(completed, total, name=clock_name):
@@ -185,11 +177,9 @@ def predict_age(
                 adata, model, device, batch_size, pipeline_logger, progress_callback=progress_callback
             )
 
-            # Add predicted ages and clock metadata to adata
             display.stage(clock_name, "writing results")
             add_pred_ages_and_clock_metadata_adata(adata, model, predicted_ages_tensor, dir, pipeline_logger)
 
-            # Delete the clock matrix object
             if clean:
                 del adata.obsm[f"X_{clock_name}"]
 

{pyaging-0.5.3 → pyaging-0.5.4}/src/pyaging/predict/_pred_utils.py

@@ -16,7 +16,7 @@ except Exception:
 
 import gc
 
-from ..models import pyagingModel
+from ..models._base_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
@@ -137,12 +137,10 @@ def _load_clock_impl(clock_name: str, device: str, dir: str, logger, indent_leve
         logger.error(message, indent_level=indent_level + 1)
         raise NameError(message) from exc
 
-    # Load the clock from the file
     # Restore on CPU even when the weights were saved from a CUDA device. The
     # explicit transfer below then respects the caller's selected device.
     clock = torch.load(weights_path, weights_only=False, map_location="cpu")
 
-    # Prepare clock for inference
     clock.to(torch.float64)
     clock.to(device)
     clock.eval()
@@ -301,11 +299,9 @@ def _align_features_into_obsm(adata, model, source_values, source_features, logg
     # instead of rebuilding a Python dictionary over every input feature.
     model_feature_indices = source_features.get_indexer(model.features)
 
-    # Identify missing features
     missing_features_mask = model_feature_indices == -1
     missing_features = np.array(model.features)[missing_features_mask].tolist()
 
-    # Assign values for existing features
     existing_features_mask = ~missing_features_mask
     existing_features_indices = model_feature_indices[existing_features_mask]
     supplied_values = source_values[:, existing_features_indices]
@@ -315,23 +311,19 @@ def _align_features_into_obsm(adata, model, source_values, source_features, logg
         supplied_values = cp.asnumpy(supplied_values)
     matrix[:, existing_features_mask] = supplied_values
 
-    # Handle missing features
     matrix[:, missing_features_mask] = (
         np.array(model.reference_values)[missing_features_mask] if model.reference_values is not None else 0
     )
     adata.obsm[f"X_{model.metadata['clock_name']}"] = matrix
 
-    # Calculate missing features statistics
     num_missing_features = len(missing_features)
     percent_missing = 100 * num_missing_features / len(model.features)
 
-    # Add missing features and percent missing values to the clock
     adata.uns[f"{model.metadata['clock_name']}_percent_na"] = percent_missing
     adata.uns[f"{model.metadata['clock_name']}_missing_features"] = missing_features
     # Columns the input carried; check_feature_ranges judges only these.
     adata.uns[f"{model.metadata['clock_name']}_supplied_features_mask"] = existing_features_mask
 
-    # Raises error if there are no features in the data
     if percent_missing == 100:
         message = (
             f"Every single feature out of {len(model.features)} features "
@@ -342,14 +334,12 @@ def _align_features_into_obsm(adata, model, source_values, source_features, logg
         logger.error(message, indent_level=3)
         raise NameError(message)
 
-    # Log and add missing features if any
     if len(missing_features) > 0:
         logger.warning(
             f"{num_missing_features} out of {len(model.features)} features "
             f"({percent_missing:.2f}%) are missing: {missing_features[: np.min([3, num_missing_features])]}, etc.",
             indent_level=indent_level + 1,
         )
-        # If there are reference values provided
         if model.reference_values is not None:
             logger.info(
                 f"Using reference feature values for {model.metadata['clock_name']}",
@@ -577,7 +567,6 @@ def predict_ages_with_model(
     if adata.n_obs == 0:
         raise ValueError("Prediction requires at least one sample.")
 
-    # If there is a preprocessing step
     if model.preprocess_name is not None:
         logger.info(
             f"The preprocessing method is {model.preprocess_name}",
@@ -586,7 +575,6 @@ def predict_ages_with_model(
     else:
         logger.info("There is no preprocessing necessary", indent_level=indent_level + 1)
 
-    # If there is a postprocessing step
     if model.postprocess_name is not None:
         logger.info(
             f"The postprocessing method is {model.postprocess_name}",
@@ -595,7 +583,6 @@ def predict_ages_with_model(
     else:
         logger.info("There is no postprocessing necessary", indent_level=indent_level + 1)
 
-    # Batched prediction over the clock's feature matrix on the model's device
     matrix = adata.obsm[f"X_{model.metadata['clock_name']}"]
     starts = range(0, matrix.shape[0], batch_size)
     predictions = []
@@ -616,7 +603,6 @@ def predict_ages_with_model(
             predictions.append(prediction)
             if progress_callback is not None:
                 progress_callback(index + 1, len(starts))
-    # Concatenate all batch predictions
     predictions = torch.cat(predictions)
 
     return predictions
@@ -691,13 +677,10 @@ def add_pred_ages_and_clock_metadata_adata(
     {'species': 'Homo sapiens', 'data_type': 'methylation', 'citation': 'Horvath, S. (2013)'}
 
     """
-    # Convert from a torch tensor to a flat numpy array
     predicted_ages = predicted_ages.cpu().detach().numpy().flatten()
 
-    # Add predicted ages to adata.obs
     adata.obs[model.metadata["clock_name"]] = predicted_ages
 
-    # Add clock metadata to adata.uns
     adata.uns[f"{model.metadata['clock_name']}_metadata"] = deepcopy(model.metadata)
 
 
@@ -786,16 +769,13 @@ def cleanup_clock_memory(model=None, clock_name=None, dir=None, **kwargs) -> Non
     >>> # ... use model ...
     >>> cleanup_clock_memory(model=model, clock_name="horvath2013", dir="pyaging_data")
     """
-    # Delete the model if provided
     if model is not None:
         del model
 
-    # Delete any additional objects passed via kwargs
     for obj in kwargs.values():
         if obj is not None:
             del obj
 
-    # Delete the .pt file from disk if specified
     if clock_name is not None and dir is not None:
         weights_path = os.path.join(dir, f"{clock_name}.pt")
         try:
@@ -805,8 +785,6 @@ def cleanup_clock_memory(model=None, clock_name=None, dir=None, **kwargs) -> Non
             # Silently ignore file deletion errors to avoid disrupting tests
             pass
 
-    # Force garbage collection
     gc.collect()
 
-    # Clear PyTorch CUDA cache
     torch.cuda.empty_cache()

{pyaging-0.5.3 → pyaging-0.5.4}/src/pyaging/preprocess/_preprocess.py

@@ -71,14 +71,12 @@ def bigwig_to_df(bw_files: str | list[str], dir: str = "pyaging_data", verbose:
     if not PYBIGWIG_AVAILABLE:
         raise ImportError("pyBigWig is not installed. To use this function, please install it.")
 
-    # Ensure bws is a list
     if isinstance(bw_files, str):
         bw_files = [bw_files]
     if not bw_files:
         raise ValueError("bw_files must contain at least one bigWig file.")
 
     with live_step("processing bigWig files", verbose) as (step, pipeline_logger):
-        # Get genomic annotation data
         genes = load_ensembl_metadata(dir, pipeline_logger, indent_level=1)
 
         regions = list(zip(genes["chr"], genes["start"], genes["end"], strict=True))
@@ -86,7 +84,6 @@ def bigwig_to_df(bw_files: str | list[str], dir: str = "pyaging_data", verbose:
         for index, bw_file in enumerate(bw_files):
             step.update(f"processing {os.path.basename(bw_file)} ({index + 1}/{len(bw_files)})")
 
-            # Open bigWig file
             with open_bw(bw_file) as bw:
                 for gene_index, (chromosome, start, end) in enumerate(regions):
                     try:
@@ -171,7 +168,6 @@ def df_to_adata(
         raise TypeError("Input df must be a pandas DataFrame.")
 
     with live_step("building AnnData object", verbose) as (step, pipeline_logger):
-        # Split data and metadata
         if metadata_cols is None:
             metadata_cols = []
         if len(metadata_cols) > 0:
@@ -180,20 +176,15 @@ def df_to_adata(
         else:
             metadata = None
 
-        # Create an AnnData object
         adata = create_anndata_object(df, pipeline_logger)
 
-        # Add metadata
         add_metadata_to_anndata(adata, metadata, pipeline_logger)
 
-        # Log statistics
         missing_pct = log_data_statistics(adata.X, pipeline_logger)
 
-        # Impute missing values
         step.update(f"imputing missing values ({imputer_strategy})")
         impute_missing_values(adata, imputer_strategy, pipeline_logger)
 
-        # Add unstructured data
         if "X_imputed" in adata.layers:
             add_unstructured_data(adata, imputer_strategy, pipeline_logger)
 

{pyaging-0.5.3 → pyaging-0.5.4}/src/pyaging/utils/_hf.py

@@ -2,12 +2,11 @@
 
 Clock weights live in one repository per clock under the ``pyaging``
 organization (``pyaging/<clock_name>``); shared assets (example data, the
-aggregate metadata file) live in the legacy data repository, which is also
+aggregate metadata file) live in the shared data repository, which is also
 the fallback whenever a clock's own repository cannot be read.
 
 Set the ``PYAGING_DATA_REVISION`` environment variable to pin downloads to a
-specific revision of the data repositories (e.g. a release tag such as
-``v0.3.1``) for reproducibility. Defaults to ``main``, the live data release.
+specific existing revision of the data repositories for reproducibility. Defaults to ``main``, the live data release.
 """
 
 import os
@@ -120,7 +119,7 @@ def download_hf_file(
 def download_clock_weights(clock_name: str, dir: str = "pyaging_data", logger=None, indent_level: int = 1) -> str:
     """Download a clock's weight file, preferring its dedicated repository.
 
-    Each clock lives in ``pyaging/<clock_name>``; the legacy shared data
+    Each clock lives in ``pyaging/<clock_name>``; the shared data
     repository is the fallback when the per-clock repository cannot be read,
     including when it lacks the requested revision. Both use the same revision.
     The repo's ``config.json`` is fetched alongside the weights - it carries
@@ -138,7 +137,7 @@ def download_clock_weights(clock_name: str, dir: str = "pyaging_data", logger=No
     ):
         # The Hub answers 401 (not 404) for nonexistent repos when the caller
         # has no token, which maps to the authentication error - for anonymous
-        # users a typoed clock name must still reach the legacy fallback and
+        # users a typoed clock name must still reach the shared-repository fallback and
         # its clock-not-available message.
         return download_hf_file(filename, dir, logger, indent_level=indent_level)
     with suppress(PyAgingHubError):