Utils

Please note that most functions are helper functions and are not meant to be used directly.

pyaging.utils._utils

pyaging.utils._utils.cite_clock(clock_name, dir='pyaging_data')

Retrieves and logs the citation information for a specified aging clock.

This function searches the metadata for aging clocks to find and log the citation details of a specified clock. If the clock is found but no citation information is available, it logs a warning indicating the absence of citation data. If the clock is not found in the metadata, it logs a warning that the clock is unavailable.

Parameters:

clock_name str

The name of the aging clock for which citation information is to be retrieved. The function is case-insensitive to the clock name.

dir str

The directory to deposit the downloaded file. Defaults to ‘pyaging_data’.

Return type:

None

Returns:

None The function does not return a value but logs the citation details or warnings.

Notes

The function calls load_clock_metadata to load the entire metadata of aging clocks and then searches for the specified clock. It logs the progress of the search and the results. The LoggerManager is used for generating loggers for logging purposes.

The function assumes that the metadata for each clock may contain a ‘citation’ field. If this field is missing, the function will indicate that no citation information is available.

Examples

>>> cite_clock("ClockX")
Citation for clockx:
Smith, A. B., et al. (2020). "A New Aging Clock Model." Aging Research, vol. 30, pp. 100-110.

or, if citation data is not available,

>>> cite_clock("ClockY")
Citation not found in clocky

or, if the clock is not in the metadata,

>>> cite_clock("UnknownClock")
UnknownClock is not currently available in pyaging

pyaging.utils._utils.download(url, dir, logger, indent_level=1)

Downloads a file from a specified URL to a local directory.

This function checks if the file specified by the URL already exists in the local ‘pyaging_data’ directory. If the file is not present or it is not the latest, it downloads the file from the URL and saves it in this directory. The function logs the progress of the download, including whether the file is found locally or needs to be downloaded.

Parameters:

url str

The URL of the file to be downloaded.

dir str

The directory to deposit the downloaded file.

logger object

Logger object for logging messages at various stages of the download process.

indent_level int, optional

The level of indentation for logging messages, by default 1.

Raises:

IOError – If the download fails or the file cannot be saved to the local directory.

Notes

The function assumes the presence of a folder named ‘pyaging_data’ in the current directory, creating it if it doesn’t exist. It uses Python’s urlretrieve function from the urllib module for downloading the file. The function is decorated with @progress, which adds start and end log messages for the download process.

Examples

>>> logger = Logger()
>>> download("https://example.com/datafile.zip", "pyaging_data", logger)
Data found in pyaging_data/datafile.zip
or
Downloading data to pyaging_data/datafile.zip

pyaging.utils._utils.find_clock_by_doi(search_doi, dir='pyaging_data')

Searches for aging clocks in the metadata by a specified DOI (Digital Object Identifier).

This function retrieves the metadata for all aging clocks and searches for clocks that match the given DOI. It uses a Logger object for logging the progress and results of the search. The function outputs the names of clocks with the matching DOI, or a warning message if no matches are found.

Parameters:

search_doi str

The DOI to search for in the aging clocks’ metadata.

dir str

The directory to deposit the downloaded file. Defaults to ‘pyaging_data’.

Return type:

None

Returns:

None The function does not return a value but logs the search results.

Notes

The function internally calls load_clock_metadata to load the metadata of all available aging clocks. It then iterates over this metadata to find matches. The logging includes starting and ending messages for the search process, and a summary of the findings.

The function assumes the existence of a LoggerManager for generating loggers and uses main_tqdm for progress tracking in the loop. It’s important to ensure that the metadata contains the ‘doi’ field for each clock for the search to be effective.

Examples

>>> find_clock_by_doi("10.1155/2020/123456")
Clocks with DOI 10.1155/2020/123456: Clock1, Clock2

or, if no match is found,

>>> find_clock_by_doi("10.1000/xyz123")
No files found with DOI 10.1000/xyz123

pyaging.utils._utils.get_clock_metadata(clock_name, dir='pyaging_data')

Retrieves and logs the metadata of a specified aging clock.

This function accesses the metadata for a given aging clock and logs detailed information about it, such as the data type, model, and citation. It is designed to help users quickly understand the characteristics and details of a specific clock in the pyaging package. The function uses a logger to ensure that the output is structured and easily readable.

Parameters:

clock_name str

The name of the aging clock whose metadata is to be retrieved. The name is case-insensitive.

dir str

The directory to deposit the downloaded file. Defaults to ‘pyaging_data’.

Return type:

None

Returns:

None The function does not return a value but logs the metadata of the specified clock.

Notes

The function first calls load_clock_metadata to load all clock metadata. It then extracts the metadata for the specified clock and logs each piece of information. The logger’s progress methods (start_progress and finish_progress) are used to indicate the start and end of the retrieval process, enhancing user understanding of the operation.

This function assumes that the specified clock name exists in the metadata. If the clock name is not found, an error may occur.

Examples

