### Verify Installation with Example Data

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Run RepeatExplorer clustering on provided example data to verify the installation. This command uses the `seqclust` executable.

```bash
./seqclust -p -v tmp/clustering_output test_data/LAS_paired_10k.fas
```

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

### Install Dependencies and Compile Binaries

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Clone the repository, create and activate the conda environment, and compile the Louvain clustering binaries. Verify the installation using provided test data.

```bash
# Clone the repository
git clone https://bitbucket.org/petrnovak/repex_tarean.git
cd repex_tarean

# Create and activate the conda environment
conda env create -f environment.yml
conda activate repeatexplorer

# Compile Louvain clustering binaries and build BLAST databases
make

# Verify installation with provided test data (paired reads, 10k pairs)
./seqclust -p -v tmp/clustering_output test_data/LAS_paired_10k.fas
# Expected: output directory created at tmp/clustering_output/
#           containing index.html, cluster_report.html, CLUSTER_TABLE.csv, etc.

# Ensure reproducibility across runs
export PYTHONHASHSEED=0
```

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

### Clone and Navigate Repository

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Use git to clone the repository and change into the directory. This is the first step for command-line installation.

```bash
git clone https://bitbucket.org/petrnovak/repex_tarean.git
cd repex_tarean
```

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

### Prepare Working Directory and Test Data

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Sets up a local directory for analysis and downloads a sample FASTA file. Ensure you have wget installed.

```bash
mkdir working_dir && cd working_dir
wget https://bitbucket.org/petrnovak/repex_tarean/raw/devel/test_data/LAS_paired_10k.fas
```

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

### Pull and Run RepeatExplorer2 via Singularity

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Demonstrates how to pull and run the RepeatExplorer2 pipeline using a Singularity container, avoiding local installation. This is useful for environments where local installation is not feasible.

```bash
Pull and run RepeatExplorer2 from Singularity Hub without a local installation.
```

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

### Get Docker Container Help

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Display help information for the `seqclust` command when using the RepeatExplorer2 Docker container.

```bash
docker run kavonrtep/repeatexplorer:2.3.8 /repex_tarean/seqclust --help
```

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

### Create Conda Environment

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Prepare the required environment for RepeatExplorer2 dependencies using conda. Ensure miniconda is installed first.

```bash
conda env create -f environment.yml
```

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

### Run RepeatExplorer with Docker

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Execute RepeatExplorer2 clustering using a Docker container. This example demonstrates setting up a working directory, downloading test data, and running the analysis with volume mounting for data access.

```bash
# create working directory
mkdir working_dir && cd working_dir
# get test data - fasta file withj paired reads in interlaced format
wget https://bitbucket.org/petrnovak/repex_tarean/raw/devel/test_data/LAS_paired_10k.fas
# run clustering on test data in working directory
docker run -v  ${PWD}:/data kavonrtep/repeatexplorer:2.3.8 /repex_tarean/seqclust -p -v /data/re_output /data/LAS_paired_10k.fas
```

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

### Get Singularity Container Help

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Retrieve help information for the `seqclust` command within the RepeatExplorer2 Singularity container.

```bash
singularity exec shub://repeatexplorer/repex_tarean seqclust --help
```

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

### Run RepeatExplorer with Singularity

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Execute RepeatExplorer2 clustering using a Singularity container. This example includes creating a working directory, downloading test data, and running the analysis with specified output and input paths.

```bash
mkdir working_dir && cd working_dir
# get test data - fasta file with paired reads in interlaced format
wget https://bitbucket.org/petrnovak/repex_tarean/raw/devel/test_data/LAS_paired_10k.fas
singularity exec --bind ${PWD}:/data/ shub://repeatexplorer/repex_tarean seqclust -p -v /data/re_output /data/LAS_paired_10k.fas
```

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

### Add 32-bit Support on Ubuntu

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

If required, add 32-bit executable support on Ubuntu systems. This involves updating package lists and installing specific libraries.

```bash
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386
```

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

### Run Clustering with Docker

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Executes the seqclust command using Docker, mounting the current directory to /data. This command performs sequence clustering, similar to the Singularity example.

```bash
docker run -v ${PWD}:/data \
  kavonrtep/repeatexplorer:2.3.8 \
  /repex_tarean/seqclust -p -v /data/re_output /data/LAS_paired_10k.fas
```

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

