smftools 0.1.6__py3-none-any.whl → 0.2.1__py3-none-any.whl

smftools/informatics/helpers/ohe_batching.py

@@ -0,0 +1,76 @@
+import os
+import anndata as ad
+import numpy as np
+import concurrent.futures
+from .one_hot_encode import one_hot_encode
+
+def encode_sequence(args):
+    """Parallel helper function for one-hot encoding."""
+    read_name, seq, device = args
+    try:
+        one_hot_matrix = one_hot_encode(seq, device)
+        return read_name, one_hot_matrix
+    except Exception:
+        return None  # Skip invalid sequences
+
+def encode_and_save_batch(batch_data, tmp_dir, prefix, record, batch_number):
+    """Encodes a batch and writes to disk immediately."""
+    batch = {read_name: matrix for read_name, matrix in batch_data if matrix is not None}
+
+    if batch:
+        save_name = os.path.join(tmp_dir, f'tmp_{prefix}_{record}_{batch_number}.h5ad')
+        tmp_ad = ad.AnnData(X=np.zeros((1, 1)), uns=batch)  # Placeholder X
+        tmp_ad.write_h5ad(save_name)
+        return save_name
+    return None
+
+def ohe_batching(base_identities, tmp_dir, record, prefix='', batch_size=100000, progress_bar=None, device='auto', threads=None):
+    """
+    Efficient version of ohe_batching: one-hot encodes sequences in parallel and writes batches immediately.
+
+    Parameters:
+        base_identities (dict): Dictionary mapping read names to sequences.
+        tmp_dir (str): Directory for storing temporary files.
+        record (str): Record name.
+        prefix (str): Prefix for file naming.
+        batch_size (int): Number of reads per batch.
+        progress_bar (tqdm instance, optional): Shared progress bar.
+        device (str): Device for encoding.
+        threads (int, optional): Number of parallel workers.
+
+    Returns:
+        list: List of valid H5AD file paths.
+    """
+    threads = threads or os.cpu_count()  # Default to max available CPU cores
+    batch_data = []
+    batch_number = 0
+    file_names = []
+
+    # Step 1: Prepare Data for Parallel Encoding
+    encoding_args = [(read_name, seq, device) for read_name, seq in base_identities.items() if seq is not None]
+
+    # Step 2: Parallel One-Hot Encoding using threads (to avoid nested processes)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=threads) as executor:
+        for result in executor.map(encode_sequence, encoding_args):
+            if result:
+                batch_data.append(result)
+
+                if len(batch_data) >= batch_size:
+                    # Step 3: Process and Write Batch Immediately
+                    file_name = encode_and_save_batch(batch_data.copy(), tmp_dir, prefix, record, batch_number)
+                    if file_name:
+                        file_names.append(file_name)
+
+                    batch_data.clear()
+                    batch_number += 1
+
+                if progress_bar:
+                    progress_bar.update(1)
+
+    # Step 4: Process Remaining Batch
+    if batch_data:
+        file_name = encode_and_save_batch(batch_data, tmp_dir, prefix, record, batch_number)
+        if file_name:
+            file_names.append(file_name)
+
+    return file_names

smftools/informatics/helpers/ohe_layers_decode.py

@@ -0,0 +1,32 @@
+# ohe_layers_decode
+
+def ohe_layers_decode(adata, obs_names):
+    """
+    Takes an anndata object and a list of observation names. Returns a list of sequence strings for the reads of interest.
+    Parameters:
+        adata (AnnData): An anndata object.
+        obs_names (list): A list of observation name strings to retrieve sequences for.
+
+    Returns:
+        sequences (list of str): List of strings of the one hot encoded array
+    """
+    import anndata as ad
+    import numpy as np
+    from .ohe_decode import ohe_decode
+
+    # Define the mapping of one-hot encoded indices to DNA bases
+    mapping = ['A', 'C', 'G', 'T', 'N']
+
+    ohe_layers = [f"{base}_binary_encoding" for base in mapping]
+    sequences = []
+
+    for obs_name in obs_names:
+        obs_subset = adata[obs_name]
+        ohe_list = []
+        for layer in ohe_layers:
+            ohe_list += list(obs_subset.layers[layer])
+        ohe_array = np.array(ohe_list)
+        sequence = ohe_decode(ohe_array)
+        sequences.append(sequence)
+        
+    return sequences

