### Install REDItools3 from local wheel file

Source: https://github.com/bioinfouniba/reditools3/blob/main/README.md

Install REDItools3 using a local .whl file.

```bash
pip install dist/reditools-0.1-py3-none-any.whl
```

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

### Install REDItools3 from PyPi

Source: https://github.com/bioinfouniba/reditools3/blob/main/README.md

Install the REDItools3 package using pip.

```bash
pip install REDItools3
```

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

### Run REDItools3 from command line

Source: https://github.com/bioinfouniba/reditools3/blob/main/README.md

Execute REDItools3 from the command line after installation.

```bash
python -m reditools
```

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

### Read BED regions

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Use `read_bed_file` to parse BED files containing genomic regions. It yields region objects with contig, start, and stop attributes.

```python
for region in read_bed_file('targets.bed'):
    print(f"{region.contig}:{region.start}-{region.stop}")
```

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

### Import File Utility Functions

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Imports various file I/O utility functions from the reditools.file_utils module, including functions for opening streams, reading BED files, and loading splicing or text files.

```python
from reditools.file_utils import (
    open_stream,
    read_bed_file,
    load_splicing_file,
    load_text_file,
)
```

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

### Parse and Split Genomic Regions with Region Class

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Demonstrates parsing samtools-style region strings and creating Region objects. It also shows how to split a Region into fixed-size windows for parallel processing.

```python
from reditools.region import Region

# Parse samtools-style region strings
r1 = Region.parse_string('chr1:1,000,001-2,000,000')
# → ('chr1', 1000000, 2000000)  (converted to 0-based internally)

r2 = Region.from_string('chr1', 'sample.bam')
# → Region(contig='chr1', start=0, stop=<bam_reference_length>)

# Split into 1 Mb windows for parallel scatter
windows = r2.split(1_000_000)
for w in windows[:3]:
    print(str(w))
# chr1:1-1000000
# chr1:1000001-2000000
# chr1:2000001-3000000

# Use in analysis
region = Region(contig='chrM', start=0, stop=16569)
print(region)   # chrM:1-16569
```

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

### file_utils Functions

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

A collection of utility functions for file input/output operations, including transparent gzip support, reading BED files, and loading splice site information.

```APIDOC
## file_utils

### Description
Provides utility functions for file I/O, including compressed file handling and data loading.

### Functions
- `open_stream(filepath, mode='r')`: Opens a file with transparent gzip support.
- `read_bed_file(filepath)`: Reads a BED file into a list of tuples.
- `load_splicing_file(filepath)`: Loads splice site information from a file.
- `load_text_file(filepath)`: Loads the content of a text file.

### Parameters
- `filepath` (str): The path to the file.
- `mode` (str): The file opening mode (e.g., 'r', 'w').

### Request Example
```python
from reditools.file_utils import open_stream, read_bed_file

with open_stream('data.bed.gz') as f:
    bed_data = read_bed_file(f)
```

### Response
- `file object`: An opened file stream.
- `list[tuple]`: Data read from a BED file.
- `list`: Data loaded from splicing or text files.
```

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

### Configure REDItools Engine and Analyze Region

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Sets up the AlignmentManager with quality filters and configures the REDItools engine for strand-specific analysis. It then analyzes a specific genomic region and prints detailed variant information.

```python
from reditools.region import Region
from reditools.reditools import REDItools
from reditools.alignmentmanager import AlignmentManager

# Set up alignment manager with quality filters
manager = AlignmentManager(min_quality=20, min_length=50)
manager.add_file('sample_rna.bam')
manager.add_file('sample_rna_rep2.bam')  # optional second BAM

# Configure the REDItools engine
rt = REDItools()
rt.min_base_quality = 30
rt.strand = 1                         # forward-stranded library
rt.strand_confidence_threshold = 0.7
rt.use_strand_correction()            # filter to consensus strand
rt.add_reference('genome.fa')         # optional; use MD tags if absent
rt._min_read_quality = 20
rt._min_edits = 1                     # only yield positions with variants

# Analyze a specific region
region = Region(contig='chr1', start=0, stop=248956422)

for result in rt.analyze(manager, region):
    if not result.variants:
        continue
    print(
        f"{result.contig}\t"
        f"{result.position + 1}\t"     # convert to 1-based
        f"{result.reference}\t"
        f"{result.strand}\t"
        f"{len(result)}\t"             # total coverage
        f"{result.mean_quality:.2f}\t"
        f"[{result['A']}, {result['C']}, {result['G']}, {result['T']}]\t"
        f"{''.join(result.variants)}\t"
        f"{result.edit_ratio:.4f}"
    )
```

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