### Getting Maximum CPU Count

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Retrieves the number of available CPUs for parallel processing. It checks configuration, environment variables, and system defaults.

```python
from lib.parallel.parallel import get_max_proc

n_cpu = get_max_proc()   # reads config.PROC → env PROC → cpu_count()
print(f"Using {n_cpu} CPU(s)")
```

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

### Start Rserve and Load R Functions with r2py

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Initiates an Rserve daemon and loads R scripts, exposing exported R functions as Python methods. Ensures Rserve is shut down automatically on pipeline exit.

```python
from lib import r2py
import config

# Start Rserve daemon (done once at pipeline startup)
port = r2py.create_connection()
# Tries: R CMD Rserve --RS-port <free_port> -q --no-save
# Prints: "Trying to start Rserve... connection OK"
# Registers atexit shutdown handler automatically

# Load TAREAN R functions
TAREAN = r2py.R(config.RSOURCE_tarean)   # lib/tarean/tarean.R
# All exported R functions become Python methods on the object

# Load reporting R functions for HTML output
REPORTING = r2py.R(config.RSOURCE_reporting)    # lib/reporting.R
ANNOTATION = r2py.R(config.RSOURCE_create_annotation)  # lib/create_annotation.R
```

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

### Get available CPU count

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Retrieves the number of available CPU cores to use for parallel processing, respecting configuration, environment variables, and system defaults.

```APIDOC
## get_max_proc

### Description
Returns the maximum number of CPU cores available for parallel processing.

### Usage
Reads from `config.PROC`, environment variable `PROC`, or system's default CPU count.

### Example
```python
from lib.parallel.parallel import get_max_proc

n_cpu = get_max_proc()   # reads config.PROC → env PROC → cpu_count()
print(f"Using {n_cpu} CPU(s)")
```
```

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

### Compile Source and Prepare Databases

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Compile the RepeatExplorer2 source code and prepare necessary databases. This command should be run from the `repex_tarean` directory.

```bash
make
```

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

### Instantiate and Analyze a Cluster Object

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Demonstrates how to instantiate a Cluster object directly for testing or analysis, and access its key attributes related to graph structure, satellite probability, and tandem repeat detection. This is useful for detailed inspection of individual clusters.

```python
from lib.graphtools import Cluster
import config

# Cluster is normally created internally by Graph.export_clusters_files_multiple,
# but can be instantiated directly for testing:
cl = Cluster(
    size=None,            # None → size == size_real (no subsampling)
    size_real=500,
    size_adjusted=500,
    blast_file="seqclust/clustering/clusters/dir_CL0001/hitsort_part.csv",
    fasta_file="seqclust/clustering/clusters/dir_CL0001/reads_selection.fasta",
    fasta_file_full="seqclust/clustering/clusters/dir_CL0001/reads.fasta",
    index=1,
    supercluster=1,
    paired=True,
    tRNA_database_path=config.TRNA_DATABASE,
    satellite_model_path=config.SATELLITE_MODEL,
    all_prefix_codes={},
    prefix_codes={},
    annotations={"blastn": "dir_CL0001/blastn_annotation.csv"},
    annotations_custom={}
)

# Key attributes after construction:
print(cl.loop_index)          # 0.0–1.0; high = tandem-like circular graph
print(cl.pair_completeness)   # fraction of pairs in same cluster
print(cl.satellite_probability)  # ML-based satellite score
print(cl.satellite)           # bool: True if classified as satellite
print(cl.putative_tandem)     # bool: True if sent to TAREAN

# Tandem rank codes:
# 1 = high-confidence satellite
# 2 = low-confidence tandem / putative satellite
# 3 = potential LTR element (has ORF or PBS)
# 4 = rDNA
# 0 = other / non-tandem
print(cl.tandem_rank)

# If putative_tandem is True, TAREAN outputs are populated:
print(cl.TR_monomer_length)   # satellite monomer length in bp
print(cl.TR_score)            # TAREAN tandem repeat score
print(cl.TR_consensus)        # consensus sequence string
print(cl.pbs_score)           # primer binding site score

# Human-readable summary
print(cl)
# cluster no 1:
# Number of vertices  : 500
# Number of edges     : 12345
# Loop index          : 0.87
# Pair completeness   : 0.72
# Orientation score   : 0.91

# Convert cluster attributes to dict (for CSV output)
d = cl.listing(asdict=True)
print(d.keys())

# LTR detection (requires CAP3 assembly output)
if cl.assembly_files.get('{}.{}.ace'):
    cl.detect_ltr(trna_database=config.TRNA_DATABASE)
    print(cl.ltr_detection)   # R evaluation result dict
```

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

