Isomatrix Tools

A suite of utilities designed for handling isomatrices, which are generated by scisclor. These tools facilitate tasks such as converting isomatrices to AnnData format, merging multiple isomatrices, and more. Additionally, the suite includes features for downloading or generating isomatrix data, which can be particularly useful for testing and demonstrating new features.

The Isomatrix Tools module provides a comprehensive set of utilities for working with isomatrices, particularly those generated by the scisclor tool. One of the key functionalities of this module is the conversion of isomatrix text files, which are the output of scisclor, into AnnData objects that are compatible with the Scanpy library. This conversion process is crucial for enabling downstream analysis of single-cell long-read data within the Scanpy ecosystem, allowing users to leverage its powerful analytical capabilities. The module ensures that the conversion retains all necessary gene and transcript information, and it supports the creation of both dense and sparse matrix representations to cater to different computational needs.

source

isomatrix_to_anndata

 isomatrix_to_anndata (file_path:str, sparse:bool=False)

This function converts an isomatrix txt file (SiCeLoRe output) into an AnnData object compatible with scanpy

Type Default Details
file_path str The path to the isomatrix csv file to be read.
sparse bool False Flag to determine if the output should be a sparse matrix.
Returns AnnData The converted isomatrix as a scanpy compatible anndata object

This section pertains to the retrieval of sample data which is essential for testing and validating the functionality of the Isomatrix Tools module. The sample data is an isomatrix text file, which is a typical output of the SiCeLoRe pipeline, and is used to ensure that the conversion to an AnnData object is performed correctly. The downloaded file is also used in the demonstration and testing of other functions within this module.

source

download_test_data

 download_test_data ()

This function downloads a test data file from a specified URL, saves it locally, and extracts it.

The Isomatrix Tools module includes functionality to simulate an isomatrix, which is a matrix representation of transcript expression data. This simulated data can be used for testing and validation purposes within the Isomatrix Tools framework. The simulation is designed to mimic the structure and characteristics of real transcriptomic datasets, allowing users to generate data with specified parameters such as the number of genes, transcripts per gene, number of samples, sparsity of the matrix, and maximum expression levels. The simulate_isomatrix function in the code block below provides a practical example of how such data can be generated for use with Isomatrix Tools.

source

simulate_isomatrix

 simulate_isomatrix (num_genes:int, num_transcripts_per_gene:int,
                     num_samples:int, sparsity:float=0.95,
                     max_expression:int=100, seed:int=0)

Simulate transcript expression data to match the structure of the first image provided by the user. Allows specifying the number of genes, transcripts per gene, and samples.

Type Default Details
num_genes int number of genes (groups of rows)
num_transcripts_per_gene int number of transcripts per gene
num_samples int number of samples (columns)
sparsity float 0.95 fraction of zeros in the data (default 0.95)
max_expression int 100 maximum expression level for any transcript in any sample
seed int 0 random seed for reproducibility
Returns DataFrame DataFrame with simulated transcript expression data for demonstration purposes.

The isomatrix_tools module provides functionality to simulate and generate multiple isomatrix datasets. These datasets are essential for testing and demonstrating the capabilities of downstream analysis tools. The simulation process involves creating synthetic gene expression data that closely resembles real-world isomatrix data structures. This includes the ability to specify the number of genes, transcripts per gene, samples, and control the sparsity and maximum expression levels of the generated data. The simulate_and_save_isomatrices function within this module is particularly useful for creating a series of isomatrix files, which can be saved to a specified directory for further use in pipeline testing or demonstration purposes. The function also offers options to return the file paths of the generated isomatrices and to output progress messages during the simulation process.

source

simulate_and_save_isomatrices

 simulate_and_save_isomatrices (num_isomatrix:int, num_genes:int,
                                num_transcripts_per_gene:int,
                                num_samples:int, sparsity:float=0.95,
                                max_expression:int=100, seed:int=0,
                                output_dir:str='./',
                                return_paths:bool=False,
                                verbose:bool=False)

Simulate multiple isomatrix and save them as txt files in the specified directory. If return_paths is True, return a list of paths to the saved isomatrix files.

Type Default Details
num_isomatrix int number of isomatrix to generate
num_genes int number of genes (groups of rows)
num_transcripts_per_gene int number of transcripts per gene
num_samples int number of samples (columns)
sparsity float 0.95 fraction of zeros in the data (default 0.95)
max_expression int 100 maximum expression level for any transcript in any sample
seed int 0 random seed for reproducibility
output_dir str ./ directory to save the generated isomatrix txt files
return_paths bool False return paths to the isomatrixs as a list of strings if True
verbose bool False print progress messages if True
Returns list list of paths for the simulated matrices (if return is set True)

source

convert_and_save_file

 convert_and_save_file (sample:str, verbose:bool, sparse:bool=False)

Convert an isomatrix txt file to an AnnData h5ad file and save it to disk. If the file already exists, it is overwritten. A delay and retry mechanism is implemented to handle file locking issues.