smftools/informatics/helpers/one_hot_decode.py

@@ -0,0 +1,27 @@
+# one_hot_decode
+
+# String encodings
+def one_hot_decode(ohe_array):
+    """
+    Takes a flattened one hot encoded array and returns the sequence string from that array.
+    Parameters:
+        ohe_array (np.array): A one hot encoded array
+
+    Returns:
+        sequence (str): Sequence string of the one hot encoded array
+    """
+    import numpy as np
+    # Define the mapping of one-hot encoded indices to DNA bases
+    mapping = ['A', 'C', 'G', 'T', 'N']
+    
+    # Reshape the flattened array into a 2D matrix with 5 columns (one for each base)
+    one_hot_matrix = ohe_array.reshape(-1, 5)
+    
+    # Get the index of the maximum value (which will be 1) in each row
+    decoded_indices = np.argmax(one_hot_matrix, axis=1)
+    
+    # Map the indices back to the corresponding bases
+    sequence_list = [mapping[i] for i in decoded_indices]
+    sequence = ''.join(sequence_list)
+    
+    return sequence

smftools/informatics/helpers/one_hot_encode.py

@@ -0,0 +1,57 @@
+# one_hot_encode
+
+def one_hot_encode(sequence, device='auto'):
+    """
+    One-hot encodes a DNA sequence.
+
+    Parameters:
+        sequence (str or list): DNA sequence (e.g., "ACGTN" or ['A', 'C', 'G', 'T', 'N']).
+
+    Returns:
+        ndarray: Flattened one-hot encoded representation of the input sequence.
+    """
+    import numpy as np
+
+    mapping = np.array(['A', 'C', 'G', 'T', 'N'])
+
+    # Ensure input is a list of characters
+    if not isinstance(sequence, list):
+        sequence = list(sequence)  # Convert string to list of characters
+
+    # Handle empty sequences
+    if len(sequence) == 0:
+        print("Warning: Empty sequence encountered in one_hot_encode()")
+        return np.zeros(len(mapping))  # Return empty encoding instead of failing
+
+    # Convert sequence to NumPy array
+    seq_array = np.array(sequence, dtype='<U1')
+
+    # Replace invalid bases with 'N'
+    seq_array = np.where(np.isin(seq_array, mapping), seq_array, 'N')
+
+    # Create one-hot encoding matrix
+    one_hot_matrix = (seq_array[:, None] == mapping).astype(int)
+
+    # Flatten and return
+    return one_hot_matrix.flatten()
+
+    # import torch
+    # bases = torch.tensor([ord('A'), ord('C'), ord('G'), ord('T'), ord('N')], dtype=torch.int8, device=device)
+
+    # # Convert input to tensor of character ASCII codes
+    # seq_tensor = torch.tensor([ord(c) for c in sequence], dtype=torch.int8, device=device)
+
+    # # Handle empty sequence
+    # if seq_tensor.numel() == 0:
+    #     print("Warning: Empty sequence encountered in one_hot_encode_torch()")
+    #     return torch.zeros(len(bases), device=device)
+
+    # # Replace invalid bases with 'N'
+    # is_valid = (seq_tensor[:, None] == bases)  # Compare each base with mapping
+    # seq_tensor = torch.where(is_valid.any(dim=1), seq_tensor, ord('N'))
+
+    # # Create one-hot encoding matrix
+    # one_hot_matrix = (seq_tensor[:, None] == bases).int()
+
+    # # Flatten and return
+    # return one_hot_matrix.flatten()

smftools/informatics/helpers/plot_bed_histograms.py

