FinaleToolkit

https://epifluidlab.github.io/FinaleToolkit/documentation/
Admin
FinaleToolkit is a comprehensive toolkit for analyzing cell-free DNA fragmentation patterns and...
Tokens:34,296
Snippets:165
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run FinaleToolkit from Terminal

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/user_guide/quickstart

This command executes the FinaleToolkit directly from the terminal interface. No specific inputs are required to start the application.

```bash
$ finaletoolkit

```

--------------------------------

### Install and Run Finaletoolkit Workflow

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/workflow_reference/installation

Commands to clone the Finaletoolkit repository, set up the Conda environment, install the toolkit via pip, and run the workflow using Snakemake. Assumes Conda is installed and configured.

```bash
git clone https://github.com/epifluidlab/finaletoolkit_workflow
cd finaletoolkit_workflow
conda env create -f environment.yml
conda activate finaletoolkit_workflow
pip install finaletoolkit
snakemake --configfile params.yaml --cores 4 --jobs 2
```

--------------------------------

### Example Fragment File Format

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/user_guide/inputdata

An example of a fragment file, which is a block-gzipped BED3+2 file containing fragment alignment information. It requires Tabix indexing for use with FinaleToolkit. The file includes columns for chromosome, start, stop, mapping quality, and strand.

```plaintext
#chrom    start    stop    mapq    strand
chr1    10000    10050    60    +
chr1    10050    10100    60    -
chr1    10100    10150    60    +
chr1    10150    10200    60    -
chr1    10200    10250    60    +
chr1    10250    10300    60    -
chr1    10300    10350    60    +
chr1    10350    10400    60    -
chr1    10400    10450    60    +
chr1    10450    10500    60    -
```

--------------------------------

### Install FinaleToolkit using pip

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/user_guide/installation

This command installs the FinaleToolkit package using pip. It is recommended to use a virtual environment for managing project dependencies.

```shell
pip install finaletoolkit
```

--------------------------------

### Import All Fragmentomics Functions (Python)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/user_guide/quickstart

This Python command imports all fragmentomic functions from the FinaleToolkit package. It's a convenient way to access the entire fragmentomics API.

```python
>>> import finaletoolkit.frag as ft

```

--------------------------------

### Import Specific Function (Python)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/user_guide/quickstart

This Python command imports a specific function, 'delfi', from the 'frag' module of the FinaleToolkit package. This allows for more granular control over imported functionalities.

```python
>>> from finaletoolkit.frag import delfi

```

--------------------------------

### Install curl using Homebrew for Mac ImportError

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/user_guide/installation

This command installs the 'curl' utility using Homebrew on macOS. This is a solution for 'ImportError' issues when running FinaleToolkit on a Mac.

```shell
$ brew install curl
```

--------------------------------

### FinaleToolkit Fragment Array Processing

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/fragfile

Reads from BAM, CRAM, or fragment files and returns a matrix with fragment start and stop positions and strand information.

```APIDOC
## GET /finaletoolkit/utils/frag_array

### Description
Reads from BAM, CRAM, or fragment files and returns a three-column matrix with fragment start and stop positions and strand.

### Method
GET

### Endpoint
/finaletoolkit/utils/frag_array

### Parameters
#### Query Parameters
- **input_file** (str | PathLike | AlignmentFile | TabixFile) - Required - Fragment coordinates stored as a BAM, CRAM, or tabix-indexed FinaleDB fragment file. Can also be a pysam object of these files.
- **contig** (str) - Required - Chromosome to fetch fragments over. May be None for genome-wide.
- **quality_threshold** (int) - Optional - Minimum mapping quality score for fragments. Defaults to 30.
- **start** (int) - Optional - Left-most coordinate of interval to fetch from.
- **stop** (int) - Optional - Right-most coordinate of interval to fetch from.
- **min_length** (int) - Optional - Specifies the lowest fragment length included in the array. Defaults to 120.
- **max_length** (int) - Optional - Specifies the highest fragment length included in the array. Defaults to 120.
- **intersect_policy** (str) - Optional - Specifies the policy used to include fragments in the given interval. Policies include: 'midpoint' (average of fragment end coordinates lies in the interval), 'any' (any part of the fragment is in the interval). Defaults to 'midpoint'.
- **verbose** (bool) - Optional - Enables verbose output. Defaults to False.

### Response
#### Success Response (200)
- **frag_ends** (Generator) - A generator yielding tuples of (contig: str, read_start: int, read_stop: int, mapq: int, read_on_plus: boolean).

#### Response Example
```json
{
  "frag_ends": "<generator object finaletoolkit.utils.frag_array at 0x...>"
}
```
```

--------------------------------

### Install Bioconda Packages using Conda

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/workflow_reference/dependencies

This command installs essential bioinformatics tools such as snakemake, bedtools, htslib, and samtools using the conda package manager from the Bioconda channel. This ensures compatibility and simplifies dependency management for genomic data analysis.

```bash
conda install -c bioconda snakemake bedtools htslib samtools
```

--------------------------------

### Generate Fragments from File

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/fragfile