Type Default Details
sample str path to the isomatrix txt file
verbose bool print progress messages if True
sparse bool False store the anndata object in sparse format if True
Returns str path to the converted h5ad file

#he Isomatrix tools module provides a suite of functions designed to facilitate the conversion of isomatrix files into AnnData objects, which are suitable for downstream analysis in single-cell genomics workflows. This module includes a function multiple_isomatrix_conversion that efficiently processes batches of isomatrix files, leveraging parallel processing to expedite the conversion. The converted AnnData objects can optionally be stored in a sparse format to optimize memory usage. Additionally, the module contains functions for handling file I/O operations, such as checking for the existence of files and implementing a retry mechanism to address file locking issues during the write process. The module also includes functionality to standardize feature sets across multiple datasets, ensuring consistency in subsequent analyses.

source

multiple_isomatrix_conversion

 multiple_isomatrix_conversion (file_paths:list, verbose:bool=False,
                                return_paths:bool=False,
                                sparse:bool=False)

This function takes a list of file paths, converts each file from isomatrix to anndata format, and saves the converted file in the same location with the same name but with a .h5ad extension. If return_paths is True, it returns a list of paths to the converted files. If sparse is True, the anndata object will be stored in sparse format.

Type Default Details
file_paths list A list of file paths to be converted.
verbose bool False If True, print progress messages.
return_paths bool False If True, return a list of paths to the converted files.
sparse bool False If True, the anndata object will be stored in sparse format.
Returns list A list of paths to the converted files.

The Isomatrix tools module includes advanced functionality for standardizing transcript features across multiple isoform matrix datasets. This process is crucial for ensuring that subsequent analyses are consistent and comparable. The module provides the option to standardize features by either taking the union or the intersection of all transcripts present in the datasets. The ‘union’ method combines all unique transcripts from each dataset, thus preserving the full range of features. In contrast, the ‘intersection’ method retains only those transcripts that are common to all datasets, which can be beneficial for comparative studies where only shared features are of interest. This flexibility allows researchers to tailor the standardization process to their specific analytical needs and the nature of their datasets.

source

feature_set_standardization

 feature_set_standardization (adatas:list,
                              standardization_method:str='union')

Standardize the feature sets of multiple AnnData objects.

This function takes a list of AnnData objects or paths to AnnData files and a standardization method as input. The standardization method can be either ‘union’ or ‘intersection’. If ‘union’ is chosen, the function will create a union of all features across all AnnData objects. If ‘intersection’ is chosen, the function will create an intersection of all features across all AnnData objects. The function returns a list of standardized AnnData objects.

Type Default Details
adatas list list of AnnData objects or paths to AnnData files
standardization_method str union str specifiying method to use union or intersection
Returns list list of anndata objects with the features standardised

The Isomatrix tools module includes a function to validate and prepare an AnnData object for serialization and storage. This function ensures that the AnnData object conforms to the requirements for writing to disk as an .h5ad file, which is the file format used by Scanpy’s write_h5ad method. The function checks for the presence of missing values in the .var and .obs DataFrames, converts non-string categorical data to strings, ensures that the observation and variable names are of string data type, and verifies that there are no duplicate names. Additionally, it checks for NaN values in the .X attribute, which holds the main data matrix, and provides warnings if any issues are detected that could interfere with the file writing process. This preprocessing step is crucial for maintaining data integrity and ensuring compatibility with downstream analysis tools that rely on the .h5ad file format.

source

check_anndata_for_saving

 check_anndata_for_saving (adata:anndata._core.anndata.AnnData,
                           verbose:bool=False)

Prepare an AnnData object for saving by ensuring proper data types and handling missing values.

Type Default Details
adata AnnData The AnnData object to check.
verbose bool False If True, print status messages. Defaults to False.

This module provides functionality to concatenate multiple AnnData objects, which are essential data structures for storing large-scale single-cell genomics data. The concatenation process is designed to combine data from different batches or experiments, while ensuring that the resulting AnnData object maintains the integrity and structure necessary for downstream analysis. The Isomatrix tools facilitate this process by handling discrepancies in data types, filling missing values, and standardizing feature sets across all input datasets. This ensures that the concatenated dataset is ready for high-throughput computational analyses, such as clustering, visualization, and differential expression testing, which are common in single-cell genomics workflows.

source

make_unique_batch_keys

 make_unique_batch_keys (batch_keys)

source

concatenate_anndata

 concatenate_anndata (h5ad_inputs:list, standardization_method='union',
                      sparse=False, verbose=False)

This function concatenates multiple AnnData objects into a single AnnData object and adds batch keys to identify the origin of each sample.

Type Default Details
h5ad_inputs list A list of AnnData objects or paths to .h5ad files.
standardization_method str union The method to standardize the feature sets across all AnnData objects. It can be either ‘union’ or ‘intersection’. Default is ‘union’.
sparse bool False Optional flag to convert the final matrix to sparse. Default is False.
verbose bool False Optional flag to print progress updates. Default is False.
Returns AnnData The concatenated AnnData object.

source

make_unique_batch_keys

 make_unique_batch_keys (batch_keys)