mirna-toolkit 0.1.0__py3-none-any.whl

mirna_toolkit/__init__.py

@@ -0,0 +1,17 @@
+"""miRNA-Toolkit public package API."""
+
+from . import alignment, batch, disease, io, ml, pipeline, prediction, quantification, visualization
+
+__all__ = [
+    "alignment",
+    "batch",
+    "disease",
+    "io",
+    "ml",
+    "pipeline",
+    "prediction",
+    "quantification",
+    "visualization",
+]
+
+__version__ = "0.1.0"

mirna_toolkit/alignment/__init__.py

@@ -0,0 +1,6 @@
+from . import bowtie, hisat2, star
+from .bowtie import align as bowtie_align
+from .hisat2 import align as hisat2_align
+from .star import align as star_align
+
+__all__ = ["bowtie", "bowtie_align", "hisat2", "hisat2_align", "star", "star_align"]

mirna_toolkit/alignment/bowtie.py

@@ -0,0 +1,21 @@
+import subprocess
+from pathlib import Path
+
+
+def align(
+    fastq_path: str | Path,
+    reference: str | Path,
+    output_bam: str | Path | None = None,
+    threads: int = 4,
+) -> Path:
+    """Align reads with Bowtie and return BAM path."""
+    fastq = Path(fastq_path)
+    output = Path(output_bam) if output_bam else fastq.with_suffix(".bowtie.bam")
+    sam = output.with_suffix(".sam")
+
+    subprocess.run(
+        ["bowtie", "-p", str(threads), "-S", str(reference), str(fastq), str(sam)],
+        check=True,
+    )
+    subprocess.run(["samtools", "view", "-bS", str(sam), "-o", str(output)], check=True)
+    return output

mirna_toolkit/alignment/hisat2.py

@@ -0,0 +1,21 @@
+import subprocess
+from pathlib import Path
+
+
+def align(
+    fastq_path: str | Path,
+    reference: str | Path,
+    output_bam: str | Path | None = None,
+    threads: int = 4,
+) -> Path:
+    """Align reads with HISAT2 and return BAM path."""
+    fastq = Path(fastq_path)
+    output = Path(output_bam) if output_bam else fastq.with_suffix(".hisat2.bam")
+    sam = output.with_suffix(".sam")
+
+    subprocess.run(
+        ["hisat2", "-p", str(threads), "-x", str(reference), "-U", str(fastq), "-S", str(sam)],
+        check=True,
+    )
+    subprocess.run(["samtools", "view", "-bS", str(sam), "-o", str(output)], check=True)
+    return output

mirna_toolkit/alignment/star.py

@@ -0,0 +1,37 @@
+import subprocess
+from pathlib import Path
+
+
+def align(
+    fastq_path: str | Path,
+    reference: str | Path,
+    output_bam: str | Path | None = None,
+    threads: int = 4,
+    small_rna_mode: bool = True,
+) -> Path:
+    """Align reads with STAR in small-RNA-friendly settings and return BAM path."""
+    fastq = Path(fastq_path)
+    output = Path(output_bam) if output_bam else fastq.with_suffix(".star.bam")
+    prefix = output.with_suffix("")
+
+    cmd = [
+        "STAR",
+        "--genomeDir",
+        str(reference),
+        "--readFilesIn",
+        str(fastq),
+        "--runThreadN",
+        str(threads),
+        "--outSAMtype",
+        "BAM",
+        "Unsorted",
+        "--outFileNamePrefix",
+        f"{prefix}",
+    ]
+    if small_rna_mode:
+        cmd.extend(["--alignIntronMax", "1", "--outFilterMismatchNmax", "1"])
+
+    subprocess.run(cmd, check=True)
+    produced_bam = Path(f"{prefix}Aligned.out.bam")
+    produced_bam.replace(output)
+    return output

mirna_toolkit/batch.py