@@ -0,0 +1,269 @@
+# plot_bed_histograms
+
+def plot_bed_histograms(bed_file, plotting_directory, fasta):
+    """
+    Plots read length, coverage, mapq, read quality stats for each record.
+
+    Parameters:
+        bed_file (str): Path to the bed file to derive metrics from.
+        plot_directory (str): Path to the directory to write out historgrams.
+        fasta (str): Path to FASTA corresponding to bed
+
+    Returns:
+        None
+    """
+    import pandas as pd
+    import matplotlib.pyplot as plt
+    import numpy as np
+    import os
+
+    # plot_bed_histograms.py
+
+def plot_bed_histograms(
+    bed_file,
+    plotting_directory,
+    fasta,
+    *,
+    bins=60,
+    clip_quantiles=(0.0, 0.995),
+    cov_bin_size=1000,       # coverage bin size in bp
+    rows_per_fig=6,          # paginate if many chromosomes
+    include_mapq_quality=True,   # add MAPQ + avg read quality columns to grid
+    coordinate_mode="one_based",  # "one_based" (your BED-like) or "zero_based"
+):
+    """
+    Plot per-chromosome QC grids from a BED-like file.
+
+    Expects columns:
+      chrom, start, end, read_len, qname, mapq, avg_base_qual
+
+    For each chromosome:
+      - Column 1: Read length histogram
+      - Column 2: Coverage across the chromosome (binned)
+      - (optional) Column 3: MAPQ histogram
+      - (optional) Column 4: Avg base quality histogram
+
+    The figure is paginated: rows = chromosomes (up to rows_per_fig), columns depend on include_mapq_quality.
+    Saves one PNG per page under `plotting_directory`.
+
+    Parameters
+    ----------
+    bed_file : str
+    plotting_directory : str
+    fasta : str
+        Reference FASTA (used to get chromosome lengths).
+    bins : int
+        Histogram bins for read length / MAPQ / quality.
+    clip_quantiles : (float, float)
+        Clip hist tails for readability (e.g., (0, 0.995)).
+    cov_bin_size : int
+        Bin size (bp) for coverage plot; bigger = faster/coarser.
+    rows_per_fig : int
+        Number of chromosomes per page.
+    include_mapq_quality : bool
+        If True, add MAPQ and avg base quality histograms as extra columns.
+    coordinate_mode : {"one_based","zero_based"}
+        One-based, inclusive (your file) vs BED-standard zero-based, half-open.
+    """
+    import os
+    import numpy as np
+    import pandas as pd
+    import matplotlib.pyplot as plt
+    import pysam
+
+    os.makedirs(plotting_directory, exist_ok=True)
+
+    bed_basename = os.path.basename(bed_file).rsplit(".bed", 1)[0]
+    print(f"[plot_bed_histograms] Loading: {bed_file}")
+
+    # Load BED-like table
+    cols = ['chrom', 'start', 'end', 'read_len', 'qname', 'mapq', 'avg_q']
+    df = pd.read_csv(bed_file, sep="\t", header=None, names=cols, dtype={
+        'chrom': str, 'start': int, 'end': int, 'read_len': int, 'qname': str,
+        'mapq': float, 'avg_q': float
+    })
+
+    # Drop unaligned records (chrom == '*') if present
+    df = df[df['chrom'] != '*'].copy()
+    if df.empty:
+        print("[plot_bed_histograms] No aligned reads found; nothing to plot.")
+        return
+
+    # Ensure coordinate mode consistent; convert to 0-based half-open for bin math internally
+    # Input is typically one_based inclusive (from your writer).
+    if coordinate_mode not in {"one_based", "zero_based"}:
+        raise ValueError("coordinate_mode must be 'one_based' or 'zero_based'")
+
+    if coordinate_mode == "one_based":
+        # convert to 0-based half-open [start0, end0)
+        start0 = df['start'].to_numpy() - 1
+        end0   = df['end'].to_numpy()   # inclusive in input -> +1 already handled by not subtracting
+    else:
+        # already 0-based half-open (assumption)
+        start0 = df['start'].to_numpy()
+        end0   = df['end'].to_numpy()
+
+    # Clip helper for hist tails
+    def _clip_series(s, q=(0.0, 0.995)):
+        if q is None:
+            return s.to_numpy()
+        lo = s.quantile(q[0]) if q[0] is not None else s.min()
+        hi = s.quantile(q[1]) if q[1] is not None else s.max()
+        x = s.to_numpy(dtype=float)
+        return np.clip(x, lo, hi)
+
+    # Load chromosome order/lengths from FASTA
+    with pysam.FastaFile(fasta) as fa:
+        ref_names = list(fa.references)
+        ref_lengths = dict(zip(ref_names, fa.lengths))
+
+    # Keep only chroms present in FASTA and with at least one read
+    chroms = [c for c in df['chrom'].unique() if c in ref_lengths]
+    # Order chromosomes by FASTA order
+    chrom_order = [c for c in ref_names if c in chroms]
+
+    if not chrom_order:
+        print("[plot_bed_histograms] No chromosomes from BED are present in FASTA; aborting.")
+        return
+
+    # Pagination
+    def _sanitize(name: str) -> str:
+        return "".join(ch if ch.isalnum() or ch in "-._" else "_" for ch in name)
+
+    cols_per_fig = 4 if include_mapq_quality else 2
+
+    for start_idx in range(0, len(chrom_order), rows_per_fig):
+        chunk = chrom_order[start_idx:start_idx + rows_per_fig]
+        nrows = len(chunk)
+        ncols = cols_per_fig
+
+        fig, axes = plt.subplots(
+            nrows=nrows, ncols=ncols,
+            figsize=(4.0 * ncols, 2.6 * nrows),
+            dpi=160,
+            squeeze=False
+        )
+
+        for r, chrom in enumerate(chunk):
+            chrom_len = ref_lengths[chrom]
+            mask = (df['chrom'].to_numpy() == chrom)
+
+            # Slice per-chrom arrays for speed
+            s0 = start0[mask]
+            e0 = end0[mask]
+            len_arr = df.loc[mask, 'read_len']
+            mapq_arr = df.loc[mask, 'mapq']
+            q_arr = df.loc[mask, 'avg_q']
+
+            # --- Col 1: Read length histogram (clipped) ---
+            ax = axes[r, 0]
+            ax.hist(_clip_series(len_arr, clip_quantiles), bins=bins, edgecolor="black", alpha=0.7)
+            if r == 0:
+                ax.set_title("Read length")
+            ax.set_ylabel(f"{chrom}\n(n={mask.sum()})")
+            ax.set_xlabel("bp")
+            ax.grid(alpha=0.25)
+
+            # --- Col 2: Coverage (binned over genome) ---
+            ax = axes[r, 1]
+            nb = max(1, int(np.ceil(chrom_len / cov_bin_size)))
+            # Bin edges in 0-based coords
+            edges = np.linspace(0, chrom_len, nb + 1, dtype=int)
+
+            # Compute per-bin "read count coverage": number of reads overlapping each bin.
+            # Approximate by incrementing all bins touched by the interval.
+            # (Fast and memory-light; for exact base coverage use smaller cov_bin_size.)
+            cov = np.zeros(nb, dtype=np.int32)
+            # bin indices overlapped by each read (0-based half-open)
+            b0 = np.minimum(np.searchsorted(edges, s0, side="right") - 1, nb - 1)
+            b1 = np.maximum(np.searchsorted(edges, np.maximum(e0 - 1, 0), side="right") - 1, 0)
+            # ensure valid ordering
+            b_lo = np.minimum(b0, b1)
+            b_hi = np.maximum(b0, b1)
+
+            # Increment all bins in range; loop but at bin resolution (fast for reasonable cov_bin_size).
+            for lo, hi in zip(b_lo, b_hi):
+                cov[lo:hi + 1] += 1
+
+            x_mid = (edges[:-1] + edges[1:]) / 2.0
+            ax.plot(x_mid, cov)
+            if r == 0:
+                ax.set_title(f"Coverage (~{cov_bin_size} bp bins)")
+            ax.set_xlim(0, chrom_len)
+            ax.set_xlabel("Position (bp)")
+            ax.set_ylabel("")  # already show chrom on col 1
+            ax.grid(alpha=0.25)
+
+            if include_mapq_quality:
+                # --- Col 3: MAPQ ---
+                ax = axes[r, 2]
+                # Clip MAPQ upper tail if needed (usually 60)
+                ax.hist(_clip_series(mapq_arr.fillna(0), clip_quantiles), bins=bins, edgecolor="black", alpha=0.7)
+                if r == 0:
+                    ax.set_title("MAPQ")
+                ax.set_xlabel("MAPQ")
+                ax.grid(alpha=0.25)
+
+                # --- Col 4: Avg base quality ---
+                ax = axes[r, 3]
+                ax.hist(_clip_series(q_arr.fillna(np.nan), clip_quantiles), bins=bins, edgecolor="black", alpha=0.7)
+                if r == 0:
+                    ax.set_title("Avg base qual")
+                ax.set_xlabel("Phred")
+                ax.grid(alpha=0.25)
+
+        fig.suptitle(
+            f"{bed_basename} — per-chromosome QC "
+            f"({'len,cov,MAPQ,qual' if include_mapq_quality else 'len,cov'})",
+            y=0.995, fontsize=11
+        )
+        fig.tight_layout(rect=[0, 0, 1, 0.98])
+
+        page = start_idx // rows_per_fig + 1
+        out_png = os.path.join(plotting_directory, f"{_sanitize(bed_basename)}_qc_page{page}.png")
+        plt.savefig(out_png, bbox_inches="tight")
+        plt.close(fig)
+
+    print("[plot_bed_histograms] Done.")
+
+
+    # bed_basename = os.path.basename(bed_file).split('.bed')[0]
+    # # Load the BED file into a DataFrame
+    # print(f"Loading BED to plot read length and coverage histograms: {bed_file}")
+    # df = pd.read_csv(bed_file, sep='\t', header=None, names=['chromosome', 'start', 'end', 'length', 'read_name', 'mapq', 'read_quality'])
+    
+    # # Group by chromosome
+    # grouped = df.groupby('chromosome')
+
+    # # for each chromosome, get the record length of that chromosome from the fasta. Use from 0 to this length for the positional coverage plot.
+
+    # # Change below and make a plot grid instead. For each, make row for chromsome, col for read length and coverage
+    # # Clip the outliers to make plots cleaner
+
+    # for chrom, group in grouped:
+    #     # Plot read length histogram
+    #     plt.figure(figsize=(12, 6))
+    #     plt.hist(group['length'], bins=50, edgecolor='k', alpha=0.7)
+    #     plt.title(f'Read Length Histogram of reads aligned to {chrom}')
+    #     plt.xlabel('Read Length')
+    #     plt.ylabel('Count')
+    #     plt.grid(True)
+    #     save_name = os.path.join(plotting_directory, f'{bed_basename}_{chrom}_read_length_histogram.png')
+    #     plt.savefig(save_name)
+    #     plt.close()
+
+    #     # Compute coverage
+    #     coverage = np.zeros(group['end'].max())
+    #     for _, row in group.iterrows():
+    #         coverage[row['start']:row['end']] += 1
+        
+    #     # Plot coverage histogram
+    #     plt.figure(figsize=(12, 6))
+    #     plt.plot(coverage, color='b')
+    #     plt.title(f'Coverage Histogram for {chrom}')
+    #     plt.xlabel('Position')
+    #     plt.ylabel('Coverage')
+    #     plt.grid(True)
+    #     save_name = os.path.join(plotting_directory, f'{bed_basename}_{chrom}_coverage_histogram.png')
+    #     plt.savefig(save_name)
+    #     plt.close()

