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`.