@@ -0,0 +1,178 @@
+import csv
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import pipeline
+from .pipeline import PipelineConfig, PipelineResult
+
+
+@dataclass
+class BatchSampleConfig:
+    sample_id: str
+    fastq_path: str | Path
+    reference: str | Path
+    annotation: str | Path
+    output_dir: str | Path | None = None
+    aligner: str = "bowtie"
+    normalization_method: str = "tpm"
+    threads: int = 4
+    run_qc: bool = False
+    trim: bool = False
+
+
+@dataclass
+class BatchSampleResult:
+    sample_id: str
+    bam_path: Path
+    counts_path: Path
+    normalized_path: Path
+    metadata_path: Path
+    counts: dict[str, int]
+    normalized: dict[str, float]
+
+
+@dataclass
+class BatchRunResult:
+    manifest_path: Path
+    summary_json_path: Path
+    summary_csv_path: Path
+    samples: list[BatchSampleResult]
+
+
+def load_manifest(manifest_path: str | Path) -> list[BatchSampleConfig]:
+    path = Path(manifest_path)
+    suffix = path.suffix.lower()
+
+    if suffix == ".csv":
+        return _load_csv_manifest(path)
+    if suffix == ".json":
+        return _load_json_manifest(path)
+    raise ValueError("manifest_path must end with .csv or .json")
+
+
+def run_batch_workflow(
+    manifest_path: str | Path,
+    output_dir: str | Path | None = None,
+    database_versions: dict[str, str] | None = None,
+) -> BatchRunResult:
+    manifest_file = Path(manifest_path)
+    base_output_dir = Path(output_dir) if output_dir is not None else manifest_file.parent / "batch_outputs"
+    base_output_dir.mkdir(parents=True, exist_ok=True)
+
+    sample_configs = load_manifest(manifest_file)
+    sample_results: list[BatchSampleResult] = []
+
+    for sample in sample_configs:
+        sample_output_dir = Path(sample.output_dir) if sample.output_dir is not None else base_output_dir / sample.sample_id
+        config = PipelineConfig(
+            fastq_path=sample.fastq_path,
+            reference=sample.reference,
+            annotation=sample.annotation,
+            output_dir=sample_output_dir,
+            aligner=sample.aligner,
+            normalization_method=sample.normalization_method,
+            threads=sample.threads,
+            run_qc=sample.run_qc,
+            trim=sample.trim,
+        )
+
+        result = pipeline.run_end_to_end(config, database_versions=database_versions)
+        sample_results.append(_to_sample_result(sample.sample_id, result))
+
+    summary_json_path = base_output_dir / "batch_summary.json"
+    summary_csv_path = base_output_dir / "batch_summary.csv"
+    _write_summary(sample_results, summary_json_path, summary_csv_path)
+
+    return BatchRunResult(
+        manifest_path=manifest_file,
+        summary_json_path=summary_json_path,
+        summary_csv_path=summary_csv_path,
+        samples=sample_results,
+    )
+
+
+def _load_csv_manifest(path: Path) -> list[BatchSampleConfig]:
+    with path.open("r", encoding="utf-8", newline="") as handle:
+        reader = csv.DictReader(handle)
+        rows = list(reader)
+    return [_row_to_sample(row, index=index) for index, row in enumerate(rows, start=1)]
+
+
+def _load_json_manifest(path: Path) -> list[BatchSampleConfig]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(payload, dict):
+        rows = payload.get("samples", [])
+    elif isinstance(payload, list):
+        rows = payload
+    else:
+        raise ValueError("JSON manifest must be a list or a dict with a samples key")
+    return [_row_to_sample(row, index=index) for index, row in enumerate(rows, start=1)]
+
+
+def _row_to_sample(row: dict[str, Any], index: int) -> BatchSampleConfig:
+    sample_id = str(row.get("sample_id") or row.get("sample") or row.get("id") or f"sample_{index}")
+    fastq_path = row.get("fastq_path") or row.get("fastq")
+    reference = row.get("reference")
+    annotation = row.get("annotation")
+
+    if not fastq_path or not reference or not annotation:
+        raise ValueError("Each manifest row must include fastq_path, reference, and annotation")
+
+    return BatchSampleConfig(
+        sample_id=sample_id,
+        fastq_path=fastq_path,
+        reference=reference,
+        annotation=annotation,
+        output_dir=row.get("output_dir") or None,
+        aligner=str(row.get("aligner") or "bowtie"),
+        normalization_method=str(row.get("normalization_method") or row.get("normalize") or "tpm"),
+        threads=int(row.get("threads") or 4),
+        run_qc=_parse_bool(row.get("run_qc") or row.get("qc") or False),
+        trim=_parse_bool(row.get("trim") or False),
+    )
+
+
+def _to_sample_result(sample_id: str, result: PipelineResult) -> BatchSampleResult:
+    return BatchSampleResult(
+        sample_id=sample_id,
+        bam_path=result.bam_path,
+        counts_path=result.counts_path,
+        normalized_path=result.normalized_path,
+        metadata_path=result.metadata_path,
+        counts=result.counts,
+        normalized=result.normalized,
+    )
+
+
+def _write_summary(samples: list[BatchSampleResult], json_path: Path, csv_path: Path) -> None:
+    summary_rows = [
+        {
+            "sample_id": sample.sample_id,
+            "bam_path": str(sample.bam_path),
+            "counts_path": str(sample.counts_path),
+            "normalized_path": str(sample.normalized_path),
+            "metadata_path": str(sample.metadata_path),
+        }
+        for sample in samples
+    ]
+
+    json_path.write_text(json.dumps(summary_rows, indent=2), encoding="utf-8")
+
+    with csv_path.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=["sample_id", "bam_path", "counts_path", "normalized_path", "metadata_path"])
+        writer.writeheader()
+        writer.writerows(summary_rows)
+
+
+def _parse_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return False
+    if isinstance(value, (int, float)):
+        return value != 0
+
+    normalized = str(value).strip().lower()
+    return normalized in {"1", "true", "yes", "y", "on"}