smftools/informatics/helpers/run_multiqc.py

@@ -0,0 +1,28 @@
+def run_multiqc(input_dir, output_dir):
+    """
+    Runs MultiQC on a given directory and saves the report to the specified output directory.
+
+    Parameters:
+    - input_dir (str): Path to the directory containing QC reports (e.g., FastQC, Samtools, bcftools outputs).
+    - output_dir (str): Path to the directory where MultiQC reports should be saved.
+
+    Returns:
+    - None: The function executes MultiQC and prints the status.
+    """
+    import os
+    import subprocess
+    # Ensure the output directory exists
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Construct MultiQC command
+    command = ["multiqc", input_dir, "-o", output_dir]
+
+    print(f"Running MultiQC on '{input_dir}' and saving results to '{output_dir}'...")
+    
+    # Run MultiQC
+    try:
+        subprocess.run(command, check=True)
+        print(f"MultiQC report generated successfully in: {output_dir}")
+    except subprocess.CalledProcessError as e:
+        print(f"Error running MultiQC: {e}")
+

smftools/informatics/helpers/separate_bam_by_bc.py

@@ -0,0 +1,43 @@
+## separate_bam_by_bc
+
+def separate_bam_by_bc(input_bam, output_prefix, bam_suffix, split_dir):
+    """
+    Separates an input BAM file on the BC SAM tag values.
+
+    Parameters:
+        input_bam (str): File path to the BAM file to split.
+        output_prefix (str): A prefix to append to the output BAM.
+        bam_suffix (str): A suffix to add to the bam file.
+        split_dir (str): String indicating path to directory to split BAMs into
+    
+    Returns:
+        None
+            Writes out split BAM files.
+    """
+    import pysam
+    import os
+
+    bam_base = os.path.basename(input_bam)
+    bam_base_minus_suffix = bam_base.split(bam_suffix)[0]
+
+    # Open the input BAM file for reading
+    with pysam.AlignmentFile(input_bam, "rb") as bam:
+        # Create a dictionary to store output BAM files
+        output_files = {}
+        # Iterate over each read in the BAM file
+        for read in bam:
+            try:
+                # Get the barcode tag value
+                bc_tag = read.get_tag("BC", with_value_type=True)[0]
+                #bc_tag = read.get_tag("BC", with_value_type=True)[0].split('barcode')[1]
+                # Open the output BAM file corresponding to the barcode
+                if bc_tag not in output_files:
+                    output_path = os.path.join(split_dir, f"{output_prefix}_{bam_base_minus_suffix}_{bc_tag}{bam_suffix}")
+                    output_files[bc_tag] = pysam.AlignmentFile(output_path, "wb", header=bam.header)
+                # Write the read to the corresponding output BAM file
+                output_files[bc_tag].write(read)
+            except KeyError:
+                 print(f"BC tag not present for read: {read.query_name}")
+    # Close all output BAM files
+    for output_file in output_files.values():
+        output_file.close()