### Use Homopolymer Regions as Exclusion Mask

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Demonstrates how to use the output from `find-repeats` as an exclusion mask in the `analyze` tool to filter out repetitive regions.

```bash
python -m reditools analyze \
    sample_rna.bam \
    --exclude-regions homopolymers.bed.gz \
    --output-file filtered_editing.tsv
```

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

### Transparent gzip/plain file reading

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Use `open_stream` to read from gzipped or plain text files transparently. This is useful for iterating over lines in large files.

```python
with open_stream('data.tsv.gz', 'rt') as f:
    for line in f:
        print(line.strip())
```

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

### Analyze RNA Editing Events (Multi-BAM)

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Merges results from multiple BAM files (replicates) at analysis time. Requires a minimum read depth of 5 and uses 4 threads for processing.

```bash
python -m reditools analyze \
    rep1.bam rep2.bam rep3.bam \
    --output-file merged_editing.tsv \
    --min-read-depth 5 \
    --threads 4
```

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

### Load exclusion reads list

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Use `load_text_file` to load a list of items, such as read IDs, from a text file. Each line in the file becomes an element in the returned list.

```python
excluded = load_text_file('excluded_reads.txt')
# → ['read_001', 'read_002', ...]
```

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

### Load and expand splice sites

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Use `load_splicing_file` to load splice site information from a file. The `splicing_span` parameter allows expanding the regions by a specified number of base pairs.

```python
# Load splice sites and expand by ±4 bp (default span)
# Splice file format: CHR START STOP TYPE(A/D) STRAND(+/-)
for splice_region in load_splicing_file('splice_sites.txt', splicing_span=4):
    print(splice_region)
# Region(contig='chr1', start=10096, stop=10100)
```

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

### Analyze RNA Editing Events (Basic)

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Detects all editing events on all chromosomes using 4 threads. Requires a reference FASTA and outputs to a TSV file. Minimum read quality is 20 and minimum base quality is 30.

```bash
python -m reditools analyze \
    sample_rna.bam \
    --reference genome.fa \
    --output-file rna_editing.tsv \
    --threads 4 \
    --min-read-quality 20 \
    --min-base-quality 30 \
    --min-read-length 50
```

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

### Programmatic RNA Editing Analysis with REDItools

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Utilizes the REDItools class from the Python API for programmatic RNA editing analysis. Requires AlignmentManager and Region objects.

```python
from reditools.reditools import REDItools
from reditools.alignment_manager import AlignmentManager
from reditools.region import Region
```

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

### Compute RNA Editing Index

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Calculates per-substitution RNA Editing Indices from analyze output. Supports single or pooled input files, and can be restricted by genomic region, BED file targets, or exclusions.

```bash
python -m reditools index \
    rna_editing.tsv \
    --output-file editing_index.tsv
```

```bash
python -m reditools index \
    sample1_editing.tsv sample2_editing.tsv \
    --output-file pooled_index.tsv
```

```bash
python -m reditools index \
    rna_editing.tsv \
    --bed_file alu_regions.bed \
    --exclude_regions known_snps.bed \
    --output-file alu_editing_index.tsv
```

```bash
python -m reditools index \
    rna_editing.tsv \
    --region chr1:1-248956422 \
    --output-file chr1_index.tsv
```

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

### Analyze RNA Editing Events (Append Mode)

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Appends analysis results to an existing output file, useful for scatter-gather approaches across chromosomes. Each chromosome is processed with 2 threads.

```bash
for CHR in chr1 chr2 chr3; do
    python -m reditools analyze \
        sample_rna.bam \
        --region ${CHR} \
        --output-file all_editing.tsv \
        --append-file \
        --threads 2
done
```

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

### Expected Output Format

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

The expected tab-separated values (TSV) output format for the `analyze` tool, detailing RNA editing event information.

```text
# Region  Position  Reference  Strand  Coverage  MeanQ  BaseCount[A,C,G,T]  AllSubs  Frequency  gCoverage  gMeanQ  gBaseCount[A,C,G,T]  gAllSubs  gFrequency
# chr1    1115716   A          *       25        38.50  [18, 0, 7, 0]       AG       0.28       -          -       -                    -         -

```

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

### Find Homopolymeric Regions in Genome

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Scans a FASTA file for homopolymeric sequences of a specified minimum length. Output is a BED-like TSV suitable for use as an exclusion mask in the analyze tool.

```bash
python -m reditools find-repeats \
    genome.fa \
    --output homopolymers.bed.gz
```

```bash
python -m reditools find-repeats \
    genome.fa \
    --min-length 8 \
    --output homopolymers_l8.bed
```

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

