telometer 2.0.2__tar.gz → 2.0.3__tar.gz

{telometer-2.0.2 → telometer-2.0.3}/LICENSE.txt

@@ -1,4 +1,6 @@
-Copyright (c) 2024 The Python Packaging Authority
+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

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.2 → telometer-2.0.3}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "telometer"
-version = "2.0.2"
+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"

{telometer-2.0.2 → telometer-2.0.3}/telometer/__init__.py

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

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# Telometer v2.0
+# Telometer v2.0.3
 
 # Created by: Santiago E Sanchez
 # Artandi Lab, Stanford University, 2024
@@ -8,7 +8,7 @@
 
 # Simple Usage: telometer -b sorted_t2t.bam -o output.tsv
 
-__version__ = "2.0.2"
+__version__ = "2.0.3"
 
 import pysam
 from pathlib import Path
@@ -354,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)
@@ -447,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.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.2 → telometer-2.0.3}/telometer.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE.txt
 README.md
 pyproject.toml
+setup.cfg
 telometer/__init__.py
 telometer/telometer.py
 telometer/telometer_variant_support.py

telometer-2.0.2/PKG-INFO

@@ -1,48 +0,0 @@
-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/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.2/telometer.egg-info/PKG-INFO

@@ -1,48 +0,0 @@
-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)