smftools/informatics/helpers/split_and_index_BAM.py

@@ -0,0 +1,32 @@
+## split_and_index_BAM
+
+def split_and_index_BAM(aligned_sorted_BAM, split_dir, bam_suffix):
+    """
+    A wrapper function for splitting BAMS and indexing them.
+    Parameters:
+        aligned_sorted_BAM (str): A string representing the file path of the aligned_sorted BAM file.
+        split_dir (str): A string representing the file path to the directory to split the BAMs into.
+        bam_suffix (str): A suffix to add to the bam file.
+    
+    Returns:
+        None
+            Splits an input BAM file on barcode value and makes a BAM index file.
+    """
+    from .. import readwrite
+    import os
+    import subprocess
+    import glob
+    from .separate_bam_by_bc import separate_bam_by_bc
+    from .make_dirs import make_dirs
+
+    aligned_sorted_output = aligned_sorted_BAM + bam_suffix
+    file_prefix = readwrite.date_string()
+    separate_bam_by_bc(aligned_sorted_output, file_prefix, bam_suffix, split_dir)
+    # Make a BAM index file for the BAMs in that directory
+    bam_pattern = '*' + bam_suffix
+    bam_files = glob.glob(os.path.join(split_dir, bam_pattern))
+    bam_files = [bam for bam in bam_files if '.bai' not in bam]
+    for input_file in bam_files:
+        subprocess.run(["samtools", "index", input_file])
+
+    return bam_files