### Import Configuration Settings

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Imports the configuration module, which centralizes pipeline settings, thresholds, and search parameters for different sequencing technologies.

```python
import config
```

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

### Accessing TAREAN Configuration Options

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Demonstrates how to access various configuration parameters for TAREAN, including protein databases, sequencing presets, and output file names. Ensure the config module is imported.

```python
import config

# --- Protein database selection ---
# Default: VIRIDIPLANTAE3.0
# Available: VIRIDIPLANTAE3.0, VIRIDIPLANTAE2.2, METAZOA2.0, METAZOA3.0
db_fasta, db_tree = config.PROTEIN_DATABASE_OPTIONS['VIRIDIPLANTAE3.0']
print(db_fasta)   # → .../databases/protein_database_viridiplantae_v3.0.fasta

# --- Sequencing technology presets ---
# ILLUMINA: mgblast all-to-all with dust filter (default)
# ILLUMINA_DUST_OFF: same but disables DUST low-complexity filter
# ILLUMINA_SHORT: blastn+ for reads <70 nt
# OXFORD_NANOPORE: LAST aligner for long reads

preset = config.ILLUMINA
print(preset.name)                    # → illumina
print(preset.filtering_threshold)
# FilteringThreshold(min_lcov=55, min_pid=90, min_ovl=0, min_scov=0, evalue=1)

# All-to-all search command template (filled in at runtime)
print(preset.all2all_search_params)
# mgblast -p 75 -W18 -UT -X40 -KT -JF -F "m D" -v100000000 -b100000000 -D4 -C 30 -H 30 -i {query} -d {blastdb}

# Annotation search parameters per annotation type
blastn_params = preset.annotation_search_params.blastn
print(blastn_params['program'])        # → blastn
print(blastn_params['args'])           # → -task blastn -num_alignments 1 -evalue 0.01

# --- Domain search options ---
# BLASTX_W3 (default), BLASTX_W2 (slowest/most sensitive), DIAMOND (fast)
print(config.DIAMOND['program'])      # → diamond blastx
print(config.DIAMOND['args'])         # → -p {max_proc} --max-target-seqs 1 ...

# --- Cluster/graph thresholds ---
print(config.MINIMUM_NUMBER_OF_READS_IN_CLUSTER)   # 20
print(config.CLUSTER_VMAX)                          # 40000 vertices max per cluster
print(config.CLUSTER_EMAX)                          # 2e7 edges max per cluster
print(config.SUPERCLUSTER_THRESHOLD)                # 0.1 mate-pair bond threshold

# --- Output file names ---
print(config.FILES['clusters_summary_csv'])         # → CLUSTER_TABLE.csv
print(config.FILES['tarean_report_html'])           # → tarean_report.html
print(config.FILES['TR_consensus_fasta'].format(1)) # → TAREAN_consensus_rank_1.fasta

# --- TAREAN rank thresholds ---
print(config.TANDEM_RANKS)                          # [1, 2, 3, 4]
print(config.ORF_THRESHOLD)                         # 1200 nt → rank 3 (LTR)
print(config.PBS_THRESHOLD)                         # 2 → rank 3 (LTR)
print(config.RDNA_THRESHOLD)                        # 20% blastn hits → rank 4
```

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

### seqclust Command-Line Option Reference

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Provides a comprehensive reference for all available command-line options for the `seqclust` executable, detailing parameters for clustering, annotation, and output configuration.