### Annotate RNA editing output with genomic data

Source: https://github.com/bioinfouniba/reditools3/blob/main/README.md

Use the 'annotate' tool to enrich RNA editing output with variant data from genomic files. This process fills the last five columns of the RNA editing file with corresponding genomic information.

```text
Region	Position	Reference	Strand	Coverage	MeanQ	BaseCount[A,C,G,T]	AllSubs	Frequency	gCoverage	gMeanQ	gBaseCount[A,C,G,T]	gAllSubs	gFrequency
chr1	1115715	C	*	2	38.00	[0, 2, 0, 0]	-	0.00	-	-	-	-	-
chr1	1115716	A	*	2	38.00	[2, 0, 0, 0]	-	0.00	-	-	-	-	-
```

```text
Region	Position	Reference	Strand	Coverage	MeanQ	BaseCount[A,C,G,T]	AllSubs	Frequency	gCoverage	gMeanQ	gBaseCount[A,C,G,T]	gAllSubs	gFrequency
chr1	1115716	A	*	2	38.00	[2, 0, 0, 0]	-	0.00	-	-	-	-	-
chr1	1115717	C	*	2	38.00	[0, 2, 0, 0]	-	0.00	-	-	-	-	-
```

```text
Region	Position	Reference	Strand	Coverage	MeanQ	BaseCount[A,C,G,T]	AllSubs	Frequency	gCoverage	gMeanQ	gBaseCount[A,C,G,T]	gAllSubs	gFrequency
chr1	1115715	C	*	2	38.00	[0, 2, 0, 0]	-	0.00	-	-	-	-	-
chr1	1115716	A	*	2	38.00	[2, 0, 0, 0]	-	0.00	2	38.00	[2, 0, 0, 0]	-	0.00
```

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

### RTIndexer Class

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

The RTIndexer class allows for programmatic calculation of editing indices from REDItools output files. It supports filtering by target regions (e.g., from BED files) and exclusion lists.

```APIDOC
## RTIndexer

### Description
Calculates per-substitution editing indices from REDItools output files. Supports region targeting and exclusion.

### Methods
- `__init__(self, region=None)`: Initializes RTIndexer, optionally with a genomic region.
- `add_file(self, filepath)`: Adds a REDItools output file to process.
- `add_target_from_bed(self, bed_filepath)`: Adds target regions from a BED file.
- `add_exclusions_from_bed(self, bed_filepath)`: Adds exclusion regions from a BED file.
- `calc_index(self)`: Computes and returns the editing indices.

### Parameters
- `region` (Region, optional): A genomic region to restrict calculations to.

### Request Example
```python
from reditools.rtindexer import RTIndexer

indexer = RTIndexer()
indexer.add_rt_output('rna_editing.tsv')
indices = indexer.calc_index()
```

### Response
- `dict`: A dictionary where keys are transition types (e.g., 'A-G') and values are their corresponding editing indices.
```

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

### Annotate RNA Editing with DNA Data

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Cross-references RNA editing data with genomic DNA data to populate RNA table columns with DNA coverage and base information. Can use BAM or FASTA index for faster contig ordering.

```bash
python -m reditools annotate \
    rna_editing.tsv \
    dna_variants.tsv \
    > annotated_editing.tsv
```

```bash
python -m reditools annotate \
    rna_editing.tsv \
    dna_variants.tsv \
    --bam sample_rna.bam \
    > annotated_editing.tsv
```

```bash
python -m reditools annotate \
    rna_editing.tsv \
    dna_variants.tsv \
    --fai genome.fa.fai \
    > annotated_editing.tsv
```

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

### Analyze RNA Editing Events (Advanced)

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Performs A-to-G editing detection on a specific chromosome, using stranded library data and excluding homopolymeric regions. Requires a reference FASTA and outputs to a TSV file. Strict mode is enabled, and parallel processing is set to 8 threads with 1MB windows.

```bash
python -m reditools analyze \
    sample_rna.bam \
    --reference genome.fa \
    --region chr1:1-248956422 \
    --output-file chr1_AG_edits.tsv \
    --variants AG \
    --strand 1 \
    --strand-correction \
    --strand-confidence-threshold 0.7 \
    --min-read-depth 10 \
    --min-edits 1 \
    --max-editing-nucleotides 1 \
    --exclude-regions homopolymers.bed \
    --bed-file target_regions.bed \
    --threads 8 \
    --window 1000000
```

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

### Annotate RNA and DNA Editing Tables with RTAnnotater

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Merges RNA and DNA editing tables using the RTAnnotater class, yielding annotated row dictionaries. It can write output to stdout or be used to iterate over annotated rows for custom processing.