Generates fragment data (contig, start, stop, mapq, strand) from BAM, CRAM, or Fragment files. It supports optional filtering by quality threshold, length, and intersection with specified regions. Returns a generator yielding fragment tuples.

```python
finaletoolkit.utils.frag_generator(_input_file : FragFile_, _contig : str | None_, _quality_threshold : int = 30_, _start : int | None = None_, _stop : int | None = None_, _min_length : int | None = None_, _max_length : int | None = None_, _intersect_policy : str = 'midpoint'_, _verbose : bool | int = False_) → Generator[tuple]
```

--------------------------------

### frag_generator

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/fragfile

Generates fragment data (contig, start, stop, mapq, strand) from BAM, CRAM, or Fragment files. Supports optional filtering by mapq, size, and region intersection.

```APIDOC
## GET /utils/frag_generator

### Description
Reads from BAM, CRAM, or Fragment files and yields tuples containing contig (chromosome), start, stop (end), mapq, and strand for each fragment. Optionally filters fragments by mapq, size, and intersection with a specified region.

### Method
GET

### Endpoint
/utils/frag_generator

### Parameters
#### Query Parameters
- **_input_file** (FragFile) - Required - Path to the input fragment file (BAM, CRAM, or Fragment file).
- **_contig** (str) - Optional - The contig (chromosome) to filter fragments by.
- **_quality_threshold** (int) - Optional - Minimum mapping quality score for fragments. Defaults to 30.
- **_start** (int) - Optional - The start coordinate for region intersection filtering.
- **_stop** (int) - Optional - The stop coordinate for region intersection filtering.
- **_min_length** (int) - Optional - Minimum length for fragments.
- **_max_length** (int) - Optional - Maximum length for fragments.
- **_intersect_policy** (str) - Optional - Policy for intersection with a region ('midpoint' or 'any'). Defaults to 'midpoint'.
- **_verbose** (bool or int) - Optional - Verbosity flag. Defaults to False.

### Request Body
(No request body specified, parameters are expected as query parameters)

### Response
#### Success Response (200)
- **fragments** (Generator[tuple]) - A generator yielding tuples of (contig, start, stop, mapq, strand) for each fragment.

#### Response Example
(Generator response, example shows a sample tuple)
{
  "fragments": [
    ["chr1", 1000, 1500, 40, "+"]
  ]
}
```

--------------------------------

### Print All Interval Frequencies to TSV

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/breakpointmotifs

Writes all intervals and their associated k-mer frequencies to a TSV file. The output includes columns for contig, start, stop, name, count, and k-mers. This is a comprehensive way to export interval-based motif frequency data.

```python
to_tsv(output_file: str | Path, calc_freq: bool = True, sep: str = '\t')
```

--------------------------------

### Write all interval frequencies to TSV

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/endmotifs

Writes all intervals and their associated k-mer frequencies to a tab-separated values (TSV) file. The output includes columns for contig, start, stop, name, count, and k-mer frequencies, with options to calculate frequencies or use raw counts.

```python
end_motif_intervals_instance.to_tsv(_output_file=path_to_output_file, _calc_freq=True, _sep='\t')
```

--------------------------------

### Calculate Raw Window Protection Scores (Python)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/wps

Calculates raw Windowed Protection Scores (WPS) over a specified genomic region [start, stop). It takes alignment files (BAM, CRAM, tabix) as input and returns WPS as a numpy structured array. Optional parameters control window size, fragment length inclusion, and quality thresholds.

```python
finaletoolkit.frag.wps(_input_file : str | AlignmentFile_, _chrom : str_, _start : int_, _stop : int_, _chrom_size : int_, _output_file : str | None = None_, _window_size : int = 120_, _min_length : int = 120_, _max_length : int = 180_, _quality_threshold : int = 30_, _verbose : bool | int = 0_, _fraction_low : int | None = None_, _fraction_high : int | None = None_) → ndarray
```

--------------------------------

### Calculate Raw Window Protection Score (WPS)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/wps

Computes raw Window Protection Scores (WPS) over a specified genomic region. It takes a BAM, CRAM, or tabix file as input and calculates scores based on fragment reads within the given start and stop coordinates.