```bash
# --- Full option reference ---
# usage: seqclust [-h] [-p] [-A] [-t] [-l LOGFILE]
#   [-m 0.0..100.0]          minimum cluster size (% of reads)
#   [-M 0..1]                merge threshold for mate-pair cluster merging (0 = off)
#   [-o 30.0..80.0]          minimum overlap coverage (default 55)
#   [-c CPU]                 number of CPUs (0 = all available)
#   [-s SAMPLE]              subsample N reads before clustering
#   [-P PREFIX_LENGTH]       keep N chars of read name as species prefix (comparative analysis)
#   [-v OUTPUT_DIR]          output directory
#   [-r MAX_MEMORY]          max RAM in kB
#   [-d DATABASE NAME]       custom FASTA database + label for annotation
#   [-C]                     cleanup large intermediate files
#   [-k]                     keep original sequence names
#   [-a {2,3,4,5}]           minimum cluster size for CAP3 assembly (default 5)
#   [-tax {VIRIDIPLANTAE3.0,VIRIDIPLANTAE2.2,METAZOA2.0,METAZOA3.0}]
#   [-opt {ILLUMINA,ILLUMINA_DUST_OFF,ILLUMINA_SHORT,OXFORD_NANOPORE}]
#   [-D {BLASTX_W2,BLASTX_W3,DIAMOND}]
```

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

### Initialize SequenceSet from FASTA

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Loads paired reads from a FASTA file into an SQLite database. Options control renaming, species prefix, and random subsampling. The 'new=True' flag ensures a fresh database is created.

```python
from lib.seqtools import SequenceSet, Sequence
import os

os.chdir("tmp")

# Load paired reads from FASTA into an on-disk SQLite database
# - rename=True: replace original names with sequential integers
# - prefix_length=4: keep first 4 chars of name as species prefix (comparative mode)
# - sample_size=5000: randomly subsample 5000 reads (2500 pairs)
ss = SequenceSet(
    filename="sequences.db",
    source="../test_data/LAS_paired_10k.fas",
    sample_size=5000,
    new=True,
    paired=True,
    prefix_length=0,
    rename=True,
    seed=42,
    fasta="reads/reads.fasta"   # also write a FASTA file to disk
)

print(len(ss))          # number of reads loaded
print(ss)               # prints first 10 name:seq pairs + total count
```

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

### Build Graph and Run Louvain Clustering

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Constructs a graph from a hitsort file for paired reads, saves it, and performs Louvain clustering. Use this to identify communities within the sequence data.

```python
g = Graph(
    source="seqclust/clustering/hitsort",
    filename="seqclust/clustering/hitsort.db",
    new=True,
    paired=True,
    seqids=ss.keys()   # pass SequenceSet keys to build pairs table
)

# Save integer-indexed edge list for Louvain binaries
g.save_indexed_graph("seqclust/clustering/hitsort.int")

# Run Louvain clustering with mate-pair supercluster merging
# merge_threshold=0  → create superclusters but don't merge clusters
# merge_threshold=0.1 → merge clusters sharing >10% mate-pair bond into one
g.louvain_clustering(merge_threshold=0, cleanup=False)

print(f"Number of clusters: {g.number_of_clusters}")
print(f"Cluster sizes: {g.cluster_sizes[:10]}")   # top-10 sizes

# Get reads belonging to cluster 1
reads_cl1 = g.get_cluster_reads(1)
print(f"Cluster 1 has {len(reads_cl1)} reads")

# Get supercluster id for cluster 3
sc = g.get_cluster_supercluster(3)
print(f"Cluster 3 → supercluster {sc}")

# Export CLS file (used by TAREAN / reporting)
g.export_cls("seqclust/clustering/hitsort.cls")
# Format: >CL1\t<size>\n\t<read1>\t<read2>\t...\n
# Extract BLAST edges for cluster 1 to a file
E = g.extract_cluster_blast(
    path="seqclust/clustering/clusters/dir_CL0001/hitsort_part.csv",
    index=1
)
print(f"Cluster 1 has {E} graph edges")

# Export all cluster directories in parallel (runs TAREAN for tandem candidates)
clusters_info = g.export_clusters_files_multiple(
    min_size=config.MINIMUM_NUMBER_OF_READS_IN_CLUSTER,  # default 20
    directory="seqclust/clustering/clusters",
    sequences=ss,
    tRNA_database_path=config.TRNA_DATABASE,
    satellite_model_path=config.SATELLITE_MODEL
)
# Returns list of Cluster objects sorted by cluster index

# Adjust cluster sizes after satellite filtering
g.adjust_cluster_size(
    proportion_kept=config.FILTER_PROPORTION_OF_KEPT,  # 0.1
    ids_kept=ss.ids_kept
)

# Find superclusters manually (returns dict: old_com → merged_com)
com2newcom = g.find_superclusters(merge_threshold=0.1)
print(f"Merged {len(com2newcom)} clusters into superclusters")
```

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