```python
import sys
from reditools.rtannotater import RTAnnotater
from reditools.tools.annotate.main import contig_order_from_fai

# Build contig order from FAI index
contig_order = contig_order_from_fai('genome.fa.fai')

# Annotate and write to stdout
rta = RTAnnotater(contig_order)
rta.annotate('rna_editing.tsv', 'dna_variants.tsv', sys.stdout)

# Or iterate over annotated rows for custom processing
for row in rta.merge_files('rna_editing.tsv', 'dna_variants.tsv'):
    g_coverage = row.get('gCoverage', '-')
    if g_coverage == '-':
        print(f"{row['Region']}:{row['Position']} — no DNA data")
    elif int(g_coverage) > 0 and row.get('gAllSubs', '-') == '-':
        # High DNA coverage, no DNA variant → confident RNA editing
        print(
            f"{row['Region']}:{row['Position']} "
            f"ref={row['Reference']} "
            f"freq={row['Frequency']} "
            f"(DNA cov={g_coverage}, no DNA variant)"
        )
```

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

### Calculate RNA Editing Indices with RTIndexer

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

Uses the RTIndexer class to calculate RNA editing indices from REDItools output files. Supports filtering by target regions (BED files) and exclusion regions (BED files), or by a specific genomic region tuple.

```python
from reditools.rtindexer import RTIndexer
from reditools.region import Region

# Calculate index over all positions in an output file
indexer = RTIndexer()
indexer.add_rt_output('rna_editing.tsv')
indices = indexer.calc_index()
for transition, index_val in sorted(indices.items()):
    print(f"{transition}\t{index_val:.4f}")
# A-G  5.8400  ← A-to-I RNA editing index

# Restrict to Alu elements and exclude SNP blacklist
indexer2 = RTIndexer()
indexer2.add_target_from_bed('alu_elements.bed')
indexer2.add_exclusions_from_bed('snp_blacklist.bed')
indexer2.add_rt_output('rna_editing.tsv')
alu_indices = indexer2.calc_index()
print(f"Alu A-G index: {alu_indices.get('A-G', 0):.4f}")

# Restrict by genomic region tuple (contig, start, stop)
region = Region.parse_string('chr1:1-248956422')
indexer3 = RTIndexer(region=region)
indexer3.add_rt_output('rna_editing.tsv')
chr1_indices = indexer3.calc_index()
```

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

### Region Class

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

The Region class represents a genomic interval and provides functionality for parsing samtools-style region strings and splitting regions into smaller windows for parallel processing.

```APIDOC
## Region

### Description
Represents a genomic interval, supporting parsing from strings and splitting into windows.

### Methods
- `parse_string(cls, region_string)`: Parses a samtools-style region string.
- `from_string(cls, contig, bam_filepath)`: Creates a Region from contig and BAM file reference length.
- `split(self, window_size)`: Splits the region into fixed-size windows.

### Parameters
- `region_string` (str): The region string to parse (e.g., 'chr1:1,000,001-2,000,000').
- `contig` (str): The chromosome or contig name.
- `bam_filepath` (str): Path to a BAM file to determine reference length.
- `window_size` (int): The size of each window when splitting.

### Request Example
```python
from reditools.region import Region

region = Region.parse_string('chr1:1-1000000')
windows = region.split(100000)
```

### Response
- `Region`: A Region object representing the genomic interval.
- `list[Region]`: A list of Region objects when splitting.
```

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

### RTAnnotater Class

Source: https://context7.com/bioinfouniba/reditools3/llms.txt

The RTAnnotater class facilitates the merging of RNA and DNA editing tables to produce annotated row dictionaries. It can output to standard output or be used for custom iteration.

```APIDOC
## RTAnnotater

### Description
Merges RNA and DNA editing tables programmatically, yielding annotated row dictionaries.

### Methods
- `__init__(self, contig_order)`: Initializes RTAnnotater with a contig order.
- `annotate(self, rna_file, dna_file, output_stream)`: Annotates and writes to the specified output stream.
- `merge_files(self, rna_file, dna_file)`: Returns an iterator over annotated rows.

### Parameters
- `contig_order` (list): A list defining the order of contigs.
- `rna_file` (str): Path to the RNA editing file.
- `dna_file` (str): Path to the DNA variants file.
- `output_stream`: A file-like object to write annotated data to.

### Request Example
```python
import sys
from reditools.rtannotater import RTAnnotater

rta = RTAnnotater(contig_order)
rta.annotate('rna_editing.tsv', 'dna_variants.tsv', sys.stdout)
```

### Response
- `dict`: Annotated row dictionaries containing merged RNA and DNA editing information.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.