vmwhere 0.2.0__py3-none-any.whl

vmwhere/__init__.py

@@ -0,0 +1,6 @@
+try:
+    from vmwhere._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

vmwhere/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

vmwhere/chr_mapping_simple.txt

@@ -0,0 +1,25 @@
+NC_060925.1 chr1
+NC_060926.1 chr2
+NC_060927.1 chr3
+NC_060928.1 chr4
+NC_060929.1 chr5
+NC_060930.1 chr6
+NC_060931.1 chr7
+NC_060932.1 chr8
+NC_060933.1 chr9
+NC_060934.1 chr10
+NC_060935.1 chr11
+NC_060936.1 chr12
+NC_060937.1 chr13
+NC_060938.1 chr14
+NC_060939.1 chr15
+NC_060940.1 chr16
+NC_060941.1 chr17
+NC_060942.1 chr18
+NC_060943.1 chr19
+NC_060944.1 chr20
+NC_060945.1 chr21
+NC_060946.1 chr22
+NC_060947.1 chrX
+NC_060948.1 chrY
+chrM chrM

vmwhere/cli.py

@@ -0,0 +1,95 @@
+import argparse
+import subprocess
+from importlib.resources import files
+from .find import run_find
+from .genotyper import run_genotyper
+
+
+def find_microsatellites(args):
+
+    run_find(
+            motif=args.motif,
+            fasta_file=args.fasta,
+            repeats=args.perfect_repeats,
+            gap=args.max_gap,
+            output_dir=args.output_dir,
+            buffer=args.buffer_size
+            )
+
+
+def genotype_microsatellites(args):
+
+    run_genotyper(
+        sample_id=args.sample_id,
+        bam_file=args.bam_file,
+        fasta=args.fasta,
+        cluster_distance=args.cluster_distance,
+        minor_threshold=args.minor_threshold,
+        major_threshold=args.major_threshold,
+        bed_file=args.bed_file,
+        output_dir=args.output_dir,
+        num_processes=args.num_processes
+    )
+
+
+def visualize_microsatellite(args):
+    r_script_path = files("vmwhere").joinpath("visualize_region.R")
+
+    subprocess.run([
+        "Rscript",
+        str(r_script_path),
+        args.genotype_tsv,
+        args.microsatellite_id,
+        args.min_allele_count,
+        args.output_pdf], check=True)
+    
+    
+
+def main():
+    parser = argparse.ArgumentParser(
+            description="vmwhere: microsatellite reference identification, sample genotyping, sequence decomposition, and visualization from long-read data"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    
+    # --- Subcommand: find ---
+    find_parser = subparsers.add_parser("find", help="Identify genomic coordinates of repeat microsatellite sequences based on a reference")
+    
+    find_parser.add_argument("-m", "--motif", required=True)
+    find_parser.add_argument("-r", "--perfect_repeats", type=int, default=2)
+    find_parser.add_argument("-g", "--max_gap", type=int, default=50)
+    find_parser.add_argument("-b", "--buffer_size", type=int, default=50)
+    find_parser.add_argument("-o", "--output_dir", required=True)
+    find_parser.add_argument("-f", "--fasta", required=True)
+    find_parser.set_defaults(func=find_microsatellites)
+
+
+    # --- Subcommand: genotype ---
+    profile_parser = subparsers.add_parser("genotype", help="Genotype microsatellites given a sample BAM file")
+    
+    profile_parser.add_argument("--sample_id", required=True, help="Output file will be sample_id_vmwhere_results.tsv")
+    profile_parser.add_argument("--bed_file", required=True, help="Header free bed file with columns chr start end region_id motif")
+    profile_parser.add_argument("--bam_file", required=True, help="Sorted, indexed, sample bam file")
+    profile_parser.add_argument("--fasta", required=True, help="Path to reference fasta file")
+    profile_parser.add_argument("--cluster_distance", type=int, default=0, help="Edit distance to use when clustering reads prior to allele calling")
+    profile_parser.add_argument("--minor_threshold", type=float, default=0.20, help="Minimium locus read support (fraction) to be called an allele")
+    profile_parser.add_argument("--major_threshold", type=float, default=0.80, help="Read support (fraction) for calling homozygous microsatellites")
+    profile_parser.add_argument("--output_dir", required=True, help="Parent directory for genotyping results")
+    profile_parser.add_argument("--num_processes", type=int, default=24)
+    profile_parser.set_defaults(func=genotype_microsatellites)
+
+    # --- Subcommand: visualize ---
+    vis_parser = subparsers.add_parser("visualize", help="Visualize sequence resolved alleles for a specific region")
+    
+    vis_parser.add_argument("-g", "--genotype_tsv", required=True, help="genotype results in vmwhere tsv format")
+    vis_parser.add_argument("-m", "--microsatellite_id", required=True, help="The unique region_id in the genotype output file")
+    vis_parser.add_argument("-o", "--output_pdf", required=True, help = "Output file path and name")
+    vis_parser.add_argument("-c", "--min_allele_count", required=True, default=0, help="Filter out low frequency alleles")
+    vis_parser.set_defaults(func=visualize_microsatellite)
+
+    # Parse args and dispatch
+    args = parser.parse_args()
+    args.func(args)
+
+if __name__ == "__main__":
+    main()
+

vmwhere/find.py

@@ -0,0 +1,160 @@
+import argparse
+from Bio.Seq import Seq
+from Bio import SeqIO
+import pandas as pd
+import os
+import logging
+
+# Configure logging once at the start of the script
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+
+def find_motif_genomic_coordinates(sequence, motif, buffer_size):
+    """Find occurrences of a motif in a genomic sequence."""
+
+    motif = Seq(motif)
+    motif_str = str(motif)
+    motif_len = len(motif)
+    motif_start = 0
+    res = []
+
+    while True:
+        # find successive occurances of motifs as you move along the contig
+        motif_start = sequence.find(motif_str, motif_start)
+        if motif_start == -1:
+            break
+
+        # Initialize forward scanning variables.
+        current_pos = motif_start
+        motif_num_next = 1
+        perfect_count = 1  # the initial match is perfect
+
+        # Scan forward from the first match to find all repeats.
+        while True:
+            next_chunk_start = current_pos + motif_len
+            next_chunk = sequence[next_chunk_start: next_chunk_start + motif_len]
+            if next_chunk == motif_str:
+                motif_num_next += 1
+                perfect_count += 1
+                current_pos = next_chunk_start
+            else:
+                break
+
+        motif_end = current_pos + motif_len
+        buffer_start = max(0, motif_start - buffer_size)
+        buffer_end = motif_end + buffer_size
+
+        res.append({
+            'Motif': motif_str,
+            'Motif_Start': motif_start,
+            'Motif_End': motif_end,
+            'Total_Repeats': motif_num_next,
+            'Perfect_Repeats': perfect_count,
+            'Buffer_Start': buffer_start,
+            'Buffer_End': buffer_end
+        })
+
+        motif_start = motif_end
+
+    return res
+
+def merge_adjacent_motifs(df, max_gap):
+    if df.empty:
+        return df
+
+    df = df.sort_values(by=['chrom', 'Motif_Start']).reset_index(drop=True)
+
+    # Calculate gaps, but reset at chromosome boundaries
+    prev_chrom = df['chrom'].shift()
+    prev_end = df['Motif_End'].shift()
+
+    # A new group starts when: different chromosome OR gap exceeds max_gap
+    new_group = (df['chrom'] != prev_chrom) | (df['Motif_Start'] > (prev_end + max_gap))
+    df['group'] = new_group.cumsum()
+
+    # Aggregate merged groups using built-in aggregation functions
+    merged_df = df.groupby(['chrom', 'group'], as_index=False).agg({
+        'Buffer_Start': 'min',
+        'Buffer_End': 'max',
+        'motif': 'first',
+        'Motif_Start': 'min',
+        'Motif_End': 'max',
+        'Total_Repeats': 'sum',
+        'Perfect_Repeats': 'sum'
+    }).drop(columns=['group'])
+
+    return merged_df
+
+def name_each_region(merged_df):
+    """Give each region a unique identifier to be used to track regions during post processing"""
+    merged_df = merged_df.copy()
+    merged_df['region_name'] = merged_df['chrom'] + '_region_'  + (merged_df.reset_index().index + 1).astype(str)
+    return merged_df
+
+def run_find(
+        motif,
+        repeats,
+        gap,
+        fasta_file,
+        buffer,
+        output_dir
+        ):
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    results = []
+    motif = motif.upper()
+    perfect_repeats = repeats
+    max_gap = gap
+    buffer_size = buffer
+    chrom_sequences = {}
+    
+    for seq_record in SeqIO.parse(fasta_file, "fasta"):
+        chrom = seq_record.id
+        sequence = seq_record.seq.upper()
+        chrom_sequences[chrom] = sequence
+                
+        # Look for motif occurances (always store forward motif)
+        forward_results = find_motif_genomic_coordinates(sequence, motif, buffer_size)
+        for res in forward_results:
+            res['chrom'] = chrom
+            res['motif'] = motif
+        results.extend(forward_results)
+        
+        # look for reverse complement occurrances (but store forward motif)
+        rev_motif = str(Seq(motif).reverse_complement())
+        reverse_results = find_motif_genomic_coordinates(sequence, rev_motif, buffer_size)
+        for res in reverse_results:
+            res['chrom'] = chrom
+            res['motif'] = motif  # Store forward motif, not reverse
+        results.extend(reverse_results)
+    
+    # collect all results into a dataframe
+    df_all = pd.DataFrame(results)
+    
+    if df_all.empty:
+        logging.warning("No motif instances found in sample.")
+        return
+
+    # order column to match bed format
+    df_all = df_all[['chrom', 'Buffer_Start', 'Buffer_End','motif', 'Motif_Start', 'Motif_End', 'Total_Repeats', 'Perfect_Repeats']]
+    # filter out regions with less than min number of perfect_repeats
+    df_all_filtered = df_all[df_all['Perfect_Repeats'] >= perfect_repeats].copy()
+    
+
+    # merge repeat regions per chrom that are in close proximity to be one region instead of two
+    merged_all = []
+    for contig in df_all_filtered['chrom'].unique():
+        df_sub = df_all_filtered[df_all_filtered['chrom'] == contig].copy()
+        merged = merge_adjacent_motifs(df_sub, max_gap)
+        merged_all.append(merged)
+
+    df_merged = pd.concat(merged_all, ignore_index=True)
+    df_merged = name_each_region(df_merged) 
+    
+    df_final = df_merged[['chrom', 'Buffer_Start', 'Buffer_End', 'region_name', 'motif']]
+    output_path = os.path.join(output_dir, 'microsatellite_coordinates.bed')
+    df_final.to_csv(output_path, sep='\t', index=False, header=False)
+
+    logging.info(f"Found {len(df_final)} microsatellite regions. Output written to {output_path}")
+    return df_final