### Build BLAST Databases

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Constructs BLAST databases (BLAST+, legacy formatdb, or LAST) from the sequences within a SequenceSet. This is a prerequisite for running similarity searches.

```python
# Build BLAST databases (BLAST+, legacy formatdb, LAST)
ss.makeblastdb(legacy=True)   # creates reads.fasta.nhr/.nin/.nsq + .legacy.*
```

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

### RepeatExplorer Command Line Usage

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

This is the general usage information for the RepeatExplorer command-line tool, outlining all available options for sequence analysis and classification.

```bash
usage: seqclust [-h] [-p] [-A] [-t] [-l LOGFILE] [-m {float range 0.0..100.0}]
                    [-M {0,float range 0.1..1}] [-o {float range 30.0..80.0}]
                    [-c CPU] [-s SAMPLE] [-P PREFIX_LENGTH] [-v OUTPUT_DIR]
                    [-r MAX_MEMORY] [-d DATABASE DATABASE] [-C] [-k]
                    [-a {2,3,4,5}]
                    [-tax {VIRIDIPLANTAE3.0,VIRIDIPLANTAE2.2,METAZOA2.0,METAZOA3.0}]
                    [-opt {ILLUMINA,ILLUMINA_DUST_OFF,ILLUMINA_SHORT,OXFORD_NANOPORE}]
                    [-D {BLASTX_W2,BLASTX_W3,DIAMOND}]
                    sequences
```

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

### Custom Protein Database for Annotation

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Uses a custom FASTA file as a protein database for annotation. Provide the database file and a label for the database.

```bash
# Custom protein database for annotation
./seqclust -p \
  -d custom_proteins.fasta MyCustomDB \
  -v custom_output \
  reads.fasta
```

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

### Compute Communities and Display Hierarchy

Source: https://github.com/petrnovak/repex_tarean/blob/devel/louvain/readme.txt

Computes communities using the Louvain algorithm and displays the hierarchical tree. Options include fast computation with modularity gain threshold and weighted graph support.

```bash
./community graph.bin -l -1 -v > graph.tree
```

```bash
./community graph.bin -l -1 -q 0.0001 > graph.tree
```

```bash
./community graph.bin -l -1 -w graph.weights > graph.tree
```

```bash
./community graph.bin -p graph.part -v
```

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

### Setting Environment Variables for TAREAN

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Shows how to override default environment variables for TAREAN to control temporary directory usage, memory limits, CPU allocation, and reproducibility. Requires the `os` module.

```python
import os
os.environ['PYTHONHASHSEED'] = '0'
os.environ['TEMP'] = '/scratch/tmp'
```

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

### Basic Single-Species Analysis with seqclust

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Orchestrates the full RepeatExplorer2 pipeline for single-species analysis using paired Illumina reads. Output is directed to a specified directory.

```bash
# Basic single-species analysis (paired Illumina reads, output to ./re_output)
./seqclust -p -v re_output reads.fasta
```

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

### Run Clustering with Pinned Singularity Version

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Ensures reproducibility by using a specific version of the Singularity image for the seqclust command. This is recommended for consistent results.

```bash
singularity exec shub://repeatexplorer/repex_tarean:0.3.8.dbaa07f \
  seqclust -p -v /data/re_output /data/LAS_paired_10k.fas
```

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

### Viridiplantae Analysis in TAREAN-Only Mode

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Runs Viridiplantae analysis focusing solely on tandem repeats using TAREAN, without full classification. Specify taxid and optimization options.

```bash
# Viridiplantae analysis, TAREAN-only mode (tandem repeats only, no full classification)
./seqclust -p -t \
  -tax VIRIDIPLANTAE3.0 \
  -opt ILLUMINA \
  -v tarean_output \
  reads.fasta
```

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

### Limit RAM and CPU, Cleanup Intermediate Files

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Limits the maximum RAM and CPU usage for the analysis and cleans up large intermediate files afterwards. Specify CPU count, max memory in kB, and the cleanup flag.

```bash
# Limit RAM and CPU; clean up large intermediate files afterwards
./seqclust -p \
  -c 4 \
  -r 16000000 \
  -C \
  -v re_output \
  reads.fasta
```

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

### Create Hitsort File for Similarity Search

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Performs an all-to-all similarity search using the sequences in the SequenceSet and generates a hitsort file. This file contains pairwise similarity information required for graph construction.