```APIDOC
## POST /websites/epifluidlab_github_io_finaletoolkit/frag/wps

### Description
Computes raw Window Protection Scores (WPS) over a specified genomic region [start, stop).

### Method
POST

### Endpoint
`/websites/epifluidlab_github_io_finaletoolkit/frag/wps`

### Parameters
#### Query Parameters
- **_input_file** (str | AlignmentFile) - Required - BAM, CRAM or tabix file containing paired-end fragment reads or its path. AlignmentFile must be opened in read mode.
- **_chrom** (str) - Required - Chromosome name.
- **_start** (int) - Required - Starting position of the region.
- **_stop** (int) - Required - Stopping position of the region.
- **_chrom_size** (int) - Required - Size of the chromosome.
- **_output_file** (str | None) - Optional - Path to save the output file.
- **_window_size** (int) - Optional - Size of the window for WPS calculation. Default is 120.
- **_min_length** (int) - Optional - Minimum fragment length included in calculation. Default is 120.
- **_max_length** (int) - Optional - Maximum fragment length included in calculation. Default is 180.
- **_quality_threshold** (int) - Optional - Quality threshold for reads. Default is 30.
- **_verbose** (bool | int) - Optional - Verbosity level. Default is 0.
- **_fraction_low** (int | None) - Optional - Deprecated alias for min_length.
- **_fraction_high** (int | None) - Optional - Deprecated alias for max_length.

### Request Example
```json
{
  "_input_file": "path/to/your/reads.bam",
  "_chrom": "chr1",
  "_start": 10000,
  "_stop": 20000,
  "_chrom_size": 250000000,
  "_output_file": "wps_scores.npz"
}
```

### Response
#### Success Response (200)
- **scores** (ndarray) - A numpy struct array with columns 'contig', 'start', and 'wps'.

#### Response Example
```json
{
  "scores": [
    {"contig": "chr1", "start": 10000, "wps": 0.85},
    {"contig": "chr1", "start": 10120, "wps": 0.92}
  ]
}
```
```

--------------------------------

### Get Chromosome Arm for an Interval (ContigGaps)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/genomeutils

Returns the name of the chromosome arm for a given interval within a ContigGaps object. Returns 'NOARM' if the interval is within a centromere, telomere, or the short arm of an acrocentric chromosome. Requires start and stop coordinates.

```python
from finaletoolkit.genome import GenomeGaps

gaps = GenomeGaps._ucsc_hg19() # Example initialization
contig_gaps = gaps.get_contig_gaps(contig='chr1')
if contig_gaps:
    arm = contig_gaps.get_arm(start=1000, stop=2000)
```

--------------------------------

### FinaleToolkit CLI Usage

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/cli_reference/index

The main entry point for the FinaleToolkit CLI. It accepts global arguments and specifies available sub-commands for various analysis tasks.

```bash
usage: finaletoolkit [-h] [-v]
                     {coverage,frag-length-bins,frag-length-intervals,cleavage-profile,wps,adjust-wps,delfi,delfi-gc-correct,end-motifs,interval-end-motifs,breakpoint-motifs,interval-breakpoint-motifs,mds,interval-mds,filter-file,agg-bw,gap-bed}
                     ...
```

--------------------------------

### Get Chromosome Arm for an Interval (GenomeGaps)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/genomeutils

Retrieves the chromosome arm for a given genomic interval from a GenomeGaps object. Returns an empty string if the interval is in the short arm of an acrocentric chromosome or intersects a centromere. Requires contig, start, and stop coordinates.

```python
from finaletoolkit.genome import GenomeGaps

gaps = GenomeGaps._ucsc_hg19() # Example initialization
arm = gaps.get_arm(contig='chr1', start=1000, stop=2000)
```

--------------------------------

### Execute Snakemake Workflow (Bash)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/workflow_reference/quick_start

This snippet demonstrates how to execute the finaletoolkit workflow using Snakemake. It requires navigating to the workflow directory and specifying a configuration file, number of cores, and maximum concurrent jobs.

```bash
cd finaletoolkit_workflow
snakemake --configfile params.yaml --cores <cores> --jobs <jobs>
```

--------------------------------

### Get Fragment Lengths

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/basicfeatures

Retrieves the lengths of DNA fragments that meet specific criteria. This is useful for analyzing fragment size distributions.

```APIDOC
## POST /frag/frag_length

### Description
Return np.ndarray containing lengths of fragments in `input_file` that are above the quality threshold and are proper-paired reads.

### Method
POST

### Endpoint
/frag/frag_length

### Parameters
#### Request Body
- **input_file** (string | pysam.AlignmentFile | TabixFile) - Required - BAM, CRAM, or tabix-indexed containing paired-end fragment reads or its path. pysam wrappers must be opened in read mode.
- **contig** (string, optional) - Contig or chromosome to get fragments from.
- **start** (integer, optional) - 0-based left-most coordinate of interval.
- **stop** (integer, optional) - 1-based right-most coordinate of interval.
- **intersect_policy** (string, optional) - Specifies what policy is used to include fragments in the given interval. Default is “midpoint”. Policies include: - midpoint: the average of end coordinates of a fragment lies in the interval. - any: any part of the fragment is in the interval.
- **output_file** (string, optional) - Path to save the fragment lengths.
- **quality_threshold** (integer, optional) - Minimum MAPQ to accept for a fragment to be counted. Default is 30.
- **verbose** (boolean, optional) - Verbosity level. Default is False.

### Request Example
```json
{
  "input_file": "/path/to/fragments.bam",
  "contig": "chr1",
  "start": 10000,
  "stop": 20000,
  "intersect_policy": "any",
  "quality_threshold": 50,
  "verbose": true
}
```

### Response
#### Success Response (200)
- **lengths** (numpy.ndarray) - An array containing the lengths of the fragments.

#### Response Example
```json
{
  "lengths": [150, 210, 180, 250]
}
```
```

--------------------------------

