telometer 2.0.1__tar.gz → 2.0.3__tar.gz

telometer-2.0.3/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 santiago-es
+
+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.3/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.1
+Name: telometer
+Version: 2.0.3
+Summary: Quantitative digital telomere measurement from nanopore long reads
+Author-email: "Santiago E. Sanchez" <santy.esanchez@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2023 santiago-es
+        
+        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
+
+# Telometer 2.0.3
+
+A tool for measuring chromosome-specific telomeres from long-read alignments.
+
+[Telometer Github](https://github.com/santiago-es/Telometer)
+
+Version 2.0.3 simplifies the main variant-output table and adds individual tract lengths and a fractional first-tract position. Telomere measurement, alignment selection, variant-tract qualification, and enrichment accounting are unchanged from the uploaded 2.0.2 baseline.
+
+## Install and run
+
+The distribution retains its Python **>=3.8** declaration and unpinned numpy, pandas, pysam, regex, and scipy dependencies. Validation for this revision uses **Python 3.11.13**; this does not establish compatibility with older interpreters or every platform/dependency combination. The standalone bundle includes the previously tested dependency pins in `requirements.txt`.
+
+In an activated Python environment, install a downloaded release file:
+
+```bash
+uv pip install ./telometer-2.0.3-py3-none-any.whl
+# Or build/install the source distribution:
+uv pip install ./telometer-2.0.3.tar.gz
+
+telometer --version
+```
+
+The version command prints `Telometer v2.0.3`. Run on a sorted BAM aligned to a confirmed compatible reference:
+
+```bash
+# WGS; use -m 1000 for telomere capture libraries.
+telometer -b sample.sorted.bam -o telomeres.tsv -m 4000 -g 20 -t 2 -l 1
+
+# Optional variant motif and independently optional enrichment:
+telometer -b sample.sorted.bam -o telomeres_variants.tsv -m 4000 -g 20 -t 2 -l 1 \
+  --variant-motif TGCGGT --min-variant-units 2 -e
+```
+
+`TGCGGT` is an example, not an inferred or default motif. Both optional features are off unless requested. `-e` / `--enrichment` is a Boolean switch with no value. The existing minimum-length default is 1000 bp; the gap default is 20. `-l` is a nominal batch-size setting in GiB, **not a total-memory limit**. With enrichment enabled, memory also scales with the number of unique read IDs. Choose resources using a representative subset.
+
+The console entry point is `telometer.telometer:run_telometer`. Package-context alternatives are `python -m telometer.telometer` and `from telometer.telometer import process_bam_file`. There is no `python -m telometer` launcher or root-level function re-export in this package.
+
+For the standalone ZIP, extract **all five files together**, install its requirements, and invoke `python telometer.py`. Its two helper modules must remain adjacent to the caller. The separate drop-in package module uses relative imports and is not a self-contained standalone script.
+
+## Main TSV
+
+With variant mode and enrichment both enabled, columns are exactly:
+
+```text
+chromosome
+reference_start
+reference_end
+telomere_length
+read_id
+mapping_quality
+read_length
+arm
+direction
+variant_motif
+variant_present
+variant_tract_count
+pre_variant_bp
+telomeres_per_gb
+variant_tract_lengths
+percent_pre_variant
+```
+
+Without `-e`, `telomeres_per_gb` is omitted. Without variant mode, all variant-specific columns are omitted. The four mode widths are **9 / 10 / 15 / 16** for neither / enrichment only / variants only / both. Empty tables retain the appropriate headers. Missing values in the main TSV are the literal **`NA`**; genuine zeros are preserved. Main row order may vary across worker runs, so compare by read ID.
+
+### Individual tract lengths
+
+`variant_tract_lengths` contains integer base-pair spans, separated by commas without spaces, in the existing companion `tract_id` order (increasing original-read query coordinates). There is one entry per qualifying tract. These are spans, not six-base repeat counts or merged/union coverage. Separately counted overlapping tracts remain separate, and lengths are not rounded to multiples of six. Reads without qualifying tracts have `NA`.
+
+### Fractional first-tract position
+
+`percent_pre_variant` is a **0–1 fraction**, not a 0–100 percentage. It describes the first qualifying tract's position from the called telomere's subtelomeric-facing end toward its distal end. In the existing original-orientation coordinate frame, let `T0` and `T1` be the selected telomere boundaries:
+
+- Right-terminal telomere: `(minimum tract start - T0) / telomere_length`.
+- Left-terminal telomere: `(T1 - maximum tract end) / telomere_length`.
+
+The coordinate frame includes consistent recorded hard-clip offsets. No qualifying tract or an ambiguous/unidentifiable terminal side gives `NA`. A tract at the proximal boundary gives a genuine zero. The lengths list stays in query-coordinate order even when the proximal-first tract is its last entry.
+
+Unlike the unchanged `pre_variant_bp`, the new fraction **does not require a supported alignment/repeat-free-flank anchor**. It can therefore be numeric when `pre_variant_bp` is `NA`. It measures position within the called telomere interval, not a verified physical subtelomeric junction or historical telomere length. Detection and tract-support thresholds are unchanged.
+
+## Companion table and enrichment
+
+Variant mode still writes `<output_stem>_variant_tracts.tsv` with its unchanged 20-column schema, per-tract values, and missing-value formatting. The eight removed main-table coverage/diagnostic fields are not used to change calls or suppress internal diagnostics. Use a fresh output stem to avoid confusing an old companion with a new variant-disabled run.
+
+Enrichment remains:
+
+`final measured unique read-ID count * 1,000,000,000 / nonredundant recorded read bases in the BAM`
+
+Each QNAME contributes one consistent recorded full length before filtering; repeated alignments do not multiply bases. Query-consuming CIGAR operations and recorded hard clips determine full length when available. Unresolved/conflicting lengths, unusable IDs, or paired-end input can make the aggregate unavailable; valid measurements are still written with `NA` enrichment. Positive recorded bases with zero calls give rate zero; an empty/zero-base BAM has unavailable rate. The sample-wide value is repeated on measured rows, not calculated independently per read. Preserve the console log for sample totals when the output has no rows.
+
+The BAM cannot recover reads removed upstream or trimming that is absent from its metadata. This rate is not necessarily total instrument yield or a fold-enrichment comparison. Software regression checks are not independent biological validation of variant status, telomere boundaries, or positional interpretation.
+
+## Build and manual publication
+
+The supplied flat layout and `setuptools>=61,<76` backend policy are retained. Build in an activated environment:
+
+```bash
+uv pip install "build==1.5.0"
+python -m build
+```
+
+Use current Twine and packaging when checking metadata:
+
+```bash
+uv pip install --upgrade "twine>=6.1.0" "packaging>=24.2"
+python -m twine check --strict dist/telometer-2.0.3-py3-none-any.whl dist/telometer-2.0.3.tar.gz
+```
+
+Publishing is a separate maintainer action; these files do not update GitHub or PyPI automatically. The release is MIT licensed under the restored Telometer notice in `LICENSE.txt`.

telometer-2.0.3/README.md

@@ -0,0 +1,108 @@
+# Telometer 2.0.3
+
+A tool for measuring chromosome-specific telomeres from long-read alignments.
+
+[Telometer Github](https://github.com/santiago-es/Telometer)
+
+Version 2.0.3 simplifies the main variant-output table and adds individual tract lengths and a fractional first-tract position. Telomere measurement, alignment selection, variant-tract qualification, and enrichment accounting are unchanged from the uploaded 2.0.2 baseline.
+
+## Install and run
+
+The distribution retains its Python **>=3.8** declaration and unpinned numpy, pandas, pysam, regex, and scipy dependencies. Validation for this revision uses **Python 3.11.13**; this does not establish compatibility with older interpreters or every platform/dependency combination. The standalone bundle includes the previously tested dependency pins in `requirements.txt`.
+
+In an activated Python environment, install a downloaded release file:
+
+```bash
+uv pip install ./telometer-2.0.3-py3-none-any.whl
+# Or build/install the source distribution:
+uv pip install ./telometer-2.0.3.tar.gz
+
+telometer --version
+```
+
+The version command prints `Telometer v2.0.3`. Run on a sorted BAM aligned to a confirmed compatible reference:
+
+```bash
+# WGS; use -m 1000 for telomere capture libraries.
+telometer -b sample.sorted.bam -o telomeres.tsv -m 4000 -g 20 -t 2 -l 1
+
+# Optional variant motif and independently optional enrichment:
+telometer -b sample.sorted.bam -o telomeres_variants.tsv -m 4000 -g 20 -t 2 -l 1 \
+  --variant-motif TGCGGT --min-variant-units 2 -e
+```
+
+`TGCGGT` is an example, not an inferred or default motif. Both optional features are off unless requested. `-e` / `--enrichment` is a Boolean switch with no value. The existing minimum-length default is 1000 bp; the gap default is 20. `-l` is a nominal batch-size setting in GiB, **not a total-memory limit**. With enrichment enabled, memory also scales with the number of unique read IDs. Choose resources using a representative subset.
+
+The console entry point is `telometer.telometer:run_telometer`. Package-context alternatives are `python -m telometer.telometer` and `from telometer.telometer import process_bam_file`. There is no `python -m telometer` launcher or root-level function re-export in this package.
+
+For the standalone ZIP, extract **all five files together**, install its requirements, and invoke `python telometer.py`. Its two helper modules must remain adjacent to the caller. The separate drop-in package module uses relative imports and is not a self-contained standalone script.
+
+## Main TSV
+
+With variant mode and enrichment both enabled, columns are exactly:
+
+```text
+chromosome
+reference_start
+reference_end
+telomere_length
+read_id
+mapping_quality
+read_length
+arm
+direction
+variant_motif
+variant_present
+variant_tract_count
+pre_variant_bp
+telomeres_per_gb
+variant_tract_lengths
+percent_pre_variant
+```
+
+Without `-e`, `telomeres_per_gb` is omitted. Without variant mode, all variant-specific columns are omitted. The four mode widths are **9 / 10 / 15 / 16** for neither / enrichment only / variants only / both. Empty tables retain the appropriate headers. Missing values in the main TSV are the literal **`NA`**; genuine zeros are preserved. Main row order may vary across worker runs, so compare by read ID.
+
+### Individual tract lengths
+
+`variant_tract_lengths` contains integer base-pair spans, separated by commas without spaces, in the existing companion `tract_id` order (increasing original-read query coordinates). There is one entry per qualifying tract. These are spans, not six-base repeat counts or merged/union coverage. Separately counted overlapping tracts remain separate, and lengths are not rounded to multiples of six. Reads without qualifying tracts have `NA`.
+
+### Fractional first-tract position
+
+`percent_pre_variant` is a **0–1 fraction**, not a 0–100 percentage. It describes the first qualifying tract's position from the called telomere's subtelomeric-facing end toward its distal end. In the existing original-orientation coordinate frame, let `T0` and `T1` be the selected telomere boundaries:
+
+- Right-terminal telomere: `(minimum tract start - T0) / telomere_length`.
+- Left-terminal telomere: `(T1 - maximum tract end) / telomere_length`.
+
+The coordinate frame includes consistent recorded hard-clip offsets. No qualifying tract or an ambiguous/unidentifiable terminal side gives `NA`. A tract at the proximal boundary gives a genuine zero. The lengths list stays in query-coordinate order even when the proximal-first tract is its last entry.
+
+Unlike the unchanged `pre_variant_bp`, the new fraction **does not require a supported alignment/repeat-free-flank anchor**. It can therefore be numeric when `pre_variant_bp` is `NA`. It measures position within the called telomere interval, not a verified physical subtelomeric junction or historical telomere length. Detection and tract-support thresholds are unchanged.
+
+## Companion table and enrichment
+
+Variant mode still writes `<output_stem>_variant_tracts.tsv` with its unchanged 20-column schema, per-tract values, and missing-value formatting. The eight removed main-table coverage/diagnostic fields are not used to change calls or suppress internal diagnostics. Use a fresh output stem to avoid confusing an old companion with a new variant-disabled run.
+
+Enrichment remains:
+
+`final measured unique read-ID count * 1,000,000,000 / nonredundant recorded read bases in the BAM`
+
+Each QNAME contributes one consistent recorded full length before filtering; repeated alignments do not multiply bases. Query-consuming CIGAR operations and recorded hard clips determine full length when available. Unresolved/conflicting lengths, unusable IDs, or paired-end input can make the aggregate unavailable; valid measurements are still written with `NA` enrichment. Positive recorded bases with zero calls give rate zero; an empty/zero-base BAM has unavailable rate. The sample-wide value is repeated on measured rows, not calculated independently per read. Preserve the console log for sample totals when the output has no rows.
+
+The BAM cannot recover reads removed upstream or trimming that is absent from its metadata. This rate is not necessarily total instrument yield or a fold-enrichment comparison. Software regression checks are not independent biological validation of variant status, telomere boundaries, or positional interpretation.
+
+## Build and manual publication
+
+The supplied flat layout and `setuptools>=61,<76` backend policy are retained. Build in an activated environment:
+
+```bash
+uv pip install "build==1.5.0"
+python -m build
+```
+
+Use current Twine and packaging when checking metadata:
+
+```bash
+uv pip install --upgrade "twine>=6.1.0" "packaging>=24.2"
+python -m twine check --strict dist/telometer-2.0.3-py3-none-any.whl dist/telometer-2.0.3.tar.gz
+```
+
+Publishing is a separate maintainer action; these files do not update GitHub or PyPI automatically. The release is MIT licensed under the restored Telometer notice in `LICENSE.txt`.

telometer-2.0.3/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = [
+    "setuptools>=61,<76",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "telometer"
+version = "2.0.3"
+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.3/telometer/__init__.py

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

{telometer-2.0.1 → telometer-2.0.3}/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.3
+
 # 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.3"
 
 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'}
@@ -339,6 +354,56 @@ class EnrichmentCounter:
                 'warning': 'Enrichment unavailable: ' + '; '.join(reasons) if reasons else None}
 
 
+_MAIN_VARIANT_COLUMNS = ['variant_motif', 'variant_present', 'variant_tract_count', 'pre_variant_bp']
+
+
+def _variant_output_fields(read_result):
+    """Format existing winning tracts without changing calls or anchor checks.
+
+    The fraction uses the called telomere's proximal-facing boundary, independently
+    of whether the original pre_variant_bp proxy passes its stricter anchor gates.
+    All coordinates already share the original-read frame and hard-clip offset.
+    """
+    tracts = read_result['_variant_tracts']
+    if (len(tracts) != read_result['variant_tract_count'] or
+            bool(tracts) != read_result['variant_present']):
+        raise ValueError('Variant tract count/presence disagrees with the existing tract rows')
+    if not tracts:
+        return None, None
+
+    details = read_result['_variant_details']
+    start, end = details['query_start_forward'], details['query_end_forward']
+    telomere_length = read_result['telomere_length']
+    if not 0 <= start < end or telomere_length <= 0 or end-start != telomere_length:
+        raise ValueError('Inconsistent called-telomere coordinates for variant output')
+
+    lengths = []
+    previous_start = None
+    for index, tract in enumerate(tracts, 1):
+        tract_start, tract_end = tract['query_start_forward'], tract['query_end_forward']
+        span = tract['span_bp']
+        if (not isinstance(span, int) or isinstance(span, bool) or
+                not start <= tract_start < tract_end <= end or span != tract_end-tract_start):
+            raise ValueError('Inconsistent variant tract coordinates or base-pair span')
+        if tract['tract_id'] != index or (previous_start is not None and tract_start < previous_start):
+            raise ValueError('Variant tract rows are not in their existing tract-ID/query order')
+        lengths.append(str(span))
+        previous_start = tract_start
+
+    length_list = ','.join(lengths)
+    side = details['telomeric_query_side']
+    if side == 'right':
+        distance = min(tract['query_start_forward'] for tract in tracts)-start
+    elif side == 'left':
+        distance = end-max(tract['query_end_forward'] for tract in tracts)
+    else:
+        return length_list, None
+    fraction = distance / telomere_length
+    if not 0 <= fraction <= 1:
+        raise ValueError('Variant fractional position lies outside the called telomere')
+    return length_list, fraction
+
+
 def process_bam_file(bam_file_path, output_file_path, max_gap_length=20, min_read_len=1000, num_processes=8, memory_limit_gb=8,
                      variant_motif=None, min_variant_units=None, enrichment=False):
     variant_motif, min_variant_units = validate_variant_options(variant_motif, min_variant_units)
@@ -432,11 +497,16 @@ def process_bam_file(bam_file_path, output_file_path, max_gap_length=20, min_rea
     bam_file.close()
 
     enrichment_summary = enrichment_counter.summarize(len(read_results)) if enrichment_counter is not None else None
-    results_df = pd.DataFrame(list(read_results.values()), columns=BASE_COLUMNS + (VARIANT_COLUMNS if variant_motif is not None else []))
+    output_records = list(read_results.values())
+    results_df = pd.DataFrame(output_records, columns=BASE_COLUMNS + (_MAIN_VARIANT_COLUMNS if variant_motif is not None else []))
     if enrichment_summary is not None:
         rate = enrichment_summary['telomeres_per_gb']
         results_df['telomeres_per_gb'] = rate if rate is not None else np.nan
-    results_df.to_csv(output_file_path, sep='\t', index=False)
+    if variant_motif is not None:
+        variant_output = [_variant_output_fields(result) for result in output_records]
+        results_df['variant_tract_lengths'] = [fields[0] for fields in variant_output]
+        results_df['percent_pre_variant'] = [fields[1] for fields in variant_output]
+    results_df.to_csv(output_file_path, sep='\t', index=False, na_rep='NA')
     if variant_motif is not None:
         tract_rows = [tract for result in read_results.values() for tract in result['_variant_tracts']]
         tract_path = Path(output_file_path).with_name(Path(output_file_path).stem + '_variant_tracts.tsv')

{telometer-2.0.1 → telometer-2.0.3}/telometer/variant_support_v2.py

@@ -11,7 +11,7 @@ import re
 import warnings
 from typing import NamedTuple
 import numpy as np
-from telometer_variant_support import reverse_complement_iupac
+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']

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

@@ -0,0 +1,155 @@
+Metadata-Version: 2.1
+Name: telometer
+Version: 2.0.3
+Summary: Quantitative digital telomere measurement from nanopore long reads
+Author-email: "Santiago E. Sanchez" <santy.esanchez@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2023 santiago-es
+        
+        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
+
+# Telometer 2.0.3
+
+A tool for measuring chromosome-specific telomeres from long-read alignments.
+
+[Telometer Github](https://github.com/santiago-es/Telometer)
+
+Version 2.0.3 simplifies the main variant-output table and adds individual tract lengths and a fractional first-tract position. Telomere measurement, alignment selection, variant-tract qualification, and enrichment accounting are unchanged from the uploaded 2.0.2 baseline.
+
+## Install and run
+
+The distribution retains its Python **>=3.8** declaration and unpinned numpy, pandas, pysam, regex, and scipy dependencies. Validation for this revision uses **Python 3.11.13**; this does not establish compatibility with older interpreters or every platform/dependency combination. The standalone bundle includes the previously tested dependency pins in `requirements.txt`.
+
+In an activated Python environment, install a downloaded release file:
+
+```bash
+uv pip install ./telometer-2.0.3-py3-none-any.whl
+# Or build/install the source distribution:
+uv pip install ./telometer-2.0.3.tar.gz
+
+telometer --version
+```
+
+The version command prints `Telometer v2.0.3`. Run on a sorted BAM aligned to a confirmed compatible reference:
+
+```bash
+# WGS; use -m 1000 for telomere capture libraries.
+telometer -b sample.sorted.bam -o telomeres.tsv -m 4000 -g 20 -t 2 -l 1
+
+# Optional variant motif and independently optional enrichment:
+telometer -b sample.sorted.bam -o telomeres_variants.tsv -m 4000 -g 20 -t 2 -l 1 \
+  --variant-motif TGCGGT --min-variant-units 2 -e
+```
+
+`TGCGGT` is an example, not an inferred or default motif. Both optional features are off unless requested. `-e` / `--enrichment` is a Boolean switch with no value. The existing minimum-length default is 1000 bp; the gap default is 20. `-l` is a nominal batch-size setting in GiB, **not a total-memory limit**. With enrichment enabled, memory also scales with the number of unique read IDs. Choose resources using a representative subset.
+
+The console entry point is `telometer.telometer:run_telometer`. Package-context alternatives are `python -m telometer.telometer` and `from telometer.telometer import process_bam_file`. There is no `python -m telometer` launcher or root-level function re-export in this package.
+
+For the standalone ZIP, extract **all five files together**, install its requirements, and invoke `python telometer.py`. Its two helper modules must remain adjacent to the caller. The separate drop-in package module uses relative imports and is not a self-contained standalone script.
+
+## Main TSV
+
+With variant mode and enrichment both enabled, columns are exactly:
+
+```text
+chromosome
+reference_start
+reference_end
+telomere_length
+read_id
+mapping_quality
+read_length
+arm
+direction
+variant_motif
+variant_present
+variant_tract_count
+pre_variant_bp
+telomeres_per_gb
+variant_tract_lengths
+percent_pre_variant
+```
+
+Without `-e`, `telomeres_per_gb` is omitted. Without variant mode, all variant-specific columns are omitted. The four mode widths are **9 / 10 / 15 / 16** for neither / enrichment only / variants only / both. Empty tables retain the appropriate headers. Missing values in the main TSV are the literal **`NA`**; genuine zeros are preserved. Main row order may vary across worker runs, so compare by read ID.
+
+### Individual tract lengths
+
+`variant_tract_lengths` contains integer base-pair spans, separated by commas without spaces, in the existing companion `tract_id` order (increasing original-read query coordinates). There is one entry per qualifying tract. These are spans, not six-base repeat counts or merged/union coverage. Separately counted overlapping tracts remain separate, and lengths are not rounded to multiples of six. Reads without qualifying tracts have `NA`.
+
+### Fractional first-tract position
+
+`percent_pre_variant` is a **0–1 fraction**, not a 0–100 percentage. It describes the first qualifying tract's position from the called telomere's subtelomeric-facing end toward its distal end. In the existing original-orientation coordinate frame, let `T0` and `T1` be the selected telomere boundaries:
+
+- Right-terminal telomere: `(minimum tract start - T0) / telomere_length`.
+- Left-terminal telomere: `(T1 - maximum tract end) / telomere_length`.
+
+The coordinate frame includes consistent recorded hard-clip offsets. No qualifying tract or an ambiguous/unidentifiable terminal side gives `NA`. A tract at the proximal boundary gives a genuine zero. The lengths list stays in query-coordinate order even when the proximal-first tract is its last entry.
+
+Unlike the unchanged `pre_variant_bp`, the new fraction **does not require a supported alignment/repeat-free-flank anchor**. It can therefore be numeric when `pre_variant_bp` is `NA`. It measures position within the called telomere interval, not a verified physical subtelomeric junction or historical telomere length. Detection and tract-support thresholds are unchanged.
+
+## Companion table and enrichment
+
+Variant mode still writes `<output_stem>_variant_tracts.tsv` with its unchanged 20-column schema, per-tract values, and missing-value formatting. The eight removed main-table coverage/diagnostic fields are not used to change calls or suppress internal diagnostics. Use a fresh output stem to avoid confusing an old companion with a new variant-disabled run.
+
+Enrichment remains:
+
+`final measured unique read-ID count * 1,000,000,000 / nonredundant recorded read bases in the BAM`
+
+Each QNAME contributes one consistent recorded full length before filtering; repeated alignments do not multiply bases. Query-consuming CIGAR operations and recorded hard clips determine full length when available. Unresolved/conflicting lengths, unusable IDs, or paired-end input can make the aggregate unavailable; valid measurements are still written with `NA` enrichment. Positive recorded bases with zero calls give rate zero; an empty/zero-base BAM has unavailable rate. The sample-wide value is repeated on measured rows, not calculated independently per read. Preserve the console log for sample totals when the output has no rows.
+
+The BAM cannot recover reads removed upstream or trimming that is absent from its metadata. This rate is not necessarily total instrument yield or a fold-enrichment comparison. Software regression checks are not independent biological validation of variant status, telomere boundaries, or positional interpretation.
+
+## Build and manual publication
+
+The supplied flat layout and `setuptools>=61,<76` backend policy are retained. Build in an activated environment:
+
+```bash
+uv pip install "build==1.5.0"
+python -m build
+```
+
+Use current Twine and packaging when checking metadata:
+
+```bash
+uv pip install --upgrade "twine>=6.1.0" "packaging>=24.2"
+python -m twine check --strict dist/telometer-2.0.3-py3-none-any.whl dist/telometer-2.0.3.tar.gz
+```
+
+Publishing is a separate maintainer action; these files do not update GitHub or PyPI automatically. The release is MIT licensed under the restored Telometer notice in `LICENSE.txt`.

{telometer-2.0.1 → telometer-2.0.3}/telometer.egg-info/SOURCES.txt

@@ -1,10 +1,14 @@
+LICENSE.txt
 README.md
 pyproject.toml
+setup.cfg
+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.3/telometer.egg-info/entry_points.txt

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

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

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

telometer-2.0.1/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.4
-Name: telometer
-Version: 2.0.1
-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.1/README.md

@@ -1,3 +0,0 @@
-A simple tool for measuring chromosome-specific telomeres from long-read alignments.
-
-[Telometer Github](https://github.com/santiago-es/Telometer) 

telometer-2.0.1/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.1"
-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.1/telometer.egg-info/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.4
-Name: telometer
-Version: 2.0.1
-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.1/telometer.egg-info/requires.txt

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