>>> get_clock_metadata("clock1")
name: Clock1
data_type: methylation
species: Homo sapiens
...

pyaging.utils._utils.is_newer_than_target(url, target_date_str)

Check if the ‘Last-Modified’ date of the metadata of a url is newer than a specific target date.

Parameters:

url str

The url of interest from S3. The header must include the ‘Last-Modified’ key with its value in the format: ‘Day, DD Mon YYYY HH:MM:SS GMT’.

target_date_str str

The target date as a string in the format ‘YYYY-MM-DD’.

Returns:

bool True if the ‘Last-Modified’ date is newer than the target date, False otherwise.

Notes

The function parses the ‘Last-Modified’ date from the provided metadata and compares it against a predefined target date (January 21st, 2024). The comparison accounts for the UTC timezone.

Example

metadata = {‘Last-Modified’: ‘Sun, 21 Jan 2024 09:54:49 GMT’} result = is_newer_than_target(metadata) # result will be True if ‘Last-Modified’ is after Jan 21st, 2024, False otherwise.

pyaging.utils._utils.load_clock_metadata(dir, logger, indent_level=2)

Loads the clock metadata from a specified source.

This function checks if the metadata file exists locally in the specified directory. If it doesn’t, the function downloads the file from AWS S3 using the provided file name and saves it in the ‘pyaging_data’ directory. After downloading or confirming the file’s existence, it reads and returns the metadata.

Parameters:

dir str

The directory to deposit the downloaded file.

logger object

Logger object used for logging information, warnings, and errors.

indent_level int, optional

The level of indentation for logging messages, by default 1.

Return type:

dict

Returns:

all_clock_metadata : dict A dictionary containing the loaded clock metadata.

Raises:

IOError – If the file download fails or the file cannot be read after downloading.

Notes

The function assumes the presence of a folder named ‘pyaging_data’ in the current directory or creates it if it doesn’t exist. It uses a predefined AWS S3 url to download the metadata file. The function is decorated with @progress, which adds start and end log messages for this process.

Examples

>>> logger = pyaging.logger.LoggerManager.gen_logger("example")
>>> metadata = load_clock_metadata("pyaging_data", logger)
>>> type(metadata)
<class 'dict'>

pyaging.utils._utils.print_model_details(model, max_list_length=30, max_tensor_elements=30)

Prints detailed information about a PyTorch model, including its attributes, structure, and parameters.

Parameters:

model torch.nn.Module

The PyTorch model to be inspected.

max_list_length int

The maximum length of lists to print in full. Lists longer than this will be summarized.

max_tensor_elements int

The maximum number of elements in a tensor to print in full. Tensors with more elements will be summarized.

Notes

The function outputs: - Model Attributes: Non-module, non-parameter attributes of the model, excluding private attributes (those starting with ‘_’). - Model Structure: The structure of the model, showing layers and submodules. - Model Parameters and Weights: Parameters of the model, including weights and biases, with size and value information.

pyaging.utils._utils.progress(message)

A decorator to add progress logging to a function.

This decorator wraps a function to add starting and finishing progress messages to the logger. It extracts the indent_level from keyword arguments, defaults to 1 if not provided, and assumes the logger is the last positional argument. It logs the start and end of the function execution with the provided message.

Parameters:

message str

The message to be logged before and after the function execution. This message is formatted as ‘{message} started’ at the beginning and ‘{message} finished’ at the end.

Return type:

None

Returns:

decorator : function A decorator function that wraps the original function with progress logging.

Raises:

AttributeError – If the logger object is not found as the last positional argument, an AttributeError might be raised when attempting to call start_progress or finish_progress.

Notes

The decorator assumes that the logger object is passed as the last positional argument to the function being decorated. It manipulates kwargs to extract indent_level if provided, otherwise defaults to 1. The indent_level controls the indentation of the log messages.

This will log ‘Processing data started’ before the data_processing function begins and ‘Processing data finished’ after it completes.

Examples

>>> @progress("Processing data")
... def data_processing(data, logger):
...     # data processing logic
...     return processed_data

pyaging.utils._utils.show_all_clocks(dir='pyaging_data')

Displays the names of all aging clocks available in the metadata.

This function retrieves the metadata for all aging clocks and logs each clock’s name. It’s useful for users to get a quick overview of all the clocks included in the pyaging package. The function utilizes a logger for structured output, providing clarity and readability in its logs.

Parameters:

dir str

The directory to deposit the downloaded file. Defaults to ‘pyaging_data’.

Return type:

None

Returns:

None The function only prints the results.

Notes

The function calls load_clock_metadata to load the metadata containing the aging clocks. It then iterates over this metadata to log the name of each clock. The function uses the LoggerManager for logging, ensuring that all log messages are properly formatted and indented.

The logger’s progress methods (start_progress and finish_progress) are used to indicate the start and end of the process, providing a clear indication of the function’s operation.

Examples

>>> all_clocks = show_all_clocks()
Clock1
Clock2
Clock3
...