mirna_toolkit/cli.py

@@ -0,0 +1,190 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+from textwrap import dedent
+
+from . import batch as batch_module
+from .pipeline import PipelineConfig, run_end_to_end
+
+EXAMPLES = dedent(
+    """
+    Examples:
+      mirna-toolkit --fastq sample.fastq --reference mirbase.fa --annotation mirbase.gtf
+      mirna-toolkit run --fastq sample.fastq --reference mirbase.fa --annotation mirbase.gtf --trim
+      mirna-toolkit batch --manifest samples.csv --output-dir batch_runs
+      mirna-toolkit help
+      mirna-toolkit help run
+      mirna-toolkit help batch
+    """
+).strip()
+
+RUN_HELP = dedent(
+    """
+    Run a single sample through preprocessing, alignment, quantification, and normalization.
+
+    Required arguments:
+      --fastq         Input FASTQ path
+      --reference     Reference index or genome directory
+      --annotation    Annotation GTF/GFF path
+
+    Useful options:
+      --aligner       bowtie | hisat2 | star
+      --normalize     tpm | rpm
+      --run-qc        Run FastQC before alignment
+      --trim          Trim adapters with fastp before alignment
+    """
+).strip()
+
+BATCH_HELP = dedent(
+    """
+    Run multiple samples from a CSV or JSON manifest.
+
+    Manifest columns or keys:
+      sample_id, fastq_path, reference, annotation, output_dir, aligner,
+      normalization_method, threads, run_qc, trim
+
+    Minimal CSV row example:
+      sample_id,fastq_path,reference,annotation
+      s1,s1.fastq,mirbase.fa,mirbase.gtf
+    """
+).strip()
+
+HELP_TEXT = dedent(
+    f"""
+    miRNA-Toolkit command line interface
+
+    Available commands:
+      run     Process one sample
+      batch   Process multiple samples from a manifest
+      help    Show detailed examples and topic-specific usage
+
+    {EXAMPLES}
+    """
+).strip()
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if not args:
+        print(HELP_TEXT)
+        return 0
+
+    if args[0] == "help":
+        _print_help(args[1] if len(args) > 1 else None)
+        return 0
+
+    if args[0] == "batch":
+        return _run_batch(args[1:])
+
+    if args[0] == "run":
+        return _run_run(args[1:])
+
+    return _run_legacy(args)
+
+
+def _run_legacy(argv: list[str]) -> int:
+    parser = _build_run_parser(prog="mirna-toolkit", description="Run an end-to-end miRNA-Toolkit workflow")
+    args = parser.parse_args(argv)
+    return _execute_run(args)
+
+
+def _run_run(argv: list[str]) -> int:
+    parser = _build_run_parser(prog="mirna-toolkit run", description="Run an end-to-end miRNA-Toolkit workflow")
+    args = parser.parse_args(argv)
+    return _execute_run(args)
+
+
+def _run_batch(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="mirna-toolkit batch",
+        description="Run multiple samples from a manifest",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=BATCH_HELP,
+    )
+    parser.add_argument("--manifest", required=True, help="CSV or JSON manifest path")
+    parser.add_argument("--output-dir", default="batch_outputs", help="Base output directory")
+    parser.add_argument(
+        "--db-versions-json",
+        default="",
+        help="JSON file mapping database names to versions, for batch metadata",
+    )
+    args = parser.parse_args(argv)
+
+    db_versions = _load_db_versions(args.db_versions_json)
+    result = batch_module.run_batch_workflow(
+        args.manifest,
+        output_dir=args.output_dir,
+        database_versions=db_versions,
+    )
+    print(result.summary_json_path)
+    return 0
+
+
+def _execute_run(args: argparse.Namespace) -> int:
+    db_versions = _load_db_versions(getattr(args, "db_versions_json", ""))
+
+    config = PipelineConfig(
+        fastq_path=args.fastq,
+        reference=args.reference,
+        annotation=args.annotation,
+        output_dir=args.output_dir,
+        aligner=args.aligner,
+        normalization_method=args.normalize,
+        threads=args.threads,
+        run_qc=args.run_qc,
+        trim=args.trim,
+    )
+
+    result = run_end_to_end(config, database_versions=db_versions)
+    print(result.metadata_path)
+    return 0
+
+
+def _build_run_parser(*, prog: str, description: str) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=RUN_HELP + "\n\n" + EXAMPLES,
+    )
+    parser.add_argument("--fastq", required=True, help="Input FASTQ path")
+    parser.add_argument("--reference", required=True, help="Reference index/path")
+    parser.add_argument("--annotation", required=True, help="Annotation GTF/GFF path")
+    parser.add_argument("--output-dir", default="outputs", help="Output directory")
+    parser.add_argument("--aligner", default="bowtie", choices=["bowtie", "hisat2", "star"])
+    parser.add_argument("--normalize", default="tpm", choices=["tpm", "rpm"])
+    parser.add_argument("--threads", type=int, default=4)
+    parser.add_argument("--run-qc", action="store_true")
+    parser.add_argument("--trim", action="store_true")
+    parser.add_argument(
+        "--db-versions-json",
+        default="",
+        help="JSON file mapping database names to versions, for run metadata",
+    )
+    return parser
+
+
+def _load_db_versions(path_value: str) -> dict[str, str] | None:
+    if not path_value:
+        return None
+    return json.loads(Path(path_value).read_text(encoding="utf-8"))
+
+
+def _print_help(topic: str | None) -> None:
+    if topic == "run":
+        print(RUN_HELP)
+        print()
+        print(EXAMPLES)
+        return
+    if topic == "batch":
+        print(BATCH_HELP)
+        print()
+        print(EXAMPLES)
+        return
+    print(HELP_TEXT)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mirna_toolkit/disease/__init__.py