### Submit Snakemake Workflow to SLURM (Bash)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/workflow_reference/quick_start

This snippet shows how to submit the finaletoolkit workflow to a SLURM cluster using Snakemake with a specific profile. Output is redirected to 'snakemake.log'.

```bash
cd finaletoolkit_workflow
snakemake --profile slurm_profile > snakemake.log 2>&1 &
```

--------------------------------

### Create BreakpointMotifFreqs from File

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/breakpointmotifs

Reads k-mer frequencies from a two-column tab-delimited file. It initializes a BreakpointMotifFreqs object, allowing for subsequent analysis of motif frequencies. Parameters include the file path, quality threshold, and optional delimiter and header line count.

```python
BreakpointMotifFreqs.from_file(file_path=str, quality_threshold=int, sep: str = '\t', header: int = 0)
```

--------------------------------

### Initialize EndMotifFreqs with k-mer frequencies

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/endmotifs

Initializes an EndMotifFreqs object with a given iterable of k-mer frequencies, k-mer size, and an optional quality threshold. This is useful for creating an instance directly from processed k-mer data.

```python
EndMotifFreqs(_kmer_frequencies=iterable_of_kmers, _k=k_value, _quality_threshold=quality_value)
```

--------------------------------

### GET /websites/epifluidlab_github_io_finaletoolkit/breakpoint_motif_freq

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/breakpointmotifs

Calculates the frequency of breakpoint motifs. This endpoint allows users to specify various parameters to filter and analyze sequence fragments for motif occurrences.

```APIDOC
## GET /websites/epifluidlab_github_io_finaletoolkit/breakpoint_motif_freq

### Description
Calculates the frequency of breakpoint motifs. This endpoint allows users to specify various parameters to filter and analyze sequence fragments for motif occurrences.

### Method
GET

### Endpoint
/websites/epifluidlab_github_io_finaletoolkit/breakpoint_motif_freq

### Parameters
#### Query Parameters
- **k** (int, optional) - Length of breakpoint motif kmer. Default is 6.
- **min_length** (int, optional) - Smallest fragment length accepted. Default is 50
- **max_length** (int, optional) - Longest fragment length accepted.
- **both_strands** (bool, optional) - Indicate whether to calculate 5’ breakpoint motifs on both positive and negative strands or not. If False, only 5’ ends of the positive strand are considered, unless the negative_strand option is set to True. Default is True.
- **negative_strand** (bool, optional) - Only considered if the both_strands option is False. When set to True, only ends on the negative strand are considered.
- **output_file** (str or None, optional) - File path to write results to. Either tsv or csv.
- **quality_threshold** (int, optional) - Minimum MAPQ to filter.
- **workers** (int, optional) - Number of worker processes.
- **verbose** (bool or int, optional)

### Response
#### Success Response (200)
- **breakpoint_motif_freq** (BreakpointMotifIntervals) - The calculated breakpoint motif frequencies.
```

--------------------------------

### Calculate Windowed Protection Score (WPS)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/cli_reference/index

Computes the Windowed Protection Score (WPS) over sites defined in a BED file using alignment data from a BAM/CRAM/Fragment file. This tool requires the input alignment file and a sorted BED file of sites. It outputs WPS values and allows customization of window size, fragment length filters, and quality thresholds.

```bash
finaletoolkit wps [-h] [-c CHROM_SIZES] [-o OUTPUT_FILE] [-i INTERVAL_SIZE] [-W WINDOW_SIZE] [-min MIN_LENGTH] [-max MAX_LENGTH] [-lo MIN_LENGTH] [-hi MAX_LENGTH] [-q QUALITY_THRESHOLD] [-w WORKERS] [-v] input_file site_bed
```

--------------------------------

### Calculate Cleavage Profile

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/cli_reference/index

Calculates the proportion of cleavage events over intervals defined in a BED file using alignment data from a BAM/CRAM/Fragment file. It requires input files for alignment data, intervals, and chromosome sizes. The output is a bigWig file. Options allow setting fragment length thresholds, quality thresholds, and interval padding.

```bash
finaletoolkit cleavage-profile [-h] [-o OUTPUT_FILE] [-min MIN_LENGTH] [-max MAX_LENGTH] [-lo MIN_LENGTH] [-hi MAX_LENGTH] [-q QUALITY_THRESHOLD] [-l LEFT] [-r RIGHT] [-w WORKERS] [-v] input_file interval_file chrom_sizes
```

--------------------------------

### Check if Interval is in Gap (ContigGaps)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/genomeutils

Determines if a specified genomic interval overlaps with any gap regions within a ContigGaps object. Requires start and stop coordinates for the interval.

```python
from finaletoolkit.genome import GenomeGaps

gaps = GenomeGaps._ucsc_hg19() # Example initialization
contig_gaps = gaps.get_contig_gaps(contig='chr1')
if contig_gaps:
    is_in_gap = contig_gaps.in_gap(start=1000, stop=2000)
```

--------------------------------

### Get ContigGaps for a Specific Chromosome

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/genomeutils