```python
# Run all-to-all similarity search and produce hitsort file
from config import ILLUMINA
hitsort_file = ss.create_hitsort(options=ILLUMINA, output="clustering/hitsort")
# hitsort format: seqA	seqB	bitscore	<alignment columns>
```

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

### Compute MD5 Checksum with lib.utils.md5checksum

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Calculates the MD5 checksum for a given file. Optionally handles missing files gracefully by returning a specific string instead of raising an error.

```python
from lib.utils import (
    md5checksum, FilePath,
    save_as_table,
    export_tandem_consensus, format_query
)

# MD5 checksum of a database file (used for integrity checks)
chk = md5checksum("databases/protein_database_viridiplantae_v3.0.fasta")
print(chk)   # → e.g. "d41d8cd98f00b204e9800998ecf8427e"

# Graceful missing-file handling
chk = md5checksum("nonexistent.fasta", fail_if_missing=False)
print(chk)   # → "Not calculated!!!!  File nonexistent.fasta is missing"
```

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

### Basic parallel execution

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

The `parallel` function executes a given callable across a list of argument tuples in parallel. It distributes arguments from multiple lists, broadcasting single-element lists to all jobs.

```APIDOC
## parallel

### Description
Executes a callable across a list of argument tuples in parallel.

### Signature
`parallel(command, arg_list_1, arg_list_2, ...)`

### Usage
Calls `command(arg_list_1[i], arg_list_2[i], ...)` for each `i` in parallel.

### Example
```python
from lib.parallel.parallel import parallel

def process_chunk(query_file, blastdb, output_file, options):
    # ... run mgblast ...
    return output_file

query_chunks = ["reads.fasta.0", "reads.fasta.1", "reads.fasta.2"]
output_parts = ["hitsort.0",     "hitsort.1",     "hitsort.2"]

results = parallel(
    process_chunk,
    query_chunks,           # list of first args
    ["reads.fasta.legacy"], # single-element list → broadcast to all jobs
    output_parts,
    [options]               # broadcast
)
# results: list of return values in input order
```
```

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

### Comparative Analysis Across Species

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Conducts comparative analysis across two species by interlacing FASTA files. The prefix_length option keeps a specified number of characters from the read name as the species prefix.

```bash
# Comparative analysis across two species (prefix_length keeps 4-char species prefix)
# Input: interlaced FASTA where read names start with species prefix (e.g., "SPE1_...")
./seqclust -p -P 4 \
  -tax VIRIDIPLANTAE3.0 \
  -v comparative_output \
  combined_species_reads.fasta
```

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

### Activate Conda Environment

Source: https://github.com/petrnovak/repex_tarean/blob/devel/README.md

Activate the conda environment created in the previous step to use RepeatExplorer2.

```bash
conda activate repeatexplorer
```

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

### Run Clustering with Singularity

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Executes the seqclust command using Singularity, binding the current directory to /data inside the container. This command performs sequence clustering on the provided FASTA file.

```bash
singularity exec --bind ${PWD}:/data/ \
  shub://repeatexplorer/repex_tarean \
  seqclust -p -v /data/re_output /data/LAS_paired_10k.fas
```

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

### Metazoa Analysis with DIAMOND and Satellite Filtering

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Performs Metazoa analysis using DIAMOND for domain search and includes automatic satellite filtering. Specify the taxid and number of CPUs.

```bash
# Metazoa analysis with DIAMOND domain search and automatic satellite filtering
./seqclust -p -A \
  -tax METAZOA3.0 \
  -D DIAMOND \
  -c 8 \
  -v re_output_metazoa \
  reads.fasta
```

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

### Basic Parallel Execution with `parallel`

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Executes a given callable across a list of argument tuples in parallel using the `multiprocessing` module. Arguments that are single-element lists are broadcast to all jobs.

```python
from lib.parallel.parallel import parallel

def process_chunk(query_file, blastdb, output_file, options):
    # ... run mgblast ...
    return output_file

query_chunks = ["reads.fasta.0", "reads.fasta.1", "reads.fasta.2"]
output_parts = ["hitsort.0",     "hitsort.1",     "hitsort.2"]

results = parallel(
    process_chunk,
    query_chunks,           # list of first args
    ["reads.fasta.legacy"], # single-element list → broadcast to all jobs
    output_parts,
    [options]               # broadcast
)
# results: list of return values in input order
```

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

### Cluster Read List Format