@@ -0,0 +1,5 @@
+from . import hmdd, mircancer
+from .hmdd import get_associations as hmdd_associations
+from .mircancer import get_associations as mircancer_associations
+
+__all__ = ["hmdd", "hmdd_associations", "mircancer", "mircancer_associations"]

mirna_toolkit/disease/hmdd.py

@@ -0,0 +1,51 @@
+import csv
+import json
+from pathlib import Path
+from typing import Any
+
+from ..utils.http import safe_get_json
+
+HMDD_ENDPOINT = "https://www.cuilab.cn/hmdd/api/v1/associations"
+
+
+def get_associations(mirna_id: str, timeout: int = 60, strict: bool = False) -> list[dict[str, Any]]:
+    payload = safe_get_json(HMDD_ENDPOINT, params={"mirna": mirna_id}, timeout=timeout, strict=strict)
+    if payload is None:
+        return []
+    if isinstance(payload, dict) and "data" in payload:
+        return list(payload["data"])
+    if isinstance(payload, list):
+        return payload
+    return []
+
+
+def build_network_edges(associations: list[dict[str, Any]]) -> list[tuple[str, str]]:
+    edges: list[tuple[str, str]] = []
+    for row in associations:
+        mirna = str(row.get("mirna") or row.get("miRNA") or "")
+        disease = str(row.get("disease") or row.get("disease_name") or "")
+        if mirna and disease:
+            edges.append((mirna, disease))
+    return edges
+
+
+def export_associations(associations: list[dict[str, Any]], output_path: str | Path) -> Path:
+    output = Path(output_path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    if output.suffix.lower() == ".json":
+        output.write_text(json.dumps(associations, indent=2), encoding="utf-8")
+        return output
+
+    if output.suffix.lower() == ".csv":
+        if associations:
+            fields = sorted({k for row in associations for k in row.keys()})
+            with output.open("w", newline="", encoding="utf-8") as handle:
+                writer = csv.DictWriter(handle, fieldnames=fields)
+                writer.writeheader()
+                writer.writerows(associations)
+        else:
+            output.write_text("", encoding="utf-8")
+        return output
+
+    raise ValueError("output_path must end with .json or .csv")

mirna_toolkit/disease/mircancer.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+from ..utils.http import safe_get_json
+
+MIRCANCER_ENDPOINT = "https://mircancer.ecu.edu/api/v1/associations"
+
+
+def get_associations(mirna_id: str, timeout: int = 60, strict: bool = False) -> list[dict[str, Any]]:
+    payload = safe_get_json(
+        MIRCANCER_ENDPOINT,
+        params={"mirna": mirna_id},
+        timeout=timeout,
+        strict=strict,
+    )
+    if payload is None:
+        return []
+    if isinstance(payload, dict) and "data" in payload:
+        return list(payload["data"])
+    if isinstance(payload, list):
+        return payload
+    return []

mirna_toolkit/io/__init__.py

@@ -0,0 +1,21 @@
+from . import bam, downloaders, fastq, gtf
+from .bam import bam_to_fasta, fastq_to_bam
+from .downloaders import download_ensembl_release, download_geo_series, download_mirbase_release
+from .fastq import parse_fastq, run_fastqc, trim_adapters
+from .gtf import parse_gtf
+
+__all__ = [
+    "bam",
+    "bam_to_fasta",
+    "downloaders",
+    "download_ensembl_release",
+    "download_geo_series",
+    "download_mirbase_release",
+    "fastq",
+    "fastq_to_bam",
+    "gtf",
+    "parse_fastq",
+    "parse_gtf",
+    "run_fastqc",
+    "trim_adapters",
+]

mirna_toolkit/io/bam.py

@@ -0,0 +1,32 @@
+import subprocess
+from pathlib import Path
+
+
+def fastq_to_bam(
+    fastq_path: str | Path,
+    reference: str | Path,
+    output_bam: str | Path,
+    aligner: str = "bowtie",
+) -> Path:
+    """Convert FASTQ to BAM through selected aligner + samtools."""
+    out = Path(output_bam)
+    sam_path = out.with_suffix(".sam")
+
+    if aligner == "bowtie":
+        cmd = ["bowtie", "-S", str(reference), str(fastq_path), str(sam_path)]
+    elif aligner == "hisat2":
+        cmd = ["hisat2", "-x", str(reference), "-U", str(fastq_path), "-S", str(sam_path)]
+    elif aligner == "star":
+        cmd = ["STAR", "--genomeDir", str(reference), "--readFilesIn", str(fastq_path), "--outFileNamePrefix", str(sam_path.with_suffix(""))]
+    else:
+        raise ValueError("aligner must be one of: bowtie, hisat2, star")
+
+    subprocess.run(cmd, check=True)
+    subprocess.run(["samtools", "view", "-bS", str(sam_path), "-o", str(out)], check=True)
+    return out
+
+
+def bam_to_fasta(bam_path: str | Path, output_fasta: str | Path) -> Path:
+    out = Path(output_fasta)
+    subprocess.run(["samtools", "fasta", str(bam_path), "-o", str(out)], check=True)
+    return out

mirna_toolkit/io/downloaders.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+
+from ..utils.http import download_file
+
+MIRBASE_BASE = "https://www.mirbase.org/ftp"
+GEO_BASE = "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi"
+ENSEMBL_BASE = "https://ftp.ensembl.org/pub"
+
+
+def _download(url: str, output_path: str | Path) -> Path:
+    return download_file(url, output_path)
+
+
+def download_mirbase_release(filename: str, output_dir: str | Path = "data") -> Path:
+    output = Path(output_dir) / filename
+    return _download(f"{MIRBASE_BASE}/{filename}", output)
+
+
+def download_geo_series(gse_id: str, output_path: str | Path) -> Path:
+    url = f"{GEO_BASE}?acc={gse_id}&targ=self&form=text&view=quick"
+    return _download(url, output_path)
+
+
+def download_ensembl_release(release_path: str, output_dir: str | Path = "data") -> Path:
+    filename = Path(release_path).name
+    output = Path(output_dir) / filename
+    return _download(f"{ENSEMBL_BASE}/{release_path}", output)

mirna_toolkit/io/fastq.py

@@ -0,0 +1,41 @@
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class FastqRecord:
+    header: str
+    sequence: str
+    plus: str
+    quality: str
+
+
+def parse_fastq(path: str | Path):
+    """Yield FASTQ records from a file."""
+    with Path(path).open("r", encoding="utf-8") as handle:
+        while True:
+            header = handle.readline().rstrip("\n")
+            if not header:
+                break
+            sequence = handle.readline().rstrip("\n")
+            plus = handle.readline().rstrip("\n")
+            quality = handle.readline().rstrip("\n")
+            if not quality:
+                raise ValueError("Malformed FASTQ: incomplete record")
+            yield FastqRecord(header=header, sequence=sequence, plus=plus, quality=quality)
+
+
+def run_fastqc(fastq_path: str | Path, output_dir: str | Path) -> Path:
+    output = Path(output_dir)
+    output.mkdir(parents=True, exist_ok=True)
+    cmd = ["fastqc", str(fastq_path), "-o", str(output)]
+    subprocess.run(cmd, check=True)
+    return output
+
+
+def trim_adapters(fastq_path: str | Path, output_fastq: str | Path, threads: int = 4) -> Path:
+    out = Path(output_fastq)
+    cmd = ["fastp", "-i", str(fastq_path), "-o", str(out), "-w", str(threads)]
+    subprocess.run(cmd, check=True)
+    return out