Creates a ContigGaps object for a specified chromosome, containing its centromere and telomere intervals. Returns None if no centromere information is available for the contig.

```python
from finaletoolkit.genome import GenomeGaps

gaps = GenomeGaps._ucsc_hg19() # Example initialization
contig_gaps = gaps.get_contig_gaps(contig='chr1')
```

--------------------------------

### FinaleToolkit: Calculate Coverage

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/cli_reference/index

Calculates fragmentation coverage over specified intervals from alignment data. Requires an input fragment file (BAM/CRAM/Fragment) and a BED file defining intervals. Outputs a BED file with coverage values. Options include normalization, length filtering, and quality thresholds.

```bash
finaletoolkit coverage [-h] [-o OUTPUT_FILE] [-n] [-s SCALE_FACTOR]
                       [-min MIN_LENGTH] [-max MAX_LENGTH] [-p {midpoint,any}]
                       [-q QUALITY_THRESHOLD] [-w WORKERS] [-v]
                       input_file interval_file
```

--------------------------------

### Read EndMotifFreqs from a file

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/endmotifs

Reads k-mer frequencies from a two-column tab-delimited file to initialize an EndMotifFreqs object. It allows specifying the file path, quality threshold, delimiter, and number of header lines to skip.

```python
_finaletoolkit.frag.EndMotifFreqs.from_file(_file_path=path_to_file, _quality_threshold=quality_value, _sep='\t', _header=0)
```

--------------------------------

### Calculate WPS Scores using Finaletoolkit

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/cli_reference/index

Calculates Windowed Protection Scores (WPS) over specified intervals. It takes input files like chromosome sizes, interval files, and outputs a bigWig file with WPS results. Key parameters include interval size, window size, and quality thresholds.

```bash
finaletoolkit adjust-wps [-h] [-o OUTPUT_FILE] [-i INTERVAL_SIZE]
                         [-m MEDIAN_WINDOW_SIZE] [-s SAVGOL_WINDOW_SIZE]
                         [-p SAVGOL_POLY_DEG] [-S] [-w WORKERS] [--mean]
                         [--subtract-edges] [--edge-size EDGE_SIZE] [-v]
                         input_file interval_file chrom_sizes

```

--------------------------------

### Get frequency of a specific k-mer within intervals

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/endmotifs

Retrieves the frequency of a specified k-mer across all intervals stored in an EndMotifsIntervals object. The output includes the genomic interval and the associated frequency.

```python
end_motif_intervals_instance.freq(_kmer='your_kmer_string')
```

--------------------------------

### Initialize EndMotifsIntervals with interval data

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/endmotifs

Initializes an EndMotifsIntervals object with a list of genomic intervals and their associated k-mer frequencies, k-mer size, and an optional quality threshold. This constructor is used when you have pre-computed interval data.

```python
EndMotifsIntervals(_intervals=list_of_intervals_and_freqs, _k=k_value, _quality_threshold=quality_value)
```

--------------------------------

### Check if Interval is in Telomere or Centromere (ContigGaps)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/genomeutils

Checks if a specified genomic interval falls within a centromere or telomere region defined in a ContigGaps object. Requires start and stop coordinates for the interval.

```python
from finaletoolkit.genome import GenomeGaps

gaps = GenomeGaps._ucsc_hg19() # Example initialization
contig_gaps = gaps.get_contig_gaps(contig='chr1')
if contig_gaps:
    is_in_tcmere = contig_gaps.in_tcmere(start=1000, stop=2000)
```

--------------------------------

### Genome Utilities - ucsc_hg38_gap_bed()

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/index

Generates BED format data for UCSC hg38 gaps. This function retrieves and formats gap information for the hg38 genome build.

```python
ucsc_hg38_gap_bed()
```

--------------------------------

### Check if Interval is in Telomere or Centromere (GenomeGaps)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/genomeutils

Determines if a specified genomic interval falls within a telomere or centromere region using a GenomeGaps object. Requires contig, start, and stop coordinates.

```python
from finaletoolkit.genome import GenomeGaps

gaps = GenomeGaps._ucsc_hg19() # Example initialization
is_in_tcmere = gaps.in_tcmere(contig='chr1', start=1000, stop=2000)
```

--------------------------------

### Check if Interval Overlaps a Gap (GenomeGaps)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/genomeutils

Checks if a given genomic interval overlaps with any gap regions (telomere, centromere, short arm) defined in a GenomeGaps object. Requires contig, start, and stop coordinates.

```python
from finaletoolkit.genome import GenomeGaps

gaps = GenomeGaps._ucsc_hg19() # Example initialization
overlaps = gaps.overlaps_gap(contig='chr1', start=1000, stop=2000)
```

--------------------------------

### Frag File Utilities - chrom_sizes_to_list()

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/index

Converts chromosome sizes to a list format. This utility function processes chromosome size information for use in downstream analysis.

```python
chrom_sizes_to_list()
```

--------------------------------

### Read EndMotifsIntervals from a file

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/endmotifs

