telometer 2.0.0__tar.gz → 2.0.2__tar.gz

telometer-2.0.2/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2024 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telometer-2.0.2/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.2
+Name: telometer
+Version: 2.0.2
+Summary: Quantitative digital telomere measurement from nanopore long reads
+Author-email: "Santiago E. Sanchez" <santy.esanchez@gmail.com>
+License: Copyright (c) 2024 The Python Packaging Authority
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pysam
+Requires-Dist: regex
+Requires-Dist: scipy
+
+A simple tool for measuring chromosome-specific telomeres from long-read alignments.
+
+[Telometer Github](https://github.com/santiago-es/Telometer) 

telometer-2.0.2/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = [
+    "setuptools>=61,<76",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "telometer"
+version = "2.0.2"
+description = "Quantitative digital telomere measurement from nanopore long reads"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.8"
+license = { file = "LICENSE.txt" }
+
+authors = [
+    { name = "Santiago E. Sanchez", email = "santy.esanchez@gmail.com" }
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics"
+]
+
+dependencies = [
+    "numpy",
+    "pandas",
+    "pysam",
+    "regex",
+    "scipy"
+]
+
+
+[project.scripts]
+telometer = "telometer.telometer:run_telometer"
+
+
+[tool.setuptools]
+include-package-data = true
+
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["telometer", "telometer.*"]
+exclude = ["build", "build.*", "dist", "dist.*"]

telometer-2.0.2/telometer/__init__.py

@@ -0,0 +1,3 @@
+"""Telometer package."""
+
+__version__ = "2.0.2"

{telometer-2.0.0 → telometer-2.0.2}/telometer/telometer.py

@@ -1,24 +1,19 @@
 #!/usr/bin/env python3
-# Telometer v2.0: eight-feature baseline with optional variant detection and enrichment
-# Baseline changes retained: 01, 03, 07, 11, 12, 14, 15, 16
+# Telometer v2.0
+
 # Created by: Santiago E Sanchez
 # Artandi Lab, Stanford University, 2024
-# Measures telomeres from ONT or PacBio long reads aligned to a T2T genome assembly
+
+# Measures telomeres from ONT long reads
+
 # Simple Usage: telometer -b sorted_t2t.bam -o output.tsv
-# Optional enrichment: add -e to your existing Telometer command.
-# -e adds the sample-level telomeres_per_gb column and console totals. Each QNAME
-# contributes one consistent recorded full length, including soft/hard clips,
-# before any Telometer filter. Missing/conflicting lengths yield NA, not a
-# partial-denominator rate. This measures yield represented by the input BAM;
-# reads/bases removed upstream without retained metadata cannot be recovered.
-# Memory for -e scales with unique read IDs; -l is not a total-RSS limit.
 
-__version__ = "2.0"
+__version__ = "2.0.2"
 
 import pysam
 from pathlib import Path
-from variant_support_v2 import (BASE_COLUMNS, VARIANT_COLUMNS, TRACT_COLUMNS,
-    validate_variant_options, strict_runs, coverage_prefix, combined_window_density, summarize_variant)
+#from variant_support_v2 import (BASE_COLUMNS, VARIANT_COLUMNS, TRACT_COLUMNS,
+#    validate_variant_options, strict_runs, coverage_prefix, combined_window_density, summarize_variant)
 import regex as re
 import pandas as pd
 import time
@@ -27,7 +22,27 @@ import sys
 from multiprocessing import Pool, cpu_count
 import numpy as np
 from scipy.signal import savgol_filter
-from telometer_variant_support import alignment_fields, cached_findall, note, reverse_complement_iupac, stable_record_key
+#from telometer_variant_support import alignment_fields, cached_findall, note, reverse_complement_iupac, stable_record_key
+
+from .variant_support_v2 import (
+    BASE_COLUMNS,
+    VARIANT_COLUMNS,
+    TRACT_COLUMNS,
+    validate_variant_options,
+    strict_runs,
+    coverage_prefix,
+    combined_window_density,
+    summarize_variant,
+)
+
+from .telometer_variant_support import (
+    alignment_fields,
+    cached_findall,
+    note,
+    reverse_complement_iupac,
+    stable_record_key,
+)
+
 
 def reverse_complement(seq):
     complement = {'A': 'T', 'C': 'G', 'G': 'C', 'T': 'A', 'N': 'N'}

telometer-2.0.2/telometer/telometer_variant_support.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Small, explicit helpers used by isolated Telometer v1.0 patches."""
+from __future__ import annotations
+from array import array
+from collections import Counter
+from functools import lru_cache
+import hashlib
+import math
+import sqlite3
+import zlib
+
+import numpy as np
+import regex
+
+_COMPLEMENT = str.maketrans('ACGTRYSWKMBDHVNacgtryswkmbdhvn', 'TGCAYRSWMKVHDBNtgcayrswmkvhdbn')
+_ERROR_PROB = np.power(10.0, -np.arange(256, dtype=float) / 10.0)
+_DOUBLET = regex.compile(r'(?:TTAGGG){2}|(?:CCCTAA){2}')
+NOTES = Counter()
+RECOVERY_COUNTS = Counter()
+
+
+def reset_notes():
+    NOTES.clear()
+
+
+def note(key, value=1):
+    NOTES[key] += value
+
+
+def reverse_complement_iupac(seq):
+    return seq.translate(_COMPLEMENT)[::-1]
+
+
+def native_read_q(read):
+    if not read.has_tag('qs'):
+        return 0.0
+    try:
+        value = float(read.get_tag('qs'))
+    except (ValueError, TypeError):
+        return 0.0
+    return value if math.isfinite(value) else 0.0
+
+
+def probability_mean_q(qualities):
+    if not len(qualities):
+        return 0.0
+    q = np.asarray(qualities, dtype=np.uint8)
+    return float(-10.0 * np.log10(_ERROR_PROB[q].mean()))
+
+
+@lru_cache(maxsize=16)
+def _compiled(pattern):
+    return regex.compile(pattern)
+
+
+def cached_findall(pattern, text):
+    return _compiled(pattern).findall(text)
+
+
+def refine_doublet_boundaries(seq, start, end, radius=120):
+    left = max(0, start-radius)
+    right = min(len(seq), start+radius+12)
+    starts = [left+m.start() for m in _DOUBLET.finditer(seq[left:right], overlapped=True)
+              if abs(left+m.start()-start) <= radius]
+    left2 = max(0, end-radius-12)
+    right2 = min(len(seq), end+radius)
+    ends = [left2+m.end() for m in _DOUBLET.finditer(seq[left2:right2], overlapped=True)
+            if abs(left2+m.end()-end) <= radius]
+    if not starts or not ends:
+        note('boundary_unresolved')
+        return None
+    refined_start = min(starts, key=lambda x:(abs(x-start), x<start, x))
+    refined_end = min(ends, key=lambda x:(abs(x-end), x>end, x))
+    if refined_start >= refined_end:
+        note('boundary_empty_or_reversed')
+        return None
+    assert abs(refined_start-start) <= radius and abs(refined_end-end) <= radius
+    return refined_start, refined_end
+
+
+def flank_support(length, start, end, cigar, hardclips_as_soft=False):
+    left_terminal, right_terminal = start < 100, end > length-100
+    if not left_terminal and not right_terminal:
+        return False, 'none', 'not_terminal'
+    left_distance, right_distance = start, length-end
+    if left_terminal and right_terminal and left_distance == right_distance:
+        return False, 'ambiguous', 'equal_terminal_proximity'
+    side = 'left' if left_terminal and (not right_terminal or left_distance < right_distance) else 'right'
+    lo, hi = (end,end+50) if side == 'left' else (start-50,start)
+    if lo < 0 or hi > length:
+        return False, side, 'insufficient_proximal_sequence'
+    query, covered = 0, 0
+    for op, n in (cigar or []):
+        if op in (0,7,8):
+            covered += max(0, min(query+n,hi)-max(query,lo))
+        if op in (0,1,4,7,8) or (op == 5 and hardclips_as_soft):
+            query += n
+    return covered == 50, side, 'supported' if covered == 50 else 'proximal_flank_not_fully_match_aligned'
+
+
+def alignment_fields(read):
+    cigar = read.cigartuples or []
+    try:
+        alignment_score = float(read.get_tag('AS')) if read.has_tag('AS') else None
+        if alignment_score is not None and not math.isfinite(alignment_score):
+            alignment_score = None
+    except (TypeError, ValueError):
+        alignment_score = None
+    return {'reference_name':read.reference_name or '',
+            'reference_start':read.reference_start if read.reference_start is not None else -1,
+            'reference_end':read.reference_end if read.reference_end is not None else -1,
+            'is_reverse':bool(read.is_reverse), 'flag':int(read.flag), 'cigar':read.cigarstring or '',
+            'record_digest':hashlib.sha256(read.to_string().encode()).hexdigest(),
+            'mapping_quality':int(read.mapping_quality),
+            'alignment_class':2 if read.is_secondary else (1 if read.is_supplementary else 0),
+            'aligned_query_bases':sum(n for op,n in cigar if op in (0,7,8)),
+            'alignment_score':alignment_score}
+
+
+def stable_record_key(fields):
+    return (fields['reference_name'],fields['reference_start'],fields['reference_end'],
+            int(fields['is_reverse']),fields['flag'],fields['cigar'],fields['record_digest'])
+
+
+def length_neutral_key(fields):
+    negative_score = -fields['alignment_score'] if fields['alignment_score'] is not None else math.inf
+    return (-fields['mapping_quality'],fields['alignment_class'],-fields['aligned_query_bases'],
+            negative_score,stable_record_key(fields))
+
+
+@lru_cache(maxsize=4)
+def _donor_connection(path):
+    return sqlite3.connect(f'file:{path}?mode=ro', uri=True)
+
+
+class RecoveredRead:
+    """Sequence/quality view retaining the original alignment record and its identity."""
+    def __init__(self, original, sequence, qualities):
+        self._original = original
+        self.query_sequence = sequence
+        self.query_qualities = array('B', qualities)
+        self.recovered_full_sequence = True
+
+    def __getattr__(self, name):
+        return getattr(self._original, name)
+
+    def get_forward_sequence(self):
+        return reverse_complement_iupac(self.query_sequence) if self.is_reverse else self.query_sequence
+
+    def get_forward_qualities(self):
+        return self.query_qualities[::-1] if self.is_reverse else self.query_qualities
+
+
+def recover_record(read, donor_db):
+    cigar = read.cigartuples or []
+    hard = [(i,n) for i,(op,n) in enumerate(cigar) if op == 5]
+    seq, qualities = read.query_sequence, read.query_qualities
+    incomplete = bool(hard) or not seq or qualities is None or not len(qualities)
+    if not incomplete:
+        return read
+    RECOVERY_COUNTS['incomplete_records'] += 1
+    if not donor_db:
+        raise ValueError('Variant 06 needs an explicitly prepared donor database.')
+    row = _donor_connection(str(donor_db)).execute(
+        'SELECT sequence,qualities,length,conflict FROM donors WHERE read_id=?',(read.query_name,)).fetchone()
+    if row is None or row[3]:
+        RECOVERY_COUNTS['missing_or_conflicting_donor'] += 1
+        return None
+    if any(i not in (0,len(cigar)-1) for i,n in hard):
+        RECOVERY_COUNTS['internal_hard_clip'] += 1
+        return None
+    full_length = row[2]
+    leading_h = cigar[0][1] if cigar and cigar[0][0]==5 else 0
+    trailing_h = cigar[-1][1] if cigar and cigar[-1][0]==5 else 0
+    inferred_length = sum(n for op,n in cigar if op in (0,1,4,5,7,8))
+    if not cigar and seq:
+        inferred_length = len(seq)
+    if inferred_length != full_length:
+        RECOVERY_COUNTS['inferred_length_conflict'] += 1
+        return None
+    donor_sequence = zlib.decompress(row[0]).decode('ascii')
+    donor_quality = zlib.decompress(row[1])
+    if read.is_reverse:
+        donor_sequence = reverse_complement_iupac(donor_sequence)
+        donor_quality = donor_quality[::-1]
+    stop = full_length-trailing_h
+    expected_sequence = donor_sequence[leading_h:stop]
+    expected_quality = donor_quality[leading_h:stop]
+    if seq and seq != expected_sequence:
+        RECOVERY_COUNTS['retained_sequence_conflict'] += 1
+        return None
+    if qualities is not None and len(qualities) and bytes(qualities) != expected_quality:
+        RECOVERY_COUNTS['retained_quality_conflict'] += 1
+        return None
+    if len(donor_sequence) != full_length or len(donor_quality) != full_length:
+        raise AssertionError('Invalid donor database SEQ/QUAL length.')
+    RECOVERY_COUNTS['recovered_records'] += 1
+    return RecoveredRead(read,donor_sequence,donor_quality)

telometer-2.0.2/telometer/variant_support_v2.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""Exact 6-mer variant support and repeat-screened proximal-flank proxy.
+
+Coordinates in computations are relative to available SEQ in original sequencing
+orientation. Public *_forward coordinates add the original-orientation leading
+hard-clip offset, when present. No absent sequence is recovered or invented.
+"""
+from __future__ import annotations
+from functools import lru_cache
+import re
+import warnings
+from typing import NamedTuple
+import numpy as np
+from .telometer_variant_support import reverse_complement_iupac
+
+BASE_COLUMNS = ['chromosome', 'reference_start', 'reference_end', 'telomere_length',
+                'read_id', 'mapping_quality', 'read_length', 'arm', 'direction']
+VARIANT_COLUMNS = ['variant_motif', 'variant_present', 'variant_tract_count',
+                   'variant_supported_bp', 'variant_repeat_equivalents', 'pre_variant_bp',
+                   'pre_variant_status', 'anchor_status', 'telomeric_query_side',
+                   'weak_proximal_variant_evidence', 'variant_boundary_truncated', 'variant_overlap_flag']
+TRACT_COLUMNS = ['read_id', 'record_id', 'tract_id', 'query_start_forward', 'query_end_forward',
+                 'span_bp', 'supported_bp', 'nonoverlapping_units', 'mean_q', 'min_q',
+                 'boundary_left_truncated', 'boundary_right_truncated', 'touches_telomere_start',
+                 'touches_telomere_end', 'touches_query_start', 'touches_query_end',
+                 'sequence_left_missing', 'sequence_right_missing', 'overlap_flag', 'phase_template']
+
+
+class PeriodicRun(NamedTuple):
+    start: int
+    end: int
+    phase: str
+
+
+@lru_cache(maxsize=32)
+def motif_family(motif):
+    """Deduplicated rotations/RCs; deterministic, cached per process."""
+    motif = motif.upper()
+    rc = reverse_complement_iupac(motif)
+    return tuple(sorted({s[i:] + s[:i] for s in (motif, rc) for i in range(6)}))
+
+
+def minimum_period(motif):
+    return next(p for p in (1, 2, 3, 6) if motif == motif[:p] * (6//p))
+
+
+def validate_variant_options(motif=None, min_units=None, emit_warnings=True):
+    if motif is None:
+        if min_units is not None:
+            raise ValueError('--min-variant-units requires --variant-motif')
+        return None, 2
+    motif = str(motif).upper()
+    if re.fullmatch('[ACGT]{6}', motif) is None:
+        raise ValueError('--variant-motif must be exactly six A/C/G/T bases (not a regex)')
+    if motif in motif_family('TTAGGG'):
+        raise ValueError('The variant motif must not be canonical-equivalent under rotation/RC')
+    units = 2 if min_units is None else min_units
+    if isinstance(units, bool) or not isinstance(units, int) or units < 2:
+        raise ValueError('--min-variant-units must be an integer at least 2')
+    if emit_warnings and (minimum_period(motif) < 6 or len(set(motif)) <= 2):
+        warnings.warn('Low-complexity variant motif: periodicity/base diversity may reduce specificity; '
+                      'exact support is not biological validation.', UserWarning, stacklevel=2)
+    return motif, units
+
+
+@lru_cache(maxsize=32)
+def _motif_search(motif):
+    family = motif_family(motif)
+    # Lookahead enumerates overlapping 6-bp hits, never consumes a gap.
+    pattern = re.compile('(?=(' + '|'.join(family) + '))')
+    # A phase key is the six-base periodic template at absolute query indices mod 6.
+    phase_keys = {(m, r): (m[-r:] + m[:-r] if r else m) for m in family for r in range(6)}
+    return pattern, phase_keys
+
+
+def strict_runs(seq, motif, min_units=2):
+    """Maximal phase-consistent covered runs; no unsupported-gap/phase bridging.
+
+    Adjacent/overlapping exact hits may join ONLY within the identical global
+    periodic template. Distinct templates remain separate, including overlaps.
+    Partial end units can be covered by overlapping exact hits; admission still
+    requires floor(span/6) >= min_units non-overlapping complete units.
+    """
+    if not seq:
+        return []
+    pattern, phase_keys = _motif_search(motif.upper())
+    current, finished = {}, []
+    for hit in pattern.finditer(seq):
+        start, end = hit.start(), hit.start() + 6
+        phase = phase_keys[(hit.group(1), start % 6)]
+        previous = current.get(phase)
+        if previous is not None and start <= previous[1]:
+            current[phase] = (previous[0], max(previous[1], end))
+        else:
+            if previous is not None:
+                finished.append(PeriodicRun(previous[0], previous[1], phase))
+            current[phase] = (start, end)
+    finished.extend(PeriodicRun(s, e, phase) for phase, (s, e) in current.items())
+    # Same-template overlaps/containments already coalesced, distinct phases are not.
+    return sorted(set(r for r in finished if r.end-r.start >= 6*min_units))
+
+
+def union_intervals(intervals):
+    merged = []
+    for s, e in sorted((int(s), int(e)) for s, e in intervals if e > s):
+        if merged and s <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(e, merged[-1][1]))
+        else:
+            merged.append((s, e))
+    return merged
+
+
+def union_bp(intervals):
+    return sum(e-s for s, e in union_intervals(intervals))
+
+
+def overlap_flags(intervals):
+    # Sorted sweep: mark every member of a positive-overlap group, not adjacency.
+    indexed = sorted((s, e, i) for i, (s, e) in enumerate(intervals))
+    flags = [False] * len(indexed)
+    active = []
+    for s, e, i in indexed:
+        active = [(pe, pi) for pe, pi in active if pe > s]
+        for _, pi in active:
+            flags[pi] = flags[i] = True
+        active.append((e, i))
+    return flags
+
+
+def coverage_prefix(length, runs):
+    if not runs:
+        return None
+    mask = np.zeros(length, dtype=np.uint8)
+    for run in runs:
+        mask[run.start:run.end] = 1
+    prefix = np.empty(length+1, dtype=np.int64)
+    prefix[0] = 0
+    np.cumsum(mask, out=prefix[1:])
+    return prefix
+
+
+@lru_cache(maxsize=32)
+def _canonical_pattern(pattern):
+    # Standard re and regex have identical semantics for this literal alternation.
+    return re.compile(pattern)
+
+
+def combined_window_density(window_seq, window_start, canonical_pattern, canonical_count, prefix):
+    """Augment the ORIGINAL non-overlapping canonical-window matches, not all registers."""
+    if prefix is None:
+        return canonical_count * 6 / len(window_seq)
+    end = window_start + len(window_seq)
+    variant_bp = int(prefix[end]-prefix[window_start])
+    if variant_bp == 0:
+        return canonical_count * 6 / len(window_seq)
+    shared = sum(int(prefix[window_start+m.end()] - prefix[window_start+m.start()])
+                 for m in _canonical_pattern(canonical_pattern).finditer(window_seq))
+    return (canonical_count * 6 + variant_bp - shared) / len(window_seq)
+
+
+def stored_to_forward(length, start, end, is_reverse, offset=0):
+    if not (0 <= start <= end <= length):
+        raise ValueError('Query interval is out of bounds')
+    s, e = (length-end, length-start) if is_reverse else (start, end)
+    return s+offset, e+offset
+
+
+def clipping(cigar, is_reverse):
+    cigar = cigar or []
+    left_h = cigar[0][1] if cigar and cigar[0][0] == 5 else 0
+    right_h = cigar[-1][1] if cigar and cigar[-1][0] == 5 else 0
+    soft = [n for op, n in cigar if op == 4]
+    return {'query_forward_offset': right_h if is_reverse else left_h,
+            'sequence_left_missing': bool(right_h if is_reverse else left_h),
+            'sequence_right_missing': bool(left_h if is_reverse else right_h),
+            'hard_clip_left': left_h, 'hard_clip_right': right_h,
+            'hard_clipped_sequence': bool(left_h or right_h), 'soft_clipped_bases': sum(soft)}
+
+
+def aligned_intervals_forward(length, cigar, is_reverse):
+    query, intervals = 0, []
+    for op, n in cigar or []:
+        if op in (0, 7, 8):
+            intervals.append(stored_to_forward(length, query, query+n, is_reverse))
+        if op in (0, 1, 4, 7, 8):
+            query += n
+    if cigar and query != length:
+        raise ValueError('CIGAR query-consuming length does not match available SEQ')
+    return union_intervals(intervals)
+
+
+def evaluate_anchor(length, start, end, cigar, is_reverse, repeat_intervals):
+    """Require exactly one terminal side, 50 M/=/X bases, and no strict repeat run."""
+    if not (0 <= start < end <= length):
+        raise ValueError('Invalid telomere interval')
+    left, right = start < 100, end > length-100
+    out = {'telomeric_query_side': 'ambiguous' if left and right else ('left' if left else 'right' if right else 'none'),
+           'anchor_status': 'ambiguous_terminal_side', 'proximal_boundary_local': None,
+           'flank_start_local': None, 'flank_end_local': None, 'flank_aligned_bp': None,
+           'flank_repeat_intersection': None}
+    if left == right:
+        return out
+    lo, hi = (end, end+50) if left else (start-50, start)
+    out.update(proximal_boundary_local=end if left else start, flank_start_local=lo, flank_end_local=hi)
+    if lo < 0 or hi > length:
+        out['anchor_status'] = 'insufficient_flank'
+        return out
+    aligned = aligned_intervals_forward(length, cigar, is_reverse)
+    covered = sum(max(0, min(hi, e)-max(lo, s)) for s, e in aligned)
+    repeated = any(s < hi and e > lo for s, e in repeat_intervals)
+    out.update(flank_aligned_bp=covered, flank_repeat_intersection=bool(repeated))
+    out['anchor_status'] = ('unaligned_flank' if covered != 50 else
+                            'repeat_supported_flank' if repeated else 'supported_proxy')
+    return out
+
+
+def common_distance(intervals, start, end, anchor):
+    if not intervals:
+        return None, 'no_supported_tract'
+    if anchor['anchor_status'] != 'supported_proxy':
+        return None, 'anchor_unresolved'
+    if anchor['telomeric_query_side'] == 'right':
+        distance = min(s for s, e in intervals)-start
+    else:
+        distance = end-max(e for s, e in intervals)
+    if not 0 <= distance <= end-start:
+        raise AssertionError('Invalid pre-variant distance')
+    return int(distance), 'estimated_proxy'
+
+
+def quality_diagnostics(qualities, start, end):
+    if qualities is None or len(qualities) < end:
+        return None, None
+    values = qualities[start:end]
+    return (float(sum(values)/len(values)), int(min(values))) if len(values) else (None, None)
+
+
+def characterize_intervals(seq, qualities, start, end, intervals, motif, cigar, is_reverse,
+                           read_id, record_id, min_units=2, phases=None, strict_definition=True):
+    """Annotate supplied intervals, preserving a comparator's intervals unchanged.
+
+    The flank always screens canonical + variant runs at TWO units, even if the
+    chosen variant-admission threshold is higher. It is not a mapping-uniqueness test.
+    """
+    length = len(seq)
+    if any(not start <= s < e <= end for s, e in intervals):
+        raise AssertionError('Tract lies outside the selected telomere interval')
+    full_weak = strict_runs(seq, motif, min_units=1)
+    strict_repeat_intervals = [(r.start, r.end) for r in full_weak if r.end-r.start >= 12]
+    strict_repeat_intervals.extend((r.start, r.end) for r in strict_runs(seq, 'TTAGGG', 2))
+    anchor = evaluate_anchor(length, start, end, cigar, is_reverse, strict_repeat_intervals)
+    distance, status = common_distance(intervals, start, end, anchor)
+    clip = clipping(cigar, is_reverse)
+    offset = clip['query_forward_offset']
+    overlaps = overlap_flags(intervals)
+    phases = phases or ['']*len(intervals)
+    rows = []
+    for i, ((s, e), phase) in enumerate(zip(intervals, phases), 1):
+        left_cut = any(r.start < s == start < r.end for r in full_weak)
+        right_cut = any(r.start < e == end < r.end for r in full_weak)
+        mean_q, min_q = quality_diagnostics(qualities, s, e)
+        rows.append(dict(read_id=read_id, record_id=record_id, tract_id=i,
+                         query_start_forward=s+offset, query_end_forward=e+offset,
+                         span_bp=e-s, supported_bp=e-s,
+                         nonoverlapping_units=(e-s)//6 if strict_definition else None,
+                         mean_q=mean_q, min_q=min_q, boundary_left_truncated=bool(left_cut),
+                         boundary_right_truncated=bool(right_cut), touches_telomere_start=s == start,
+                         touches_telomere_end=e == end, touches_query_start=s == 0, touches_query_end=e == length,
+                         sequence_left_missing=clip['sequence_left_missing'], sequence_right_missing=clip['sequence_right_missing'],
+                         overlap_flag=overlaps[i-1], phase_template=phase))
+    local_weak = strict_runs(seq[start:end], motif, 1)
+    weak_intervals = [(r.start+start, r.end+start) for r in local_weak if r.end-r.start < 6*min_units]
+    # Includes extraction-boundary fragments shorter than one complete motif.
+    fragments = [(max(start, r.start), min(end, r.end)) for r in full_weak if r.start < end and r.end > start]
+    weak_intervals += [(s, e) for s, e in fragments if 0 < e-s < 6*min_units]
+    side = anchor['telomeric_query_side']
+    proximal_region = ((start, min(s for s, e in intervals)) if intervals else (start, end)) if side == 'right' else (
+                      (max(e for s, e in intervals), end) if intervals else (start, end))
+    weak_flag = (any(s < proximal_region[1] and e > proximal_region[0] for s, e in weak_intervals)
+                 if side in ('left', 'right') else None)
+    boundary_truncated = any(r.start < start < r.end or r.start < end < r.end for r in full_weak)
+    boundary_truncated |= any((r.start == 0 and clip['sequence_left_missing']) or
+                              (r.end == length and clip['sequence_right_missing']) for r in full_weak
+                              if r.start < end and r.end > start)
+    coverage = union_bp(intervals)
+    public = dict(variant_motif=motif, variant_present=bool(intervals), variant_tract_count=len(intervals),
+                  variant_supported_bp=coverage, variant_repeat_equivalents=coverage/6,
+                  pre_variant_bp=distance, pre_variant_status=status, anchor_status=anchor['anchor_status'],
+                  telomeric_query_side=side, weak_proximal_variant_evidence=weak_flag,
+                  variant_boundary_truncated=bool(boundary_truncated), variant_overlap_flag=any(overlaps))
+    details = {**clip, **anchor, 'query_start_forward': start+offset, 'query_end_forward': end+offset,
+               'query_available_start_forward': offset, 'query_available_end_forward': length+offset,
+               'proximal_boundary_forward': (anchor['proximal_boundary_local']+offset
+                                              if anchor['proximal_boundary_local'] is not None else None),
+               'local_query_start': start, 'local_query_end': end,
+               'missing_sequence': False, 'missing_quality': qualities is None,
+               'native_subtelomeric_junction_verified': False}
+    return public, rows, details
+
+
+def summarize_variant(seq, qualities, start, end, motif, min_units, read_data):
+    # Requalification uses only the final extracted telomere, never outside support.
+    local = strict_runs(seq[start:end], motif, min_units)
+    intervals = [(r.start+start, r.end+start) for r in local]
+    return characterize_intervals(seq, qualities, start, end, intervals, motif,
+                                  read_data.get('_variant_cigar', []), read_data['is_reverse'],
+                                  read_data['query_name'], read_data['_ranking_fields']['record_digest'],
+                                  min_units=min_units, phases=[r.phase for r in local], strict_definition=True)

telometer-2.0.2/telometer.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.2
+Name: telometer
+Version: 2.0.2
+Summary: Quantitative digital telomere measurement from nanopore long reads
+Author-email: "Santiago E. Sanchez" <santy.esanchez@gmail.com>
+License: Copyright (c) 2024 The Python Packaging Authority
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pysam
+Requires-Dist: regex
+Requires-Dist: scipy
+
+A simple tool for measuring chromosome-specific telomeres from long-read alignments.
+
+[Telometer Github](https://github.com/santiago-es/Telometer) 

{telometer-2.0.0 → telometer-2.0.2}/telometer.egg-info/SOURCES.txt

@@ -1,9 +1,13 @@
+LICENSE.txt
 README.md
 pyproject.toml
 telometer/__init__.py
 telometer/telometer.py
+telometer/telometer_variant_support.py
+telometer/variant_support_v2.py
 telometer.egg-info/PKG-INFO
 telometer.egg-info/SOURCES.txt
 telometer.egg-info/dependency_links.txt
+telometer.egg-info/entry_points.txt
 telometer.egg-info/requires.txt
 telometer.egg-info/top_level.txt

telometer-2.0.2/telometer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+telometer = telometer.telometer:run_telometer

telometer-2.0.2/telometer.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+pandas
+pysam
+regex
+scipy

telometer-2.0.0/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.4
-Name: telometer
-Version: 2.0.0
-Summary: Quantitative digital telomere measurement from nanopore long-reads
-Author-email: "Santiago E. Sanchez" <santy.esanchez@gmail.com>
-License-Expression: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-Requires-Dist: requests
-Requires-Dist: numpy
-
-A simple tool for measuring chromosome-specific telomeres from long-read alignments.
-
-[Telometer Github](https://github.com/santiago-es/Telometer) 

telometer-2.0.0/pyproject.toml

@@ -1,31 +0,0 @@
-[build-system]
-requires = ["setuptools>=77.0.3", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "telometer"
-version = "2.0.0"
-description = "Quantitative digital telomere measurement from nanopore long-reads"
-readme = "README.md"
-requires-python = ">=3.7"
-license = "MIT"
-license-files = ["LICENSE"]
-
-authors = [
-    { name = "Santiago E. Sanchez", email = "santy.esanchez@gmail.com" }
-]
-
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "Operating System :: OS Independent"
-]
-
-dependencies = [
-    "requests",
-    "numpy"
-]
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["telometer*"]
-exclude = ["build*", "dist*"]

telometer-2.0.0/telometer/__init__.py

@@ -1,34 +0,0 @@
-__version__ = '1.01'
-__author__ = 'Santiago E Sanchez'
-__email__ = 'santy.esanchez@gmail.com'
-__license__ = 'MIT'
-
-import logging
-from .telometer import (
-    process_bam_file,
-    measure_telomere_length,
-    identify_telomere_regions,
-    get_telomere_repeats,
-    reverse_complement,
-    process_read_wrapper,
-    process_read,
-    detect_discontinuities,
-    check_gap,
-    run_telometer
-)
-
-logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
-
-__all__ = [
-    'process_bam_file',
-    'measure_telomere_length',
-    'identify_telomere_regions',
-    'get_telomere_repeats',
-    'reverse_complement',
-    'process_read_wrapper',
-    'process_read',
-    'detect_discontinuities',
-    'check_gap',
-    'run_telometer'
-]
-

telometer-2.0.0/telometer.egg-info/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.4
-Name: telometer
-Version: 2.0.0
-Summary: Quantitative digital telomere measurement from nanopore long-reads
-Author-email: "Santiago E. Sanchez" <santy.esanchez@gmail.com>
-License-Expression: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-Requires-Dist: requests
-Requires-Dist: numpy
-
-A simple tool for measuring chromosome-specific telomeres from long-read alignments.
-
-[Telometer Github](https://github.com/santiago-es/Telometer) 

telometer-2.0.0/telometer.egg-info/requires.txt

@@ -1,2 +0,0 @@
-requests
-numpy