Source: https://github.com/petrnovak/repex_tarean/blob/devel/lib/tarean_output_help.org

Format of the 'hitsort.cls' file, which lists reads belonging to individual clusters.

```text
>CL1    11

```

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

### Oxford Nanopore Long Reads Analysis

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Analyzes Oxford Nanopore long reads by specifying the appropriate optimization option. Include taxid and output directory.

```bash
# Oxford Nanopore long reads
./seqclust -p \
  -opt OXFORD_NANOPORE \
  -tax VIRIDIPLANTAE3.0 \
  -v nanopore_output \
  nanopore_reads.fasta
```

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

### Access and Iterate Sequences in SequenceSet

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Demonstrates how to access individual sequences by name and iterate through all sequence names or Sequence objects within a SequenceSet. This is useful for inspecting or processing specific reads.

```python
# Access a single sequence by name
seq = ss["1f"]          # returns sequence string for read named "1f"

# Iterate over all read names
for name in ss:
    pass  # name is a string

# Iterate over Sequence objects
for seq_obj in ss.items():
    print(seq_obj.name, seq_obj.seq[:20])
```

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

### Format List for SQL IN Clause with lib.utils.format_query

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Formats a Python list of strings into a SQL-compatible IN clause string, enclosed in parentheses.

```python
# Format a Python list as an SQL IN clause string
ids = ["1f", "2r", "5f"]
q = format_query(ids)
print(q)   # → ("1f","2r","5f")
# Used in: cursor.execute("SELECT * FROM sequences WHERE name IN {}".format(q))
```

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

### Save List of Dicts as CSV with lib.utils.save_as_table

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Saves a list of dictionaries as a tab-separated CSV file. Requires a list of dictionaries and a path, with optional header specification.

```python
# Save list of dicts as a tab-separated CSV
save_as_table(
    d=[cl.listing() for cl in clusters_info],
    path="CLUSTER_TABLE.csv",
    header=["index", "size", "loop_index", "tandem_rank", "satellite_probability"]
)
```

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

### parallel2 with group exclusion and load control

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

The `parallel2` function extends `parallel` by adding group exclusivity (jobs with the same group ID do not run simultaneously) and fractional CPU load control (`ppn`).

```APIDOC
## parallel2

### Description
Executes a callable across a list of argument tuples in parallel, with added support for group exclusivity and fractional CPU load control.

### Parameters
- `groups` (list): Jobs with the same group ID are never run simultaneously.
- `ppn` (list): Fractional CPU load per job. The sum of running `ppn` must not exceed 1.0.

### Usage
Distributes arguments from multiple lists and applies group and load constraints.

### Example
```python
from lib.parallel.parallel import parallel2

cluster_jobs   = [cluster_args_0, cluster_args_1, cluster_args_2, cluster_args_3]
group_ids      = [1, 2, 1, 3]      # groups 1, 1 will never run together
load_fractions = [0.6, 0.4, 0.6, 0.2]

results = parallel2(
    Cluster,                  # callable — each call returns a Cluster object
    *[list(col) for col in zip(*cluster_jobs)],
    groups=group_ids,
    ppn=load_fractions
)
# results: list of Cluster objects in input order
```
```

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

### Convert Graph to Binary Format

Source: https://github.com/petrnovak/repex_tarean/blob/devel/louvain/readme.txt

Converts a text-based graph representation to a binary format for efficient processing. Supports unweighted, weighted, and renumbered node formats.

```bash
./convert -i graph.txt -o graph.bin
```

```bash
./convert -i graph.txt -o graph.bin -w graph.weights
```

```bash
./convert -i graph.txt -o graph.bin -r
```

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

### Handle File Paths with lib.utils.FilePath

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Uses a subclass of str that carries a .filepath=True flag for special handling by functions like save_as_table, enabling relative path emission in CSV output.

```python
# FilePath: a str subclass that carries a .filepath=True flag
# Used so save_as_table can emit relative paths in CSV output
p = FilePath("seqclust/clustering/clusters/dir_CL0001/index.html")
print(p.relative("seqclust/clustering/clusters"))
# → dir_CL0001/index.html
```

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

### Create Sequence Chunks for Parallel Processing

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Splits the sequences in a SequenceSet into smaller chunk files, suitable for parallel processing with tools like BLAST. The chunk_size parameter determines the number of reads per chunk.