Reads k-mer frequency data from a delimited file to initialize an EndMotifsIntervals object. This method supports custom delimiters and header lines, expecting columns like contig, start, stop, name, count, and k-mers.

```python
_finaletoolkit.frag.EndMotifsIntervals.from_file(_file_path=path_to_file, _quality_threshold=quality_value, _sep=',', _header=0)
```

--------------------------------

### chrom_sizes_to_list

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/fragfile

Reads chromosome names and sizes from a CHROMSIZE file and returns them as a list of tuples.

```APIDOC
## GET /utils/chrom_sizes_to_list

### Description
Reads chromosome names and sizes from a CHROMSIZE file and returns them as a list of (chromosome_name, size) tuples.

### Method
GET

### Endpoint
/utils/chrom_sizes_to_list

### Parameters
#### Query Parameters
- **_chrom_sizes_file** (str) - Required - Path to the tab-delimited CHROMSIZE file (columns: chrom names, chrom sizes).

### Request Body
(No request body specified, parameters are expected as query parameters)

### Response
#### Success Response (200)
- **chrom_sizes** (list[tuple[str, int]]) - A list of tuples, where each tuple contains a chromosome name (string) and its size (integer).

#### Response Example
{
  "chrom_sizes": [
    ["chr1", 248956422],
    ["chr2", 242193529]
  ]
}
```

--------------------------------

### Breakpoint Motifs API

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/breakpointmotifs

Calculates 5' k-mer breakpoint motif frequencies from BAM, CRAM, or tabix indexed files, with optional output to a file.

```APIDOC
## POST /websites/epifluidlab_github_io_finaletoolkit/breakpoint_motifs

### Description
This endpoint reads fragments from a BAM, CRAM, or tabix indexed file and returns the 5’ k-mer breakpoint motif frequencies as a dictionary. It can optionally write the results to a TSV or CSV file.

### Method
POST

### Endpoint
/websites/epifluidlab_github_io_finaletoolkit/breakpoint_motifs

### Parameters
#### Query Parameters
- **_input_file** (str) - Required - BAM, CRAM, or Frag.gz file with paired-end reads.
- **_refseq_file** (str | Path) - Required - 2bit file with sequence of reference genome input_file is aligned to.
- **_k** (int) - Optional - Length of breakpoint motif kmer. Default is 6.
- **_min_length** (int | None) - Optional - Minimum length of fragments to be included. Default is 50.
- **_max_length** (int | None) - Optional - Maximum length of fragments to be included.
- **_both_strands** (bool) - Optional - Indicate whether to calculate 5’ breakpoint motifs on both positive and negative strands or not. If False, only 5’ ends of the positive strand are considered, unless the negative_strand option is set to True. Default is True.
- **_negative_strand** (bool) - Optional - Only considered if the both_strands option is False. When set to True, only ends on the negative strand are considered. Default is False.
- **_output_file** (None | str) - Optional - File path to write results to. Either tsv or csv. Default is None.
- **_quality_threshold** (int) - Optional - Minimum MAPQ to filter. Default is 30.
- **_workers** (int) - Optional - Number of worker processes. Default is 1.
- **_verbose** (bool | int) - Optional - Verbosity flag.
- **_fraction_low** (int | None) - Optional - Alias for min_length. Deprecated.
- **_fraction_high** (int | None) - Optional - Alias for max_length. Deprecated.

### Request Example
```json
{
  "_input_file": "/path/to/your/reads.bam",
  "_refseq_file": "/path/to/reference.2bit",
  "_k": 8,
  "_min_length": 100,
  "_max_length": 1000,
  "_output_file": "/path/to/output.tsv",
  "_quality_threshold": 40,
  "_workers": 4,
  "_verbose": true
}
```

### Response
#### Success Response (200)
- **breakpoint_motif_freq** (BreakpointMotifFreqs) - A dictionary containing the breakpoint motif frequencies.

#### Response Example
```json
{
  "breakpoint_motif_freq": {
    "motifA": 50,
    "motifB": 75
  }
}
```
```

--------------------------------

### Get K-mer Frequency for Specific Interval (BreakpointMotifsIntervals)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/breakpointmotifs

Returns a dictionary mapping genomic intervals to the frequency of a specified k-mer. This method is part of the BreakpointMotifsIntervals class and helps in retrieving detailed frequency information for a particular motif within defined regions.

```python
freq(kmer: str) -> dict[tuple[str, int, int], float]
```

--------------------------------

### Interval Breakpoint Motifs API

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/breakpointmotifs

Calculates 5' k-mer breakpoint motif frequencies for user-specified intervals from BAM, CRAM, or tabix indexed files.

