strkit 0.25.0a1__tar.gz → 0.25.0a2__tar.gz

{strkit-0.25.0a1/strkit.egg-info → strkit-0.25.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strkit
-Version: 0.25.0a1
+Version: 0.25.0a2
 Summary: A toolkit for analyzing variation in short(ish) tandem repeats.
 Home-page: https://github.com/davidlougheed/strkit
 Author: David Lougheed
@@ -11,7 +11,6 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: POSIX
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS :: MacOS X
@@ -19,15 +18,15 @@ Requires-Python: ~=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: Flask<3.2,>=2.2.5
-Requires-Dist: orjson<4,>=3.9.15
+Requires-Dist: orjson<4,>=3.11.1
 Requires-Dist: pysam<0.24,>=0.19
-Requires-Dist: numpy<1.27,>=1.23.4
+Requires-Dist: numpy<3,>=2.1.3
 Requires-Dist: parasail<1.4,>=1.2.4
 Requires-Dist: pydantic<3,>=2.11.7
 Requires-Dist: scikit-learn<1.8,>=1.2.1
 Requires-Dist: scipy<1.17,>=1.10
 Requires-Dist: statsmodels<0.15,>=0.14.0
-Requires-Dist: strkit_rust_ext==0.25.0
+Requires-Dist: strkit_rust_ext==0.26.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -43,12 +42,20 @@ Dynamic: summary
 # STRkit - short tandem repeat genotyping with long reads
 
 [![PyPI version](https://badge.fury.io/py/strkit.svg)](https://badge.fury.io/py/strkit)
-[![BioRxiv DOI](https://img.shields.io/badge/bioRxiv-10.1101/2025.03.25.645269-B31B1B.svg)](https://doi.org/10.1101/2025.03.25.645269)
-[![Zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12689906.svg)](https://doi.org/10.5281/zenodo.12689906)
 
-STRkit is a short tandem repeat (STR) genotyping and analysis toolkit for long read sequencing data, especially 
-PacBio HiFi data. The STRkit software package is written in Python and is available in the PyPI package registry or as
-a Docker container.
+STRkit is a short tandem repeat (STR) genotyping and analysis toolkit for long read sequencing data (both HiFi and ONT). 
+The STRkit software package is written in Python and is available in the PyPI package registry or as a Docker container.
+
+STRkit's main advantages over other callers include:
+* Better performance in some [benchmarking assessments](https://doi.org/10.1101/gr.280766.125) versus other tools;
+* An on-the-fly SNV calling and local phasing step for unphased aligned reads;
+* A license which allows use on any long-read sequencing data, versus TRGT whose 
+  [license](https://github.com/PacificBiosciences/trgt/blob/main/LICENSE.md) restricts it to only PacBio data.
+
+Some other useful features include:
+* An interactive [call visualizer](#strkit-visualize-call-visualizer)
+* A locus catalog [converter](#strkit-convert-str-catalog-conversion), which includes a TRF `.dat` to `BED` converter
+* A pre-built Docker image ([`ghcr.io/davidlougheed/strkit`](https://ghcr.io/davidlougheed/strkit))
 
 If you use STRkit in published work, please cite our paper in *Genome Research*:
 
@@ -56,6 +63,8 @@ If you use STRkit in published work, please cite our paper in *Genome Research*:
 > David R Lougheed, Tomi Pastinen, Guillaume Bourque. *Genome Res*.
 > DOI:&nbsp;[10.1101/gr.280766.125](https://doi.org/10.1101/gr.280766.125)
 
+The code for the software itself is also available and citeable in Zenodo: https://doi.org/10.5281/zenodo.12689906
+
 <img src="./docs/images/strkit_logo_small.png" alt="" width="500" height="324" />
 
 **Officially-supported platforms:** macOS (aarch64), Linux (amd64/aarch64)
@@ -141,7 +150,7 @@ docker run \
   -v out:/out \
   -it ghcr.io/davidlougheed/strkit call \
   /inputs/file.bam \
-  --hq --loci /inputs/loci.bed --ref /inputs/ref.fa --incorporate-snvs /inputs/dbsnp.vcf.gz \
+  --loci /inputs/loci.bed --ref /inputs/ref.fa --incorporate-snvs /inputs/dbsnp.vcf.gz \
   --vcf /out/calls.vcf --no-tsv
 ```
 
@@ -179,13 +188,14 @@ long read data should still work.
   * Whole-genome and targeted genotyping modes to adjust this re-weighting.
 * Incorporation of single-nucleotide variation (SNVs) for better and faster calling plus 
   additional downstream analysis possibilities.
-  * Recommended for **HiFi data and ONT R10 data only**. In my testing, this worsens runtime and call quality for 
-    ONT ultra-long-read data, but speeds up the tool and improves call quality for HiFi/ONT R10 data. 
+  * SNV incorporation is recommended for **HiFi data and ONT R10 data only**. In my testing, this worsens runtime and 
+    call quality for ONT ultra-long-read data, but speeds up the tool and improves call quality for HiFi/ONT R10 data. 
   * **Important note:** This functionality is best for whole-genome STR surveying. If hunting for rare / low-coverage
-    expansions, or using targeted sequencing data, it may be best to **NOT USE** an SNV catalog to avoid discording 
+    expansions, or using targeted sequencing data, it may be best to **NOT USE** an SNV catalog to avoid discarding 
     reads with short flanking regions.
 * Parallelized for faster computing on clusters and for ad-hoc fast analysis of single samples.
 * 95% confidence intervals on calls via a user-configurable optional parametric bootstrapping process.
+* Multiple motif support via [IUPAC code motifs](https://www.bioinformatics.org/sms/iupac.html).
 
 
 #### Usage:
@@ -198,16 +208,14 @@ See all parameters and example usage with a Slurm cluster:
 ```bash
 # For the dbSNP VCF used below for SNV incorporation, see https://ftp.ncbi.nih.gov/snp/organisms/human_9606/VCF/
 # (00-common_all.vcf.gz)
-#
-# "Accurate reads" here means HiFi / ONT R10 duplex reads, but in practice may also include ONT R10 simplex reads.
 
 strkit call \
   path/to/read/file.bam \  # [REQUIRED] One indexed read file (BAM/CRAM)
-  --hq \  # If using accurate reads, enable this to get better genotyping & more robust expansion detection
   --realign \  # If using accurate reads, enable this to enable local realignment / read recovery. Good for detecting expansions, but slows down calling.
   --ref path/to/reference.fa.gz \  # [REQUIRED] Indexed FASTA-formatted reference genome
   --loci path/to/loci.bed \  # [REQUIRED] TRF-formatted (or 4-col, with motif as last column) sorted list of loci to genotype
-  --incorporate-snvs path/to/dbsnp/00-common_all.vcf.gz \   # If you want, specify a SNV catalogue to help phase STRs & speed up calling
+  --annotation-file path/to/reference-annotations.gff.gz \  # Optional GFF3/GTF file to provide locus annotations (transcript/exon ID)
+  --incorporate-snvs path/to/dbsnp/00-common_all.vcf.gz \   # If you want, specify a SNV catalogue to help phase STRs & speed up calling with HiFi/ONT R10
   --vcf my-calls.vcf \  # Calculate consensus sequences for alleles and output a .vcf (or .vcf.gz) with call data
   --seed 183 \  # Fixed random number generator seed for replicability
   --processes 10 \  # Number of parallel processes to use; DEFAULT: 1
@@ -222,15 +230,77 @@ PacBio provides a
 for CCS alignment in this scenario. However, regular aligned readsets are fine and have been tested
 extensively.
 
-If you're using accurate long reads (e.g., HiFi, ONT R10 duplex) as input, **use the `--hq` and 
-`--realign` options** to get better genotype calculation and a greater proportion of reads 
-incorporated into the computed genotypes, respectively. These should not add much performance 
-overhead. *In practice, these options may also aid calling with slightly-less-accurate reads.*
+###### WITH ACCURATE READS
+
+If you're using accurate long reads (e.g., HiFi, ONT R10) as input, **use the `--realign` option**
+to enable re-aligning soft-clipped reads to the reference genome. This will add a bit of 
+performance overhead, but can help recover some reads of interest (e.g., expansions). 
+
+*In practice, this option may also aid calling with slightly-less-accurate reads, especially if
+you are looking for expansions and do not mind slower performance if the reads do not align well 
+to the reference genome.*
+
+###### WITH LOW-QUALITY READS
+
+If you're using low-quality long reads (e.g., older ONT data), some non-default parameters may help
+get the best genotyping performance:
+
+- Reads with tandem repeat + flanking region PHRED quality below 13 are filtered out by default. 
+  You may wish to lower this to avoid discarding reads by setting `--min-avg-phred` to a lower 
+  value like `5`, or you can effectively disable this filter by setting it to `1`.
+- We have observed some cases of 'false positive' expansion-esque reads with ONT R9 data. The 
+  `--force-gm-filter` option can help filter these out, at the cost of reducing STRkit's 
+  sensitivity to true expansions.
+
+###### WITH HAPLOTAGGED READS
 
 If you want to **incorporate haplotagging from an alignment file (`HP` tags)** into the 
 process, which should speed up runtime and potentially improve calling results, you must pass 
 the `--use-hp` flag.
 
+###### WITH LOW-COVEREAGE ALIGNMENT DATA
+
+If you're calling STRs using low-coverage alignments, you may want to:
+
+- lower the minimum number of reads per locus (`--min-reads`) to `2` (or even `1` if you're fine 
+  with some guaranteed allelic dropout), and
+- lower the minimum number of reads per allele (`--min-allele-reads`) to `1` to avoid dropout as 
+  much as possible.
+- potentially, if you desire more calls at the cost of quality, lower the minimum tandem repeat +
+  flanking region PHRED quality required (from its default of 13) via the `--min-avg-phred` 
+  parameter.
+- enable the `--allow-only-one-full-flank` option to discard fewer reads by including spanning 
+  reads where only one of the two flanking sequences on either side of the repeat are of full 
+  length (i.e., are of length `--flank-size` or higher.)
+
+**Note:** `--min-reads` must be greater than or equal to `--min-allele-reads`.
+
+###### WITH TARGETED SEQUENCING DATA
+
+If you're running STRkit with targeted sequencing data, you should put STRkit in targeted mode with the `--targeted` 
+flag, which slightly tweaks read re-sampling behaviour and increases the `--max-reads` default from 250 to 500.
+
+##### LOOKING FOR LARGE EXPANSIONS
+
+If you're running STRkit for the purpose of finding pathogenic STR expansions or expansions of 
+interest, the following parameters may help increase expansion sensitivity, at the cost of 
+computational performance or a potential bias towards heterozygous calls:
+
+* With a catalog of disease loci, make sure to encode all possible locus motifs of the same length 
+  via [IUPAC codes](https://www.bioinformatics.org/sms/iupac.html) in the catalog file.
+* Make sure to **NOT** enable `--force-gm-filter`, even if using lower-quality reads. Enabling this
+  option can filter out artifact reads with false-positive expansion-like read counts, but it will 
+  also lower sensitivity for true expansions with low read support.
+* Enable `--realign`, *even* with lower-quality reads. Reads containing expansions can be 
+  soft-clipped by aligners like `minimap2`; the `--realign` flag can help recover these reads.
+* Tune `--gm-filter-expansion-ratio` to a slightly lower value, like `3.0`. This will keep larger 
+  alleles with low read support if they are larger than `--gm-filter-expansion-ratio` times the 
+  size of the smaller allele.
+* Enable the `--allow-only-one-full-flank` option to discard fewer reads (especially since 
+  expansions often do not have many spanning reads) by including spanning reads where only one of the
+  two flanking sequences on either side of the repeat are of full length (i.e., are of length 
+  `--flank-size` or higher.)
+
 ##### REGARDING SNV INCORPORATION
 
 If you want to **incorporate SNV calling** into the process, which speeds up runtime and gives
@@ -241,6 +311,16 @@ The file for GRCh38 is called `00-common_all.vcf.gz` as of time of writing.
 **Note that this does not need to be an SNV call file for your sample, specifically**; just one 
 which has positions, reference/alternate alleles, and the `ID` field populated.
 
+##### REGARDING ANNOTATION
+
+If you would like to have the IDs of **genome features** (from a `.gff3` or `.gtf` file) which 
+overlap STR loci in your `strkit call` output (JSON or VCF), you can pass a sorted, Tabix-indexed
+annotation file path to `strkit call` with the `--annotation-file <path>` flag (replacing `<path>`
+with the path to the annotation file.) This could be used for downstream analysis to find STR 
+variants that overlap, for example, coding sequences or gene UTRs.
+
+For more information, see also documentation on the [Output formats](./docs/output_formats.md).
+
 ##### REGARDING OUTPUT
 
 If you want to output a full call report, you can use the `--json output-file.json` argument to
@@ -383,44 +463,77 @@ For other options and what they do, run `strkit mi` (with no other arguments) or
 
 ### `strkit convert`: STR catalog conversion
 
-STRkit takes as input a four-or-more-column BED file, structured like:
+STRkit takes as input a four-or-more-column BED file, structured like one of the following:
 
 ```
-contig  start end [0 or more extraneous columns] motif
+contig  start end [0 or more extraneous columns] NNN
+contig  start end [0 or more extraneous columns] ID=locus1;MOTIF=NNN
 ```
 
 Any extraneous columns are removed, (internally) leaving a four-column STR locus representation. 
 Some other tools, e.g., [Straglr](https://github.com/bcgsc/straglr), also take a four-column STR
 BED as locus catalog input. However, other formats representing a catalog of STRs exist:
 
-* [Tandem Repeats Finder](https://github.com/Benson-Genomics-Lab/TRF) outputs a TSV/BED with a lot 
-  of information. This can be used as-is with STRkit, but it's safer for other tools to convert to
-  a four-column BED format.
+* [Tandem Repeats Finder](https://github.com/Benson-Genomics-Lab/TRF) outputs a `.dat` file with a lot 
+  of information. Once converted to a BED file, this can be used as-is with STRkit, but 
+  it's safer for other tools to convert to a four-column BED format.
+  See "[Converting TRF DAT files to BED](./docs/convert_trf_to_bed.md)" for more on how to do this.
+* STRkit supports using [IUPAC codes] to specify motifs. Manual post-processing of TRF output would 
+  be needed to do this.
 * [TRGT uses a custom repeat definition format](https://github.com/PacificBiosciences/trgt/blob/main/docs/repeat_files.md),
   which can specify more advanced STR structures.
+* Some tools support multiple motifs (see, e.g., 
+  [STRchive catalogs of pathogenic loci](https://strchive.org/loci/#downloads)).
 
 #### Usage
 
-The `strkit convert` sub-command requires an input format (`trf` or `trgt`), an output format 
-(many, see `strkit convert --help`), and an input file. Output is written to `stdout`.
+The `strkit convert` sub-command requires an input format (`bed4`, `trf` or `trgt`), an output 
+format (many, see `strkit convert --help`), and an input file. Output is written to `stdout`.
+
+If you want the output **sorted** (which many tools prefer or require), use the `--sort` flag.
 
 *Note:* Not all input/output format pairs have available converter functions; an error will be 
 printed to `stderr` if one does not exist.
 
-For example, to convert from a TRF BED to a TRGT repeat definition BED file:
+##### TRF DAT file to TRF BED file (*UCSC-style*)
+
+To convert from a TRF `.dat` file (as output by the TRF program) to a TRF BED file in the style of
+the one obtainable from UCSC (e.g., for 
+[hg38](https://hgdownload.soe.ucsc.edu/goldenpath/hg38/bigZips/latest/)):
+
+```bash
+strkit convert --in-format trf --out-format trf in_file.trf.dat > out_file.trf.bed
+```
+
+##### TRF DAT file to 4-column BED file
+
+To convert from a TRF `.dat` file (as output by the TRF program) to a normal BED file:
+
+```bash
+strkit convert --in-format trf --out-format bed4 in_file.trf.dat > out_file.bed
+```
+
+##### TRF BED to TRGT repeat definition file
+
+To convert from a TRF BED to a TRGT repeat definition BED file:
 
 ```bash
 strkit convert --in-format trf --out-format trgt in_file.trf.bed > out_file.bed
 ```
 
-To attempt a conversion from a TRGT repeat definition file to a STRkit/four-column motif BED:
+##### TRGT repeat definition file to STRkit BED
+
+To convert from a TRGT repeat definition file to a STRkit BED, including locus IDs if set:
 
 ```bash
-strkit convert --in-format trgt --out-format strkit in_file.trgt.bed > out_file.bed
+strkit convert --in-format trgt --out-format strkit in_file.trgt.bed > out_file.strkit.bed
 ```
 
-Note that TRGT can represent STRs with complex structure that STRkit cannot, so some of these loci
-may not be converted (these will be logged to `stderr`).
+Where possible, multiple motifs will be reconciled using [IUPAC codes](https://www.bioinformatics.org/sms/iupac.html),
+which STRkit supports.
+
+Note that TRGT can represent STRs with complex structure that STRkit cannot. In these cases, the first motif in the TRGT 
+locus definition will be used and a message will be logged to `stderr`.
 
 
 ## Copyright and License

{strkit-0.25.0a1 → strkit-0.25.0a2}/README.md

@@ -1,12 +1,20 @@
 # STRkit - short tandem repeat genotyping with long reads
 
 [![PyPI version](https://badge.fury.io/py/strkit.svg)](https://badge.fury.io/py/strkit)
-[![BioRxiv DOI](https://img.shields.io/badge/bioRxiv-10.1101/2025.03.25.645269-B31B1B.svg)](https://doi.org/10.1101/2025.03.25.645269)
-[![Zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.12689906.svg)](https://doi.org/10.5281/zenodo.12689906)
 
-STRkit is a short tandem repeat (STR) genotyping and analysis toolkit for long read sequencing data, especially 
-PacBio HiFi data. The STRkit software package is written in Python and is available in the PyPI package registry or as
-a Docker container.
+STRkit is a short tandem repeat (STR) genotyping and analysis toolkit for long read sequencing data (both HiFi and ONT). 
+The STRkit software package is written in Python and is available in the PyPI package registry or as a Docker container.
+
+STRkit's main advantages over other callers include:
+* Better performance in some [benchmarking assessments](https://doi.org/10.1101/gr.280766.125) versus other tools;
+* An on-the-fly SNV calling and local phasing step for unphased aligned reads;
+* A license which allows use on any long-read sequencing data, versus TRGT whose 
+  [license](https://github.com/PacificBiosciences/trgt/blob/main/LICENSE.md) restricts it to only PacBio data.
+
+Some other useful features include:
+* An interactive [call visualizer](#strkit-visualize-call-visualizer)
+* A locus catalog [converter](#strkit-convert-str-catalog-conversion), which includes a TRF `.dat` to `BED` converter
+* A pre-built Docker image ([`ghcr.io/davidlougheed/strkit`](https://ghcr.io/davidlougheed/strkit))
 
 If you use STRkit in published work, please cite our paper in *Genome Research*:
 
@@ -14,6 +22,8 @@ If you use STRkit in published work, please cite our paper in *Genome Research*:
 > David R Lougheed, Tomi Pastinen, Guillaume Bourque. *Genome Res*.
 > DOI: [10.1101/gr.280766.125](https://doi.org/10.1101/gr.280766.125)
 
+The code for the software itself is also available and citeable in Zenodo: https://doi.org/10.5281/zenodo.12689906
+
 <img src="./docs/images/strkit_logo_small.png" alt="" width="500" height="324" />
 
 **Officially-supported platforms:** macOS (aarch64), Linux (amd64/aarch64)
@@ -99,7 +109,7 @@ docker run \
   -v out:/out \
   -it ghcr.io/davidlougheed/strkit call \
   /inputs/file.bam \
-  --hq --loci /inputs/loci.bed --ref /inputs/ref.fa --incorporate-snvs /inputs/dbsnp.vcf.gz \
+  --loci /inputs/loci.bed --ref /inputs/ref.fa --incorporate-snvs /inputs/dbsnp.vcf.gz \
   --vcf /out/calls.vcf --no-tsv
 ```
 
@@ -137,13 +147,14 @@ long read data should still work.
   * Whole-genome and targeted genotyping modes to adjust this re-weighting.
 * Incorporation of single-nucleotide variation (SNVs) for better and faster calling plus 
   additional downstream analysis possibilities.
-  * Recommended for **HiFi data and ONT R10 data only**. In my testing, this worsens runtime and call quality for 
-    ONT ultra-long-read data, but speeds up the tool and improves call quality for HiFi/ONT R10 data. 
+  * SNV incorporation is recommended for **HiFi data and ONT R10 data only**. In my testing, this worsens runtime and 
+    call quality for ONT ultra-long-read data, but speeds up the tool and improves call quality for HiFi/ONT R10 data. 
   * **Important note:** This functionality is best for whole-genome STR surveying. If hunting for rare / low-coverage
-    expansions, or using targeted sequencing data, it may be best to **NOT USE** an SNV catalog to avoid discording 
+    expansions, or using targeted sequencing data, it may be best to **NOT USE** an SNV catalog to avoid discarding 
     reads with short flanking regions.
 * Parallelized for faster computing on clusters and for ad-hoc fast analysis of single samples.
 * 95% confidence intervals on calls via a user-configurable optional parametric bootstrapping process.
+* Multiple motif support via [IUPAC code motifs](https://www.bioinformatics.org/sms/iupac.html).
 
 
 #### Usage:
@@ -156,16 +167,14 @@ See all parameters and example usage with a Slurm cluster:
 ```bash
 # For the dbSNP VCF used below for SNV incorporation, see https://ftp.ncbi.nih.gov/snp/organisms/human_9606/VCF/
 # (00-common_all.vcf.gz)
-#
-# "Accurate reads" here means HiFi / ONT R10 duplex reads, but in practice may also include ONT R10 simplex reads.
 
 strkit call \
   path/to/read/file.bam \  # [REQUIRED] One indexed read file (BAM/CRAM)
-  --hq \  # If using accurate reads, enable this to get better genotyping & more robust expansion detection
   --realign \  # If using accurate reads, enable this to enable local realignment / read recovery. Good for detecting expansions, but slows down calling.
   --ref path/to/reference.fa.gz \  # [REQUIRED] Indexed FASTA-formatted reference genome
   --loci path/to/loci.bed \  # [REQUIRED] TRF-formatted (or 4-col, with motif as last column) sorted list of loci to genotype
-  --incorporate-snvs path/to/dbsnp/00-common_all.vcf.gz \   # If you want, specify a SNV catalogue to help phase STRs & speed up calling
+  --annotation-file path/to/reference-annotations.gff.gz \  # Optional GFF3/GTF file to provide locus annotations (transcript/exon ID)
+  --incorporate-snvs path/to/dbsnp/00-common_all.vcf.gz \   # If you want, specify a SNV catalogue to help phase STRs & speed up calling with HiFi/ONT R10
   --vcf my-calls.vcf \  # Calculate consensus sequences for alleles and output a .vcf (or .vcf.gz) with call data
   --seed 183 \  # Fixed random number generator seed for replicability
   --processes 10 \  # Number of parallel processes to use; DEFAULT: 1
@@ -180,15 +189,77 @@ PacBio provides a
 for CCS alignment in this scenario. However, regular aligned readsets are fine and have been tested
 extensively.
 
-If you're using accurate long reads (e.g., HiFi, ONT R10 duplex) as input, **use the `--hq` and 
-`--realign` options** to get better genotype calculation and a greater proportion of reads 
-incorporated into the computed genotypes, respectively. These should not add much performance 
-overhead. *In practice, these options may also aid calling with slightly-less-accurate reads.*
+###### WITH ACCURATE READS
+
+If you're using accurate long reads (e.g., HiFi, ONT R10) as input, **use the `--realign` option**
+to enable re-aligning soft-clipped reads to the reference genome. This will add a bit of 
+performance overhead, but can help recover some reads of interest (e.g., expansions). 
+
+*In practice, this option may also aid calling with slightly-less-accurate reads, especially if
+you are looking for expansions and do not mind slower performance if the reads do not align well 
+to the reference genome.*
+
+###### WITH LOW-QUALITY READS
+
+If you're using low-quality long reads (e.g., older ONT data), some non-default parameters may help
+get the best genotyping performance:
+
+- Reads with tandem repeat + flanking region PHRED quality below 13 are filtered out by default. 
+  You may wish to lower this to avoid discarding reads by setting `--min-avg-phred` to a lower 
+  value like `5`, or you can effectively disable this filter by setting it to `1`.
+- We have observed some cases of 'false positive' expansion-esque reads with ONT R9 data. The 
+  `--force-gm-filter` option can help filter these out, at the cost of reducing STRkit's 
+  sensitivity to true expansions.
+
+###### WITH HAPLOTAGGED READS
 
 If you want to **incorporate haplotagging from an alignment file (`HP` tags)** into the 
 process, which should speed up runtime and potentially improve calling results, you must pass 
 the `--use-hp` flag.
 
+###### WITH LOW-COVEREAGE ALIGNMENT DATA
+
+If you're calling STRs using low-coverage alignments, you may want to:
+
+- lower the minimum number of reads per locus (`--min-reads`) to `2` (or even `1` if you're fine 
+  with some guaranteed allelic dropout), and
+- lower the minimum number of reads per allele (`--min-allele-reads`) to `1` to avoid dropout as 
+  much as possible.
+- potentially, if you desire more calls at the cost of quality, lower the minimum tandem repeat +
+  flanking region PHRED quality required (from its default of 13) via the `--min-avg-phred` 
+  parameter.
+- enable the `--allow-only-one-full-flank` option to discard fewer reads by including spanning 
+  reads where only one of the two flanking sequences on either side of the repeat are of full 
+  length (i.e., are of length `--flank-size` or higher.)
+
+**Note:** `--min-reads` must be greater than or equal to `--min-allele-reads`.
+
+###### WITH TARGETED SEQUENCING DATA
+
+If you're running STRkit with targeted sequencing data, you should put STRkit in targeted mode with the `--targeted` 
+flag, which slightly tweaks read re-sampling behaviour and increases the `--max-reads` default from 250 to 500.
+
+##### LOOKING FOR LARGE EXPANSIONS
+
+If you're running STRkit for the purpose of finding pathogenic STR expansions or expansions of 
+interest, the following parameters may help increase expansion sensitivity, at the cost of 
+computational performance or a potential bias towards heterozygous calls:
+
+* With a catalog of disease loci, make sure to encode all possible locus motifs of the same length 
+  via [IUPAC codes](https://www.bioinformatics.org/sms/iupac.html) in the catalog file.
+* Make sure to **NOT** enable `--force-gm-filter`, even if using lower-quality reads. Enabling this
+  option can filter out artifact reads with false-positive expansion-like read counts, but it will 
+  also lower sensitivity for true expansions with low read support.
+* Enable `--realign`, *even* with lower-quality reads. Reads containing expansions can be 
+  soft-clipped by aligners like `minimap2`; the `--realign` flag can help recover these reads.
+* Tune `--gm-filter-expansion-ratio` to a slightly lower value, like `3.0`. This will keep larger 
+  alleles with low read support if they are larger than `--gm-filter-expansion-ratio` times the 
+  size of the smaller allele.
+* Enable the `--allow-only-one-full-flank` option to discard fewer reads (especially since 
+  expansions often do not have many spanning reads) by including spanning reads where only one of the
+  two flanking sequences on either side of the repeat are of full length (i.e., are of length 
+  `--flank-size` or higher.)
+
 ##### REGARDING SNV INCORPORATION
 
 If you want to **incorporate SNV calling** into the process, which speeds up runtime and gives
@@ -199,6 +270,16 @@ The file for GRCh38 is called `00-common_all.vcf.gz` as of time of writing.
 **Note that this does not need to be an SNV call file for your sample, specifically**; just one 
 which has positions, reference/alternate alleles, and the `ID` field populated.
 
+##### REGARDING ANNOTATION
+
+If you would like to have the IDs of **genome features** (from a `.gff3` or `.gtf` file) which 
+overlap STR loci in your `strkit call` output (JSON or VCF), you can pass a sorted, Tabix-indexed
+annotation file path to `strkit call` with the `--annotation-file <path>` flag (replacing `<path>`
+with the path to the annotation file.) This could be used for downstream analysis to find STR 
+variants that overlap, for example, coding sequences or gene UTRs.
+
+For more information, see also documentation on the [Output formats](./docs/output_formats.md).
+
 ##### REGARDING OUTPUT
 
 If you want to output a full call report, you can use the `--json output-file.json` argument to
@@ -341,44 +422,77 @@ For other options and what they do, run `strkit mi` (with no other arguments) or
 
 ### `strkit convert`: STR catalog conversion
 
-STRkit takes as input a four-or-more-column BED file, structured like:
+STRkit takes as input a four-or-more-column BED file, structured like one of the following:
 
 ```
-contig  start end [0 or more extraneous columns] motif
+contig  start end [0 or more extraneous columns] NNN
+contig  start end [0 or more extraneous columns] ID=locus1;MOTIF=NNN
 ```
 
 Any extraneous columns are removed, (internally) leaving a four-column STR locus representation. 
 Some other tools, e.g., [Straglr](https://github.com/bcgsc/straglr), also take a four-column STR
 BED as locus catalog input. However, other formats representing a catalog of STRs exist:
 
-* [Tandem Repeats Finder](https://github.com/Benson-Genomics-Lab/TRF) outputs a TSV/BED with a lot 
-  of information. This can be used as-is with STRkit, but it's safer for other tools to convert to
-  a four-column BED format.
+* [Tandem Repeats Finder](https://github.com/Benson-Genomics-Lab/TRF) outputs a `.dat` file with a lot 
+  of information. Once converted to a BED file, this can be used as-is with STRkit, but 
+  it's safer for other tools to convert to a four-column BED format.
+  See "[Converting TRF DAT files to BED](./docs/convert_trf_to_bed.md)" for more on how to do this.
+* STRkit supports using [IUPAC codes] to specify motifs. Manual post-processing of TRF output would 
+  be needed to do this.
 * [TRGT uses a custom repeat definition format](https://github.com/PacificBiosciences/trgt/blob/main/docs/repeat_files.md),
   which can specify more advanced STR structures.
+* Some tools support multiple motifs (see, e.g., 
+  [STRchive catalogs of pathogenic loci](https://strchive.org/loci/#downloads)).
 
 #### Usage
 
-The `strkit convert` sub-command requires an input format (`trf` or `trgt`), an output format 
-(many, see `strkit convert --help`), and an input file. Output is written to `stdout`.
+The `strkit convert` sub-command requires an input format (`bed4`, `trf` or `trgt`), an output 
+format (many, see `strkit convert --help`), and an input file. Output is written to `stdout`.
+
+If you want the output **sorted** (which many tools prefer or require), use the `--sort` flag.
 
 *Note:* Not all input/output format pairs have available converter functions; an error will be 
 printed to `stderr` if one does not exist.
 
-For example, to convert from a TRF BED to a TRGT repeat definition BED file:
+##### TRF DAT file to TRF BED file (*UCSC-style*)
+
+To convert from a TRF `.dat` file (as output by the TRF program) to a TRF BED file in the style of
+the one obtainable from UCSC (e.g., for 
+[hg38](https://hgdownload.soe.ucsc.edu/goldenpath/hg38/bigZips/latest/)):
+
+```bash
+strkit convert --in-format trf --out-format trf in_file.trf.dat > out_file.trf.bed
+```
+
+##### TRF DAT file to 4-column BED file
+
+To convert from a TRF `.dat` file (as output by the TRF program) to a normal BED file:
+
+```bash
+strkit convert --in-format trf --out-format bed4 in_file.trf.dat > out_file.bed
+```
+
+##### TRF BED to TRGT repeat definition file
+
+To convert from a TRF BED to a TRGT repeat definition BED file:
 
 ```bash
 strkit convert --in-format trf --out-format trgt in_file.trf.bed > out_file.bed
 ```
 
-To attempt a conversion from a TRGT repeat definition file to a STRkit/four-column motif BED:
+##### TRGT repeat definition file to STRkit BED
+
+To convert from a TRGT repeat definition file to a STRkit BED, including locus IDs if set:
 
 ```bash
-strkit convert --in-format trgt --out-format strkit in_file.trgt.bed > out_file.bed
+strkit convert --in-format trgt --out-format strkit in_file.trgt.bed > out_file.strkit.bed
 ```
 
-Note that TRGT can represent STRs with complex structure that STRkit cannot, so some of these loci
-may not be converted (these will be logged to `stderr`).
+Where possible, multiple motifs will be reconciled using [IUPAC codes](https://www.bioinformatics.org/sms/iupac.html),
+which STRkit supports.
+
+Note that TRGT can represent STRs with complex structure that STRkit cannot. In these cases, the first motif in the TRGT 
+locus definition will be used and a message will be logged to `stderr`.
 
 
 ## Copyright and License

{strkit-0.25.0a1 → strkit-0.25.0a2}/pyproject.toml

@@ -1,3 +1,3 @@
 [build-system]
-requires = ["setuptools>=57.4.0", "wheel"]
+requires = ["setuptools>=82.0.1"]
 build-backend = "setuptools.build_meta"

{strkit-0.25.0a1 → strkit-0.25.0a2}/setup.py

@@ -15,15 +15,15 @@ setup(
     python_requires="~=3.10",
     install_requires=[
         "Flask>=2.2.5,<3.2",
-        "orjson>=3.9.15,<4",
+        "orjson>=3.11.1,<4",
         "pysam>=0.19,<0.24",
-        "numpy>=1.23.4,<1.27",
+        "numpy>=2.1.3,<3",
         "parasail>=1.2.4,<1.4",
         "pydantic>=2.11.7,<3",
         "scikit-learn>=1.2.1,<1.8",
         "scipy>=1.10,<1.17",
         "statsmodels>=0.14.0,<0.15",
-        "strkit_rust_ext==0.25.0",
+        "strkit_rust_ext==0.26.0",
     ],
 
     description="A toolkit for analyzing variation in short(ish) tandem repeats.",
@@ -38,7 +38,6 @@ setup(
         "Programming Language :: Python :: 3.12",
         "Programming Language :: Python :: 3.13",
         "Programming Language :: Python :: 3 :: Only",
-        "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
         "Operating System :: POSIX",
         "Operating System :: POSIX :: Linux",
         "Operating System :: MacOS :: MacOS X",
@@ -47,7 +46,7 @@ setup(
     author="David Lougheed",
     author_email="david.lougheed@gmail.com",
 
-    packages=setuptools.find_namespace_packages(),
+    packages=setuptools.find_namespace_packages(exclude=["tests"]),
     include_package_data=True,
 
     entry_points={

strkit-0.25.0a2/strkit/VERSION

@@ -0,0 +1 @@
+0.25.0a2