smftools/informatics/readwrite.py

@@ -0,0 +1,106 @@
+## readwrite ##
+
+######################################################################################################
+## Datetime functionality
+def date_string():
+    """
+    Each time this is called, it returns the current date string
+    """
+    from datetime import datetime
+    current_date = datetime.now()
+    date_string = current_date.strftime("%Y%m%d")
+    date_string = date_string[2:]
+    return date_string
+
+def time_string():
+    """
+    Each time this is called, it returns the current time string
+    """
+    from datetime import datetime
+    current_time = datetime.now()
+    return current_time.strftime("%H:%M:%S")
+######################################################################################################
+
+######################################################################################################
+## Numpy, Pandas, Anndata functionality
+def adata_to_df(adata, layer=None):
+    """
+    Input: An adata object with a specified layer.
+    Output: A dataframe for the specific layer.
+    """
+    import pandas as pd
+    import anndata as ad
+
+    # Extract the data matrix from the given layer
+    if layer:
+        data_matrix = adata.layers[layer]
+    else:
+        data_matrix = adata.X
+    # Extract observation (read) annotations
+    obs_df = adata.obs
+    # Extract variable (position) annotations
+    var_df = adata.var
+    # Convert data matrix and annotations to pandas DataFrames
+    df = pd.DataFrame(data_matrix, index=obs_df.index, columns=var_df.index)
+    return df
+
+def save_matrix(matrix, save_name):
+    """
+    Input: A numpy matrix and a save_name
+    Output: A txt file representation of the data matrix
+    """
+    import numpy as np
+    np.savetxt(f'{save_name}.txt', matrix)
+
+def concatenate_h5ads(output_file, file_suffix='h5ad.gz', delete_inputs=True):
+    """
+    Concatenate all h5ad files in a directory and delete them after the final adata is written out.
+    Input: an output file path relative to the directory in which the function is called
+    """
+    import os
+    import anndata as ad
+    # Runtime warnings
+    import warnings
+    warnings.filterwarnings('ignore', category=UserWarning, module='anndata')
+    warnings.filterwarnings('ignore', category=FutureWarning, module='anndata')
+    
+    # List all files in the directory
+    files = os.listdir(os.getcwd())
+    # get current working directory
+    cwd = os.getcwd()
+    suffix = file_suffix
+    # Filter file names that contain the search string in their filename and keep them in a list
+    hdfs = [hdf for hdf in files if suffix in hdf]
+    # Sort file list by names and print the list of file names
+    hdfs.sort()
+    print('{0} sample files found: {1}'.format(len(hdfs), hdfs))
+    # Iterate over all of the hdf5 files and concatenate them.
+    final_adata = None
+    for hdf in hdfs:
+        print('{0}: Reading in {1} hdf5 file'.format(time_string(), hdf))
+        temp_adata = ad.read_h5ad(hdf)
+        if final_adata:
+            print('{0}: Concatenating final adata object with {1} hdf5 file'.format(time_string(), hdf))
+            final_adata = ad.concat([final_adata, temp_adata], join='outer', index_unique=None)
+        else:
+            print('{0}: Initializing final adata object with {1} hdf5 file'.format(time_string(), hdf))
+            final_adata = temp_adata
+    print('{0}: Writing final concatenated hdf5 file'.format(time_string()))
+    final_adata.write_h5ad(output_file, compression='gzip')
+
+    # Delete the individual h5ad files and only keep the final concatenated file
+    if delete_inputs:
+        files = os.listdir(os.getcwd())
+        hdfs = [hdf for hdf in files if suffix in hdf]
+        if output_file in hdfs:
+            hdfs.remove(output_file)
+            # Iterate over the files and delete them
+            for hdf in hdfs:
+                try:
+                    os.remove(hdf)
+                    print(f"Deleted file: {hdf}")
+                except OSError as e:
+                    print(f"Error deleting file {hdf}: {e}")
+    else:
+        print('Keeping input files')
+######################################################################################################