```APIDOC
## POST /websites/epifluidlab_github_io_finaletoolkit/interval_breakpoint_motifs

### Description
This endpoint reads fragments from a BAM, CRAM, or tabix indexed file and user-specified intervals, then returns the 5’ k-mer breakpoint motif frequencies. It can optionally write the data to a TSV file.

### Method
POST

### Endpoint
/websites/epifluidlab_github_io_finaletoolkit/interval_breakpoint_motifs

### Parameters
#### Query Parameters
- **_input_file** (str) - Required - Path of BAM, CRAM, or Frag.gz containing pair-end reads.
- **_refseq_file** (str | Path) - Required - Path of 2bit file for reference genome that reads are aligned to.
- **_intervals** (str | Iterable[tuple[str, int, int, str]]) - Required - Path of BED file containing intervals or list of tuples (chrom, start, stop, name).
- **_k** (int) - Optional - Length of breakpoint motif kmer. Default is 6.
- **_min_length** (int | None) - Optional - Minimum length of fragments to be included. Default is 50.
- **_max_length** (int | None) - Optional - Maximum length of fragments to be included.
- **_both_strands** (bool) - Optional - Choose whether to use forward 5’ ends only or use 5’ ends for both ends of PE reads. If negative_strand is True, only reverse 5’ ends are used. Default is True.
- **_negative_strand** (bool) - Optional - Only considered if the both_strands option is False. When set to True, only ends on the negative strand are considered. Default is False.
- **_output_file** (str | None) - Optional - File path to write results to. Default is None.
- **_quality_threshold** (int) - Optional - Minimum MAPQ to filter. Default is 30.
- **_workers** (int) - Optional - Number of worker processes. Default is 1.
- **_verbose** (bool | int) - Optional - Verbosity flag.
- **_fraction_low** (int | None) - Optional - Alias for min_length. Deprecated.
- **_fraction_high** (int | None) - Optional - Alias for max_length. Deprecated.

### Request Example
```json
{
  "_input_file": "/path/to/your/reads.bam",
  "_refseq_file": "/path/to/reference.2bit",
  "_intervals": "/path/to/your/intervals.bed",
  "_k": 10,
  "_min_length": 75,
  "_quality_threshold": 50
}
```

### Response
#### Success Response (200)
- **breakpoint_motif_freq** (BreakpointMotifsIntervals) - A dictionary containing the breakpoint motif frequencies for the specified intervals.

#### Response Example
```json
{
  "breakpoint_motif_freq": {
    "interval1": {
      "motifX": 25,
      "motifY": 30
    },
    "interval2": {
      "motifX": 40,
      "motifY": 35
    }
  }
}
```
```

--------------------------------

### Run DELFI Analysis (Python)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/delfi

Executes the DELFI analysis pipeline replicating Christiano et al (2019) methodology. It requires input fragment reads, chromosome sizes, bin information, and reference genome files. Optional parameters control GC correction, low-coverage window removal, bin merging, window size, and verbosity. The function returns a pandas DataFrame with the analysis results.

```python
finaletoolkit.frag.delfi(_input_file : str_, _chrom_sizes : str_, _bins_file : str_, _reference_file : str_, _blacklist_file : str = None_, _gap_file : str | GenomeGaps = None_, _output_file : str = None_, _no_gc_correct : bool = False_, _gc_correct : bool | None = None_, _remove_nocov : bool = True_, _merge_bins : bool = True_, _window_size : int = 5000000_, _quality_threshold : int = 30_, _workers : int = 1_, _verbose : int | bool = False_) → DataFrame
```

--------------------------------

### interval-end-motifs

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/cli_reference/index

Measures frequency of k-mer 5’ end motifs in each region specified in a BED file and writes data into a table.

```APIDOC
## interval-end-motifs

### Description
Measures frequency of k-mer 5’ end motifs in each region specified in a BED file and writes data into a table.

### Method
CLI COMMAND

### Endpoint
finaletoolkit interval-end-motifs

### Parameters
#### Positional Arguments
- **input_file** (BAM/CRAM/Fragment file) - Required - Path to a BAM/CRAM/Fragment file containing fragment data.
- **refseq_file** (.2bit file) - Required - The .2bit file for the associate reference genome sequence used during alignment.
- **intervals** (BED file) - Required - Path to a BED file containing intervals to retrieve end motif frequencies over.

#### Named Arguments
- **-k** (integer) - Optional - Length of k-mer.
- **-min, --min-length** (integer) - Optional - Minimum length for a fragment to be included.
- **-max, --max-length** (integer) - Optional - Maximum length for a fragment to be included.
- **-lo, --min-length** (integer) - Optional - Minimum length for a fragment to be included.
- **-hi, --max-length** (integer) - Optional - Maximum length for a fragment to be included.
- **-B, --no-both-strands** (boolean) - Optional - Set flag to only consider one strand for end-motifs. Default: True
- **-n, --negative-strand** (boolean) - Optional - Set flag in conjunction with -B to only consider 5’ end motifs on the negative strand. Default: False
- **-o, --output-file** (TSV file) - Optional - TSV to print k-mer frequencies. If "-", will write to stdout. Default: "-"
- **-q, --quality-threshold** (integer) - Optional - Minimum mapping quality threshold. Default: 20
- **-w, --workers** (integer) - Optional - Number of worker processes. Default: 1
- **-v, --verbose** (boolean) - Optional - Enable verbose mode to display detailed processing information. Default: False
```

--------------------------------

### Generate Fragment Ends Array

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/fragfile