```python
# Split into chunks of 5000 for parallel BLAST
chunk_files = ss.make_chunks(file_name="reads/reads.fasta", chunk_size=5000)
# returns: ["reads/reads.fasta.0", "reads/reads.fasta.1", ...]
```

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

### Analyze Community Hierarchy Structure

Source: https://github.com/petrnovak/repex_tarean/blob/devel/louvain/readme.txt

Analyzes the structure of the community hierarchy tree. Can display the number of levels and nodes per level, or the belonging of nodes to communities at a specific level.

```bash
./hierarchy graph.tree
```

```bash
./hierarchy graph.tree -l 2 > graph_node2comm_level2
```

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

### Advanced Parallel Execution with `parallel2`

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Extends `parallel` by adding group exclusion (jobs with the same group ID do not run concurrently) and fractional CPU load control (`ppn`). Useful for managing resource-intensive jobs.

```python
from lib.parallel.parallel import parallel2

# --- parallel2 with group exclusion and load control ---
# groups: jobs with the same group id are never run simultaneously
# ppn: fractional CPU load per job (sum of running ppn must not exceed 1.0)

cluster_jobs   = [cluster_args_0, cluster_args_1, cluster_args_2, cluster_args_3]
group_ids      = [1, 2, 1, 3]      # groups 1, 1 will never run together
load_fractions = [0.6, 0.4, 0.6, 0.2]

results = parallel2(
    Cluster,                  # callable — each call returns a Cluster object
    *[list(col) for col in zip(*cluster_jobs)],
    groups=group_ids,
    ppn=load_fractions
)
# results: list of Cluster objects in input order
```

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

### TAREAN Output Archive Structure

Source: https://github.com/petrnovak/repex_tarean/blob/devel/lib/tarean_output_help.org

Overview of the file and directory structure of the TAREAN analysis output archive.

```text
.
├── clusters_info.csv <------------ list of clusters in tab delimited format 
├── index.html        <------------ main html report
├── seqclust
│   ├── assembly                  # not implemented yet
│   ├── blastn        <------------ results of read comparison with DNA database
│   ├── blastx        <------------ results of read comparison with protein database
│   ├── clustering
│   │   ├── clusters
│   │   │   ├── dir_CL0001  <----┐- detailed information about clusters
│   │   │   ├── dir_CL0002  <----│
│   │   │   ├── dir_CL0003  <----│
│   │   │   ....            <----┘
│   │   │   
│   │   └── hitsort.cls  <--------- list of reads in individual clusters
│   ├── mgblast
│   └── sequences        <--------- input reads
├── summary                       # not implemented yet
├── TR_consensus_rank_1_.fasta  <-- reconstructed monomer sequences for HIGH confidence satellites
├── TR_consensus_rank_2_.fasta  <-- reconstructed monomer sequences for LOW confidence satellites
├── TR_consensus_rank_3_.fasta  <-- reconstructed sequences of potential LTR elements
└── TR_consensus_rank_4_.fasta  <-- reconstructed consensus for rDNA

```

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

### Call R Function: mgblast2graph with r2py

Source: https://context7.com/petrnovak/repex_tarean/llms.txt

Invokes the R function 'mgblast2graph' via the r2py bridge to build k-mer graphs and detect satellite DNA. Requires specific input files and configuration parameters.

```python
# Call R function: mgblast2graph (builds k-mer graph and detects satellite)
graph_info_str = TAREAN.mgblast2graph(
    blast_file="dir_CL0001/hitsort_part.csv",
    seqfile="dir_CL0001/reads_selection.fasta",
    seqfile_full="dir_CL0001/reads.fasta",
    graph_destination="dir_CL0001/graph_layout.GL",
    directed_graph_destination="dir_CL0001/graph_layout_directed.RData",
    oriented_sequences="dir_CL0001/reads_selection_oriented.fasta",
    image_file="dir_CL0001/graph_layout.png",
    image_file_tmb="dir_CL0001/graph_layout_tmb.png",
    repex=True,
    paired=True,
    satellite_model_path=config.SATELLITE_MODEL,
    maxv=config.CLUSTER_VMAX,
    maxe=config.CLUSTER_EMAX
)
graph_info = eval(graph_info_str)
# graph_info dict keys:
#   ecount, vcount, loop_index, pair_completeness,
#   escore (orientation score), satellite_probability, satellite (bool)
```