pyaging 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of pyaging might be problematic. Click here for more details.

@@ -0,0 +1,909 @@
1
+ from typing import Tuple, List
2
+ import os
3
+ import torch
4
+ import numpy as np
5
+ import pandas as pd
6
+ import anndata
7
+ import ntpath
8
+ from urllib.request import urlretrieve
9
+ from ..models import *
10
+ from ..utils import *
11
+ from ..logger import LoggerManager, main_tqdm, silence_logger
12
+ from ._preprocessing import *
13
+ from ._postprocessing import *
14
+
15
+
16
+ @progress("Load clock")
17
+ def load_clock(clock_name: str, dir: str, logger, indent_level: int = 2) -> Tuple:
18
+ """
19
+ Loads the specified aging clock from a remote source and returns its components.
20
+
21
+ This function downloads the weights and configuration of a specified aging clock from a
22
+ remote server. It then loads and returns various components of the clock such as its
23
+ features, weight dictionary, and any preprocessing or postprocessing steps. This allows
24
+ users to instantiate and use the clock in their analyses.
25
+
26
+ Parameters
27
+ ----------
28
+ clock_name : str
29
+ The name of the aging clock to be loaded. This name is used to construct the URL
30
+ for downloading the clock's weights and configuration.
31
+
32
+ dir : str
33
+ The directory to deposit the downloaded file.
34
+
35
+ logger : Logger
36
+ A logger object used for logging information during the function execution.
37
+
38
+ indent_level : int, optional
39
+ The indentation level for the logger, by default 2. It controls the formatting
40
+ of the log messages.
41
+
42
+ Returns
43
+ -------
44
+ tuple
45
+ A tuple containing the following components of the clock:
46
+ - features: The features used by the clock.
47
+ - weight_dict: A dictionary of weights used in the clock's model.
48
+ - preprocessing: Any preprocessing steps required for the clock's input data.
49
+ - postprocessing: Any postprocessing steps applied to the clock's output.
50
+ - clock_dict: The complete clock dictionary as loaded from the file.
51
+
52
+ Notes
53
+ -----
54
+ The clock's weights and configuration are assumed to be stored in a .pt (PyTorch) file
55
+ on a remote server. The URL for the clock is constructed based on the clock's name.
56
+ The function uses the `download` utility to retrieve the file. If the clock or its
57
+ components are not found, the function may fail or return incomplete information.
58
+
59
+ The logger is used extensively for progress tracking and information logging, enhancing
60
+ transparency and user experience.
61
+
62
+ Examples
63
+ --------
64
+ >>> features, weight_dict, preprocessing, postprocessing, clock_dict = load_clock("clock1", "pyaging_data", logger)
65
+ >>> print(features)
66
+ ['feature1', 'feature2', ...]
67
+
68
+ """
69
+ url = f"https://pyaging.s3.amazonaws.com/clocks/weights/{clock_name}.pt"
70
+ download(url, dir, logger, indent_level=2)
71
+
72
+ # Define the path to the clock weights file
73
+ weights_path = os.path.join(dir, f"{clock_name}.pt")
74
+
75
+ # Load the clock dictionary from the file
76
+ clock_dict = torch.load(weights_path)
77
+
78
+ # Extract relevant information from the clock dictionary
79
+ features = clock_dict["features"]
80
+ weight_dict = clock_dict["weight_dict"]
81
+ preprocessing = clock_dict.get("preprocessing", None)
82
+ postprocessing = clock_dict.get("postprocessing", None)
83
+
84
+ return features, weight_dict, preprocessing, postprocessing, clock_dict
85
+
86
+
87
+ @progress("Check features in adata")
88
+ def check_features_in_adata(
89
+ adata: anndata.AnnData, features: List[str], logger, indent_level: int = 2
90
+ ) -> anndata.AnnData:
91
+ """
92
+ Verifies if all required features are present in an AnnData object and adds missing features.
93
+
94
+ This function checks an AnnData object (commonly used in single-cell analysis) to ensure
95
+ that it contains all the necessary features specified in the 'features' list. If any features
96
+ are missing, they are added to the AnnData object with a default value of 0. This is crucial
97
+ for downstream analyses where the presence of all specified features is assumed.
98
+
99
+ Parameters
100
+ ----------
101
+ adata : anndata.AnnData
102
+ The AnnData object to be checked. It is a commonly used data structure in single-cell
103
+ genomics containing high-dimensional data.
104
+
105
+ features : list
106
+ A list of features (e.g., gene names or other identifiers) that are expected to be
107
+ present in the 'adata'.
108
+
109
+ logger : Logger
110
+ A logger object used for logging information about the process, such as the number
111
+ of missing features.
112
+
113
+ indent_level : int, optional
114
+ The indentation level for the logger, by default 2. It controls the formatting
115
+ of the log messages.
116
+
117
+ Returns
118
+ -------
119
+ anndata.AnnData
120
+ The updated AnnData object, which includes any missing features added with a default
121
+ value of 0.
122
+
123
+ Notes
124
+ -----
125
+ This function is particularly useful in preprocessing steps where the consistency of
126
+ data structure across different datasets is crucial. The function modifies the AnnData
127
+ object in place if there are missing features and logs detailed information about
128
+ these modifications.
129
+
130
+ The added features are initialized with zeros. This approach, while providing completeness,
131
+ may introduce biases if not accounted for in downstream analyses.
132
+
133
+ Examples
134
+ --------
135
+ >>> updated_adata = check_features_in_adata(adata, ['gene1', 'gene2'], logger)
136
+ >>> updated_adata.var_names
137
+ Index(['gene1', 'gene2', ...], dtype='object')
138
+
139
+ """
140
+ # Identify missing features
141
+ missing_features = [
142
+ feature for feature in features if feature not in adata.var_names
143
+ ]
144
+
145
+ # Calculate the percentage of missing features
146
+ total_features = len(features)
147
+ num_missing_features = len(missing_features)
148
+ percent_missing = (
149
+ (num_missing_features / total_features) * 100 if total_features > 0 else 0
150
+ )
151
+
152
+ # Log and add missing features if any
153
+ if missing_features:
154
+ logger.warning(
155
+ f"{num_missing_features} out of {total_features} features "
156
+ f"({percent_missing:.2f}%) are missing and will be "
157
+ f"added with default value 0: {missing_features[:np.min([3, num_missing_features])]}, etc.",
158
+ indent_level=3,
159
+ )
160
+
161
+ # Create an empty AnnData object for missing features
162
+ adata_empty = anndata.AnnData(
163
+ np.zeros((adata.n_obs, num_missing_features)),
164
+ obs=adata.obs,
165
+ var=pd.DataFrame(index=missing_features),
166
+ )
167
+
168
+ # Concatenate original adata with the empty adata
169
+ adata = anndata.concat([adata, adata_empty], axis=1)
170
+ logger.info(
171
+ f"Expanded adata with {num_missing_features} missing features.",
172
+ indent_level=3,
173
+ )
174
+ else:
175
+ logger.info("All features are present in adata.var_names.", indent_level=2)
176
+
177
+ return adata
178
+
179
+
180
+ @progress("Initialize model")
181
+ def initialize_model(
182
+ clock_name: str,
183
+ features: List[str],
184
+ weight_dict: dict,
185
+ logger,
186
+ indent_level: int = 2,
187
+ ) -> torch.nn.Module:
188
+ """
189
+ Initialize and configure a predictive model based on the specified aging clock.
190
+
191
+ This function selects and initializes a machine learning model tailored to a particular aging clock,
192
+ indicated by `clock_name`. It loads the model weights from `weight_dict` and prepares the model
193
+ for inference (evaluation mode). Different types of clocks require different models, and this function
194
+ handles the instantiation and configuration of these models based on the clock type.
195
+
196
+ Parameters
197
+ ----------
198
+ clock_name : str
199
+ The name of the aging clock for which the model is to be initialized. This name determines
200
+ the type of model to be used.
201
+
202
+ features : list
203
+ A list of feature names that the model will use for making predictions. The length of this
204
+ list is used to configure the input dimension of the model.
205
+
206
+ weight_dict : dict
207
+ A dictionary containing the pre-trained weights of the model. These weights are loaded into
208
+ the model for making predictions.
209
+
210
+ logger : Logger
211
+ A logger object for logging the progress and any information or warnings during the
212
+ initialization process.
213
+
214
+ indent_level : int, optional
215
+ The indentation level for the logger, by default 2. It controls the formatting of the log
216
+ messages.
217
+
218
+ Returns
219
+ -------
220
+ model : torch.nn.Module
221
+ The initialized and configured PyTorch model ready for making predictions.
222
+
223
+ Raises
224
+ ------
225
+ ValueError
226
+ If the provided `clock_name` is not supported or recognized.
227
+
228
+ Notes
229
+ -----
230
+ The function currently supports a range of models including linear models, principal component
231
+ (PC) based models, and specific models for complex clocks like `AltumAge` and `PCGrimAge`.
232
+ It is crucial that the `weight_dict` matches the structure expected by the model corresponding
233
+ to the `clock_name`.
234
+
235
+ The function assumes the availability of a pre-defined set of model classes like `LinearModel`,
236
+ `PCLinearModel`, `PCGrimAge`, `AltumAge`, etc., which should be defined elsewhere in the codebase.
237
+
238
+ Examples
239
+ --------
240
+ >>> model = initialize_model('horvath2013', features, weight_dict, logger)
241
+ >>> print(type(model))
242
+ <class 'torch.nn.modules.linear.LinearModel'>
243
+
244
+ """
245
+ # Model selection based on clock name
246
+ if clock_name in [
247
+ "horvath2013",
248
+ "skinandblood",
249
+ "hannum",
250
+ "phenoage",
251
+ "dnamtl",
252
+ "dunedinpace",
253
+ "replitali",
254
+ "pedbe",
255
+ "mammalian1",
256
+ "mammalian2",
257
+ "mammalian3",
258
+ "mammalianlifespan",
259
+ "ocampoatac1",
260
+ "ocampoatac2",
261
+ "bitage",
262
+ ]:
263
+ model = LinearModel(len(features))
264
+ model.load_state_dict(weight_dict)
265
+ model.eval()
266
+ return model
267
+ elif clock_name in [
268
+ "pchorvath2013",
269
+ "pcskinandblood",
270
+ "pchannum",
271
+ "pcphenoage",
272
+ "pcdnamtl",
273
+ ]:
274
+ model = PCLinearModel(len(features), pc_dim=weight_dict["rotation"].shape[1])
275
+ model.load_state_dict(weight_dict)
276
+ model.eval()
277
+ return model
278
+ elif clock_name == "pcgrimage":
279
+ model = PCGrimAge(
280
+ sum(["cg" in feature for feature in features]),
281
+ pc_dim=weight_dict["rotation"].shape[1],
282
+ comp_dims=[
283
+ weight_dict[f"step1_layers.{i}.weight"].shape[1]
284
+ for i in range(weight_dict["step2.weight"].shape[1] - 2)
285
+ ],
286
+ )
287
+ model.load_state_dict(weight_dict)
288
+ model.eval()
289
+ return model
290
+ elif clock_name == "altumage":
291
+ model = AltumAge()
292
+ model.load_state_dict(weight_dict)
293
+ model.eval()
294
+ return model
295
+ elif clock_name in [
296
+ "h3k4me3",
297
+ "h3k4me1",
298
+ "h3k9me3",
299
+ "h3k9ac",
300
+ "h3k27me3",
301
+ "h3k27ac",
302
+ "h3k36me3",
303
+ "panhistone",
304
+ ]:
305
+ model = PCARDModel(len(features), pc_dim=weight_dict["rotation"].shape[1])
306
+ model.load_state_dict(weight_dict)
307
+ model.eval()
308
+ return model
309
+ else:
310
+ raise ValueError(f"Clock '{clock_name}' is not supported.")
311
+
312
+
313
+ @progress("Preprocess data")
314
+ def preprocess_data(
315
+ preprocessing: str,
316
+ data: torch.Tensor,
317
+ clock_dict: dict,
318
+ logger,
319
+ indent_level: int = 2,
320
+ ) -> torch.Tensor:
321
+ """
322
+ Preprocess the input data based on the specified method and the clock dictionary.
323
+
324
+ This function applies a specified preprocessing method to the input data, which is necessary
325
+ for aligning the data format with the requirements of the aging clock models. The function
326
+ supports multiple preprocessing methods, including scaling, log transformation, binarization, etc.
327
+ The specific preprocessing method to be used is indicated by the `preprocessing` parameter, and
328
+ any additional parameters required for preprocessing are obtained from `clock_dict`.
329
+
330
+ Parameters
331
+ ----------
332
+ preprocessing : str
333
+ The name of the preprocessing method to apply. Supported methods include 'scale', 'log1p',
334
+ 'binarize', etc.
335
+
336
+ data : torch.Tensor or similar
337
+ The input data to be preprocessed. It should be in a format compatible with the specified
338
+ preprocessing method.
339
+
340
+ clock_dict : dict
341
+ A dictionary containing clock-specific information, which may include helper functions or
342
+ parameters needed for preprocessing.
343
+
344
+ logger : Logger
345
+ A logger object for logging the progress and any information or warnings during preprocessing.
346
+
347
+ indent_level : int, optional
348
+ The indentation level for the logger, by default 2. It controls the formatting of the log
349
+ messages.
350
+
351
+ Returns
352
+ -------
353
+ processed_data : torch.Tensor or similar
354
+ The preprocessed data, ready to be input into the aging clock models.
355
+
356
+ Notes
357
+ -----
358
+ The function assumes that the input `data` is in a format compatible with the preprocessing methods.
359
+ For instance, 'scale' may expect a numeric tensor, while 'log1p' requires non-negative values.
360
+ Users must ensure that the input data is appropriate for the selected preprocessing method.
361
+
362
+ The `clock_dict` may include specific parameters or helper functions like `preprocessing_helper`
363
+ for the 'scale' method, which should be defined elsewhere in the codebase.
364
+
365
+ Examples
366
+ --------
367
+ >>> processed_data = preprocess_data("scale", data, clock_dict, logger)
368
+ >>> print(processed_data.shape)
369
+ torch.Size([...])
370
+
371
+ """
372
+ logger.info(f"Preprocessing data with function {preprocessing}", indent_level=3)
373
+ # Apply specified preprocessing method
374
+ if preprocessing == "scale":
375
+ data = scale(data, clock_dict["preprocessing_helper"])
376
+ elif preprocessing == "log1p":
377
+ data = torch.log1p(data)
378
+ elif preprocessing == "binarize":
379
+ data = binarize(data)
380
+ return data
381
+
382
+
383
+ @progress("Postprocess data")
384
+ def postprocess_data(
385
+ postprocessing: str,
386
+ data: np.ndarray,
387
+ clock_dict: dict,
388
+ logger,
389
+ indent_level: int = 2,
390
+ ) -> np.ndarray:
391
+ """
392
+ Apply postprocessing to the data based on the specified method.
393
+
394
+ This function is designed to apply a specific postprocessing method to data, typically after
395
+ it has been processed by a machine learning model. The type of postprocessing is determined
396
+ by the `postprocessing` parameter. The function supports several methods, including various
397
+ forms of anti-log transformations, which are applied using a vectorized approach for efficiency.
398
+
399
+ Parameters
400
+ ----------
401
+ postprocessing : str
402
+ The name of the postprocessing method to be applied. Supported methods include
403
+ 'anti_log_linear', 'anti_logp2', 'anti_log', etc.
404
+
405
+ data : array-like
406
+ The data to be postprocessed. It should be compatible with the specified postprocessing method.
407
+
408
+ clock_dict : dict
409
+ A dictionary containing any additional information or parameters required for postprocessing.
410
+ For example, parameters for scaling factors or offsets used in anti-log transformations.
411
+
412
+ logger : Logger
413
+ A logger object for logging the progress, information, or warnings during postprocessing.
414
+
415
+ indent_level : int, optional
416
+ The indentation level for logging messages, by default 2.
417
+
418
+ Returns
419
+ -------
420
+ postprocessed_data : array-like
421
+ The data after applying the specified postprocessing method.
422
+
423
+ Notes
424
+ -----
425
+ The function relies on numpy's vectorization capabilities for efficient computation. The
426
+ postprocessing functions, like `anti_log_linear`, need to be defined elsewhere in the codebase.
427
+
428
+ The choice of postprocessing method should be consistent with the preprocessing method and the
429
+ nature of the data and model predictions.
430
+
431
+ Examples
432
+ --------
433
+ >>> postprocessed_data = postprocess_data("anti_log_linear", data, clock_dict, logger)
434
+ >>> print(postprocessed_data.shape)
435
+ (num_samples, num_features)
436
+
437
+ """
438
+ logger.info(f"Postprocessing data with function {postprocessing}", indent_level=3)
439
+ # Apply specified postprocessing method using vectorization
440
+ if postprocessing == "anti_log_linear":
441
+ vectorized_function = np.vectorize(anti_log_linear)
442
+ data = vectorized_function(data)
443
+ elif postprocessing == "anti_logp2":
444
+ vectorized_function = np.vectorize(anti_logp2)
445
+ data = vectorized_function(data)
446
+ elif postprocessing == "anti_log":
447
+ vectorized_function = np.vectorize(anti_log)
448
+ data = vectorized_function(data)
449
+ elif postprocessing == "anti_log_log":
450
+ vectorized_function = np.vectorize(anti_log_log)
451
+ data = vectorized_function(data)
452
+ return data
453
+
454
+
455
+ @progress("Predict ages with model")
456
+ def predict_ages_with_model(
457
+ model: torch.nn.Module, data: torch.Tensor, logger, indent_level: int = 2
458
+ ) -> torch.Tensor:
459
+ """
460
+ Predict biological ages using a trained model and input data.
461
+
462
+ This function takes a machine learning model and input data, and returns predictions made by the model.
463
+ It's primarily used for estimating biological ages based on various biological markers. The function
464
+ assumes that the model is already trained and the data is preprocessed according to the model's requirements.
465
+
466
+ Parameters
467
+ ----------
468
+ model : torch.nn.Module
469
+ A pre-trained machine learning model that can make predictions.
470
+
471
+ data : array-like
472
+ The input data on which age predictions need to be made. This should be in the format expected
473
+ by the `model` (e.g., a numpy array, pandas DataFrame, or PyTorch tensor).
474
+
475
+ logger : Logger
476
+ A logger object for logging the progress or any relevant information during the prediction process.
477
+
478
+ indent_level : int, optional
479
+ The indentation level for logging messages, by default 2.
480
+
481
+ Returns
482
+ -------
483
+ predictions : torch.Tensor
484
+ An array of predicted ages or biological markers, as returned by the model.
485
+
486
+ Notes
487
+ -----
488
+ Ensure that the data is preprocessed (e.g., scaled, normalized) as required by the model before
489
+ passing it to this function. The model should be in evaluation mode if it's a type that has different
490
+ behavior during training and inference (e.g., PyTorch models).
491
+
492
+ The exact nature of the predictions (e.g., age, biological markers) depends on the model being used.
493
+
494
+ Examples
495
+ --------
496
+ >>> model = load_pretrained_model()
497
+ >>> predictions = predict_ages_with_model(model, data, logger)
498
+ >>> print(predictions[:5])
499
+ [34.5, 29.3, 47.8, 50.1, 42.6]
500
+
501
+ """
502
+ return model(data)
503
+
504
+
505
+ @progress("Convert tensor to numpy array")
506
+ def convert_tensor_to_numpy_array(
507
+ tensor: torch.Tensor, logger, indent_level: int = 2
508
+ ) -> np.ndarray:
509
+ """
510
+ Convert a PyTorch tensor to a flattened NumPy array.
511
+
512
+ This utility function takes a PyTorch tensor and converts it into a 1D NumPy array. It is useful in scenarios
513
+ where PyTorch tensors need to be processed or analyzed using NumPy-based tools or functions. The function ensures
514
+ that the tensor is detached from the current computation graph (if applicable) and then flattens it to a 1D array.
515
+
516
+ Parameters
517
+ ----------
518
+ tensor : torch.Tensor
519
+ The PyTorch tensor to be converted. This can be a tensor of any shape.
520
+
521
+ logger : Logger
522
+ A logger object for logging the progress or any relevant information during the conversion process.
523
+
524
+ indent_level : int, optional
525
+ The indentation level for logging messages, by default 2.
526
+
527
+ Returns
528
+ -------
529
+ numpy_array : ndarray
530
+ A 1D NumPy array equivalent to the input tensor.
531
+
532
+ Notes
533
+ -----
534
+ This function detaches the tensor from the computation graph, so it should be used with caution if the tensor
535
+ is part of a PyTorch computational graph, such as when dealing with gradients in training neural networks.
536
+
537
+ The flattening to a 1D array may lose the original shape information of the tensor, which should be considered
538
+ if the shape is important for further processing.
539
+
540
+ Examples
541
+ --------
542
+ >>> tensor = torch.tensor([[1, 2], [3, 4]])
543
+ >>> numpy_array = convert_tensor_to_numpy_array(tensor, logger)
544
+ >>> numpy_array
545
+ array([1, 2, 3, 4])
546
+
547
+ """
548
+ return tensor.detach().numpy().flatten()
549
+
550
+
551
+ @progress("Convert adata.X to torch.tensor and filter features")
552
+ def convert_adata_to_tensor_and_filter_features(
553
+ adata: anndata.AnnData, features: List[str], logger, indent_level: int = 2
554
+ ) -> torch.Tensor:
555
+ """
556
+ Convert an AnnData object's data matrix to a PyTorch tensor and filter features.
557
+
558
+ This function processes an AnnData object, which is commonly used in bioinformatics for storing large
559
+ gene expression datasets. It extracts the data matrix corresponding to a specified set of features (genes or
560
+ other genomic elements) and converts this subset into a PyTorch tensor. This tensor can then be used for
561
+ further analysis or model input in PyTorch-based workflows.
562
+
563
+ Parameters
564
+ ----------
565
+ adata : anndata.AnnData
566
+ The AnnData object containing the dataset. Its `.X` attribute is expected to be a matrix where rows
567
+ correspond to samples and columns correspond to features.
568
+
569
+ features : list of str
570
+ A list of feature names to be included in the tensor. Only these features from the AnnData object will
571
+ be extracted and converted.
572
+
573
+ logger : Logger
574
+ A logger object for logging progress or relevant information during the conversion process.
575
+
576
+ indent_level : int, optional
577
+ The indentation level for logging messages, by default 2.
578
+
579
+ Returns
580
+ -------
581
+ tensor : torch.Tensor
582
+ A PyTorch tensor containing the filtered data from the AnnData object, with dtype set to float32.
583
+
584
+ Notes
585
+ -----
586
+ The AnnData object is a central data structure in many bioinformatics pipelines. It efficiently handles
587
+ large datasets typical in genomics and transcriptomics. This function facilitates the integration of
588
+ AnnData-based workflows with PyTorch models and functions.
589
+
590
+ The dtype of the returned tensor is set to float32, which is a common choice for numerical operations in
591
+ PyTorch, especially in the context of machine learning models.
592
+
593
+ Examples
594
+ --------
595
+ >>> adata = anndata.AnnData(np.random.rand(5, 10))
596
+ >>> features = ['gene1', 'gene2', 'gene3']
597
+ >>> tensor = convert_adata_to_tensor_and_filter_features(adata, features, logger)
598
+ >>> tensor.shape
599
+ torch.Size([5, 3])
600
+
601
+ """
602
+ return torch.tensor(adata[:, features].X, dtype=torch.float32)
603
+
604
+
605
+ @progress("Add predicted ages to adata")
606
+ def add_pred_ages_adata(
607
+ adata: anndata.AnnData,
608
+ predicted_ages: np.ndarray,
609
+ clock_name: str,
610
+ logger,
611
+ indent_level: int = 2,
612
+ ) -> None:
613
+ """
614
+ Add predicted ages to an AnnData object as a new column in the observation (obs) attribute.
615
+
616
+ This function appends the predicted ages, obtained from a biological aging clock or similar model, to
617
+ the AnnData object's `obs` attribute. The predicted ages are added as a new column, named after the
618
+ clock used to generate these predictions. This allows for easy integration and comparison of age
619
+ predictions within the bioinformatics data analysis workflows.
620
+
621
+ Parameters
622
+ ----------
623
+ adata : anndata.AnnData
624
+ The AnnData object to which the predicted ages will be added. It's a data structure for handling
625
+ large-scale biological data, like gene expression matrices, commonly used in bioinformatics.
626
+
627
+ predicted_ages : numpy.ndarray or list
628
+ An array or list of predicted ages corresponding to the samples in the AnnData object. The length
629
+ of this array should match the number of samples in `adata`.
630
+
631
+ clock_name : str
632
+ The name of the biological aging clock used to generate the predicted ages. This name will be used
633
+ as the column name in `adata.obs`.
634
+
635
+ logger : Logger
636
+ A logger object for logging the progress or relevant information during the operation.
637
+
638
+ indent_level : int, optional
639
+ The indentation level for logging messages, by default 2.
640
+
641
+ Returns
642
+ -------
643
+ None
644
+ This function modifies the AnnData object in-place and does not return any value.
645
+
646
+ Notes
647
+ -----
648
+ It is essential to ensure that the length of `predicted_ages` matches the number of samples in the
649
+ `adata` object. Mismatch in lengths will lead to errors or misaligned data.
650
+
651
+ This function is part of a pipeline that integrates biological aging clock predictions with the
652
+ standard data structures used in bioinformatics, facilitating downstream analyses like visualization
653
+ or statistical testing.
654
+
655
+ Examples
656
+ --------
657
+ >>> adata = anndata.AnnData(np.random.rand(5, 10))
658
+ >>> predicted_ages = [25, 30, 35, 40, 45]
659
+ >>> add_pred_ages_adata(adata, predicted_ages, 'horvath2013', logger)
660
+ >>> adata.obs['horvath2013']
661
+ 0 25
662
+ 1 30
663
+ 2 35
664
+ 3 40
665
+ 4 45
666
+ Name: horvath2013, dtype: int64
667
+
668
+ """
669
+ adata.obs[clock_name] = predicted_ages
670
+
671
+
672
+ @progress("Add clock metadata to adata.uns")
673
+ def add_clock_metadata_adata(
674
+ adata: anndata.AnnData,
675
+ clock_name: str,
676
+ all_clock_metadata: dict,
677
+ logger,
678
+ indent_level: int = 2,
679
+ ) -> None:
680
+ """
681
+ Add specific clock metadata to the `uns` attribute of an AnnData object.
682
+
683
+ This function enriches an AnnData object with metadata related to a specific biological aging clock.
684
+ The metadata is stored under a key named after the clock in the AnnData's `uns` attribute, which is
685
+ a dictionary-like structure used for storing unstructured data. This addition aids in keeping track
686
+ of the clock-specific information, such as model parameters or references, which can be crucial for
687
+ subsequent analyses and reproducibility.
688
+
689
+ Parameters
690
+ ----------
691
+ adata : anndata.AnnData
692
+ The AnnData object to which the clock metadata will be added. AnnData is widely used in
693
+ bioinformatics for storing large-scale biological data like gene expression matrices.
694
+
695
+ clock_name : str
696
+ The name of the biological aging clock. The metadata associated with this clock will be added to
697
+ the AnnData object.
698
+
699
+ all_clock_metadata : dict
700
+ A dictionary containing metadata for all available clocks. The function will extract metadata for
701
+ the specified clock from this dictionary.
702
+
703
+ logger : Logger
704
+ A logger object for logging the progress or relevant information during the operation.
705
+
706
+ indent_level : int, optional
707
+ The indentation level for logging messages, by default 2.
708
+
709
+ Returns
710
+ -------
711
+ None
712
+ This function modifies the AnnData object in-place and does not return any value.
713
+
714
+ Notes
715
+ -----
716
+ The `uns` attribute in AnnData is a flexible slot for storing miscellaneous data. Adding clock metadata
717
+ here ensures that all relevant information about the biological aging clocks used in the analysis is
718
+ preserved alongside the dataset.
719
+
720
+ It is important to ensure that the `clock_name` exists within the `all_clock_metadata` dictionary to
721
+ avoid key errors.
722
+
723
+ Examples
724
+ --------
725
+ >>> adata = anndata.AnnData(np.random.rand(5, 10))
726
+ >>> all_clock_metadata = {'horvath2013': {'description': 'Horvath’s 2013 epigenetic clock', 'reference': 'Horvath, S. (2013)'}}
727
+ >>> add_clock_metadata_adata(adata, 'horvath2013', all_clock_metadata, logger)
728
+ >>> adata.uns['horvath2013_metadata']
729
+ {'description': 'Horvath’s 2013 epigenetic clock', 'reference': 'Horvath, S. (2013)'}
730
+
731
+ """
732
+ adata.uns[f"{clock_name}_metadata"] = all_clock_metadata[clock_name]
733
+
734
+
735
+ @progress("Set PyTorch device")
736
+ def set_torch_device(logger, indent_level: int = 1) -> None:
737
+ """
738
+ Set and return the PyTorch device based on the availability of CUDA.
739
+
740
+ This function checks if CUDA is available in the system and accordingly sets the PyTorch device to
741
+ either 'cuda' or 'cpu'. If CUDA is available, it utilizes GPU acceleration for PyTorch operations,
742
+ significantly enhancing computation speed for large datasets. The chosen device is logged for
743
+ user reference.
744
+
745
+ Parameters
746
+ ----------
747
+ logger : Logger
748
+ A logger object for logging the selected device.
749
+
750
+ indent_level : int, optional
751
+ The indentation level for logging messages, by default 1.
752
+
753
+ Returns
754
+ -------
755
+ torch.device
756
+ The PyTorch device object set to 'cuda' if CUDA is available, or 'cpu' otherwise.
757
+
758
+ Notes
759
+ -----
760
+ The function automatically detects the availability of CUDA and makes a decision without user input.
761
+ This makes it convenient for deploying code on different machines without the need for manual
762
+ configuration.
763
+
764
+ It is important to use the returned device for all PyTorch operations to ensure that they are
765
+ executed on the correct hardware (CPU or GPU).
766
+
767
+ Examples
768
+ --------
769
+ >>> logger = pyaging.logger.LoggerManager.gen_logger("example")
770
+ >>> device = set_torch_device(logger)
771
+ >>> print(device)
772
+ device(type='cuda') # or device(type='cpu') if CUDA is not available
773
+
774
+ """
775
+ device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
776
+ logger.info(f"Using device: {device}", indent_level=2)
777
+ return device
778
+
779
+
780
+ def predict_age(
781
+ adata: anndata.AnnData,
782
+ clock_names: str = "horvath2013",
783
+ dir: str = "pyaging_data",
784
+ verbose: bool = True,
785
+ ) -> anndata.AnnData:
786
+ """
787
+ Predicts biological age using specified aging clocks.
788
+
789
+ This function takes an AnnData object and applies one or more specified aging
790
+ clock models to predict the biological age of the samples. It handles the entire pipeline from data
791
+ preprocessing, model loading, prediction, to postprocessing. It also enriches the input AnnData
792
+ object with the predicted ages and relevant clock metadata.
793
+
794
+ Parameters
795
+ ----------
796
+ adata : AnnData
797
+ An AnnData object. The object should have .X attribute for the
798
+ data matrix and .var_names for feature names.
799
+
800
+ clock_names : str or list of str, optional
801
+ Names of the aging clocks to be applied. It can be a single clock name as a string or a list
802
+ of clock names, by default "horvath2013".
803
+
804
+ dir : str
805
+ The directory to deposit the downloaded file. Defaults to "pyaging_data".
806
+
807
+ verbose: bool
808
+ Whether to log the output to console with the logger. Defaults to True.
809
+
810
+ Returns
811
+ -------
812
+ AnnData
813
+ The input AnnData object enriched with the predicted ages and clock metadata in the .obs and
814
+ .uns attributes, respectively.
815
+
816
+ Notes
817
+ -----
818
+ The function is designed to be flexible and can handle both single and multiple clock predictions.
819
+ The predicted ages are appended to the .obs attribute of the AnnData object with the clock name as
820
+ the key. The metadata of each clock used in the prediction is stored in the .uns attribute.
821
+
822
+ It is important that the input AnnData object's .X attribute contains data
823
+ suitable for age prediction.
824
+
825
+ The function automatically handles the transfer of data and models to the appropriate compute
826
+ device (CPU or GPU) based on system configuration.
827
+
828
+ Examples
829
+ --------
830
+ >>> adata = anndata.read_h5ad("sample_data.h5ad")
831
+ >>> adata = predict_age(adata, clock_names=["horvath2013", "hannum"])
832
+ >>> adata.obs["horvath2013"] # Access predicted ages by clock name
833
+
834
+ """
835
+ logger = LoggerManager.gen_logger("predict_age")
836
+ if not verbose:
837
+ silence_logger("predict_age")
838
+ logger.first_info("Starting predict_age function")
839
+
840
+ # Ensure clock_names is a list
841
+ if isinstance(clock_names, str):
842
+ clock_names = [clock_names]
843
+
844
+ # Set device for PyTorch operations
845
+ device = set_torch_device(logger)
846
+
847
+ for clock_name in clock_names:
848
+ logger.info(f"Processing clock: {clock_name}", indent_level=1)
849
+
850
+ # Load and prepare the clock
851
+ clock_name = clock_name.lower()
852
+ features, weight_dict, preprocessing, postprocessing, clock_dict = load_clock(
853
+ clock_name, dir, logger, indent_level=2
854
+ )
855
+
856
+ # Check and update adata for missing features
857
+ adata_expanded = check_features_in_adata(
858
+ adata, features, logger, indent_level=2
859
+ )
860
+
861
+ # Convert adata to tensor and filter features
862
+ x_tensor = convert_adata_to_tensor_and_filter_features(
863
+ adata_expanded, features, logger, indent_level=2
864
+ )
865
+
866
+ # Apply preprocessing if specified
867
+ if preprocessing:
868
+ x_tensor = preprocess_data(
869
+ preprocessing, x_tensor, clock_dict, logger, indent_level=2
870
+ )
871
+
872
+ # Move tensor to the appropriate device
873
+ x_tensor = x_tensor.to(device)
874
+
875
+ # Initialize and configure the model
876
+ clock_model = initialize_model(
877
+ clock_name, features, weight_dict, logger, indent_level=2
878
+ )
879
+ clock_model = clock_model.to(device) # Move model to the appropriate device
880
+
881
+ # Perform age prediction using the model
882
+ predicted_ages_tensor = predict_ages_with_model(
883
+ clock_model, x_tensor, logger, indent_level=2
884
+ )
885
+
886
+ # Convert adata tensor to numpy array
887
+ predicted_ages = convert_tensor_to_numpy_array(
888
+ predicted_ages_tensor.cpu(), logger, indent_level=2
889
+ )
890
+
891
+ # Apply postprocessing if specified
892
+ if postprocessing:
893
+ predicted_ages = postprocess_data(
894
+ postprocessing, predicted_ages, clock_dict, logger, indent_level=2
895
+ )
896
+
897
+ # Add predicted ages to adata
898
+ add_pred_ages_adata(adata, predicted_ages, clock_name, logger, indent_level=2)
899
+
900
+ # Load all clocks metadata
901
+ all_clock_metadata = load_clock_metadata(dir, logger, indent_level=2)
902
+
903
+ # Add clock metadata to adata object
904
+ add_clock_metadata_adata(
905
+ adata, clock_name, all_clock_metadata, logger, indent_level=2
906
+ )
907
+
908
+ logger.done()
909
+ return adata