Reads fragment coordinates from BAM, CRAM, or tabix-indexed FinaleDB files and returns a matrix containing fragment start and stop positions along with strand information. It accepts various input file types and allows filtering by quality threshold, specific genomic intervals, fragment length, and intersection policy. The output is a NumPy array suitable for further analysis.

```python
finaletoolkit.utils.frag_array(_input_file : str | PathLike | AlignmentFile | TabixFile_, _contig : str_, _quality_threshold : int = 30_, _start : int | None = None_, _stop : int | None = None_, _min_length : int | None = None_, _max_length : int | None = None_, _intersect_policy : str = 'midpoint'_, _verbose : bool = False_)

Reads from BAM, CRAM, or fragment file and returns a three column matrix with fragment start and stop positions and strand. 

Parameters:
    
  * **input_file** (_str_ _or_ _AlignmentFile_)
  * **contig** (_str_)
  * **quality_threshold** (_int_ _,__optional_)
  * **start** (_int_ _,__optional_)
  * **stop** (_int_ _,__optional_)
  * **min_length** (_int_ _,__optional_) – Specifies lowest fragment length included in array. Default is 120, equivalent to long fraction.
  * **max_length** (_int_ _,__optional_) – Specifies highest fragment length included in array. Default is 120, equivalent to long fraction. intersect_policy : str, optional Specifies what policy is used to include fragments in the given interval. Default is “midpoint”. Policies include: - midpoint: the average of end coordinates of a fragment lies in the interval. - any: any part of the fragment is in the interval.
  * **verbose** (_bool_ _,__optional_)

Returns:
    
**frag_ends** – ‘NDArray’ with shape (n, 3) where column 1 contains fragment start position and column 2 contains fragment stop position, and column3 is 1 of on the + strand and is 0 if on the - strand. If no fragments exist in the specified minimum-maximum interval, the returned ‘ndarray’ will have a shape of (0, 3) 

Return type:
    
NDArray
```

--------------------------------

### DELFI Analysis (delfi)

Source: https://epifluidlab.github.io/FinaleToolkit/documentation/api_reference/delfi

Replicates the methodology of Christiano et al (2019) for DELFI analysis. It processes PE fragment reads and generates a DataFrame with analysis results.

```APIDOC
## POST /websites/epifluidlab_github_io_finaletoolkit/delfi

### Description
A function that replicates the methodology of Christiano et al (2019) for DELFI analysis, processing PE fragment reads to generate analysis results.

### Method
POST

### Endpoint
/websites/epifluidlab_github_io_finaletoolkit/delfi

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **_input_file** (str) - Required - Path string pointing to a bam file containing PE fragment reads.
- **_chrom_sizes** (str) - Required - Path string to a chrom.sizes file containing only autosomal chromosomes.
- **_bins_file** (str) - Required - Path string to a BED file containing 100kb bins for reference genome of choice.
- **_reference_file** (str) - Required - Path string to .2bit file for reference genome.
- **_gap_file** (str | GenomeGaps) - Optional - Specifies locations of telomeres and centromeres for reference genome. Can be a BED4+ file, a reference genome string ('b37', 'hg19', 'hg38', 'GRCh38'), or a GenomeGaps object.
- **_blacklist_file** (str) - Optional - Path string to BED file containing genome blacklist regions.
- **_output_file** (str) - Optional - Path to output tsv.
- **_no_gc_correct** (bool) - Optional - Skip gc-correction. Default is False.
- **_gc_correct** (bool) - Optional - Deprecated command to perform gc-correction. Use no_gc_correct instead.
- **_remove_nocov** (bool) - Optional - Remove two windows described by Cristiano et al (2019) as low coverage. Default is True.
- **_merge_bins** (bool) - Optional - Perform merging from 100kb bins to 5Mb bins. Default is True.
- **_window_size** (int) - Optional - Size (in bases) of non-overlapping windows to cover genome. Default is 5000000.
- **_quality_threshold** (int) - Optional - Quality threshold for reads. Default is 30.
- **_workers** (int) - Optional - Number of worker processes to use. Default is 1.
- **_verbose** (int | bool) - Optional - Determines how many print statements and loading bars appear in stdout. Default is False.

### Request Example
```json
{
  "_input_file": "/path/to/reads.bam",
  "_chrom_sizes": "/path/to/chrom.sizes",
  "_bins_file": "/path/to/bins.bed",
  "_reference_file": "/path/to/reference.2bit",
  "_gap_file": "hg19",
  "_blacklist_file": "/path/to/blacklist.bed",
  "_output_file": "/path/to/output.tsv",
  "_no_gc_correct": false,
  "_remove_nocov": true,
  "_merge_bins": true,
  "_window_size": 5000000,
  "_quality_threshold": 30,
  "_workers": 4,
  "_verbose": true
}
```

### Response
#### Success Response (200)
- **DataFrame** (pandas DataFrame) - Results of DELFI analysis, with column names corresponding to those generated by the original author’s scripts.

#### Response Example
```json
{
  "example": "DataFrame with analysis results"
}
```
```
Tokens:
Raw