peek-bio 0.1.0__tar.gz

peek_bio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Patrick Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

peek_bio-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.1
+Name: peek-bio
+Version: 0.1.0
+Summary: Instant file previews for genomics data
+Author: Patrick Wilson
+License: MIT
+Project-URL: Homepage, https://github.com/pwilson97/peek-bio
+Project-URL: Repository, https://github.com/pwilson97/peek-bio
+Project-URL: Issues, https://github.com/pwilson97/peek-bio/issues
+Keywords: bioinformatics,genomics,bam,vcf,fastq,fasta,bed,gtf,csv,preview,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.0; extra == "excel"
+Provides-Extra: h5ad
+Requires-Dist: anndata>=0.8; extra == "h5ad"
+Provides-Extra: bigwig
+Requires-Dist: pyBigWig>=0.3; extra == "bigwig"
+Provides-Extra: bam
+Requires-Dist: pysam>=0.20; extra == "bam"
+Provides-Extra: all
+Requires-Dist: openpyxl>=3.0; extra == "all"
+Requires-Dist: anndata>=0.8; extra == "all"
+Requires-Dist: pyBigWig>=0.3; extra == "all"
+Requires-Dist: pysam>=0.20; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+
+# peek-bio
+
+Instant file previews for genomics data. One command, any format.
+
+```
+pip install peek-bio
+```
+
+## What it does
+
+Point `peek` at a file and get a structured summary: row counts, column types,
+quality scores, variant stats, mapping rates, QC warnings. No scripts, no
+notebooks, no googling command flags.
+
+```
+$ peek deseq2_results.csv
+
+ deseq2_results.csv — >10,553 x 7 (CSV, comma-separated)
+ ────────────────────────────────────────────────────────────────────
+ Columns:
+                   str    0610005C13Rik, 0610009B22Rik, ...  (1,000 unique)
+   baseMean        float  3.92 … 1983.92  (median: 25.32, mean: 59.32)  ⡇⡀⡀⡀⡀⡀⡀⡀⡀⡀
+   log2FoldChange  float  -3.29 … 3.60  (median: -0.02, mean: -0.04)    ⡀⡀⡀⡀⡀⡇⡄⡀⡀⡀⡀⡀
+   lfcSE           float  0.11 … 1.23  (median: 0.35, mean: 0.40)       ⡄⡇⡆⡄⡄⡄⡀⡀⡀⡀⡀⡀
+   stat            float  -5.94 … 8.10  (median: -0.06, mean: -0.11)    ⡀⡀⡀⡀⡇⡆⡄⡀⡀⡀⡀
+   pvalue          float  5.46e-16 … 1.00  (median: 0.37, mean: 0.45)   ⡇⡄⡄⡄⡄⡄⡄⡀⡄⡄⡄⡄
+   padj            float  3.42e-13 … 1.00  (median: 0.95, mean: 0.81)   ⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡇
+
+ Missing:  pvalue (1)
+```
+
+```
+$ peek NA12878.bam
+
+ NA12878.bam — 61,614 reads (BAM, indexed)
+ ────────────────────────────────────────────────────────────────────
+ Reference:  3366 sequences, 3.2 Gb  [GRCh38 (with alts)]
+ Reads:  60,749 mapped (98.6%), 865 unmapped
+ Flags:  0.1% duplicates, 1.5% supplementary
+ Paired:  yes (2×250 bp)
+ Insert size:  mean 449  median 428  range 100–999  ⡀⡀⡀⡀⡆⡇⡄⡄⡄⡀⡀⡀
+ Read groups:  3  (NA12878, NA12878, NA12878)
+ Sort order:  coordinate
+ Programs:  bwamem, MarkDuplicates, GATK ApplyBQSR
+ MAPQ:  mean 55.3  median 60  ⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡇
+```
+
+```
+$ peek ERR188273_chrX_1.fq.gz
+
+ ERR188273_chrX_1.fq.gz — 30,531 reads, 2.3 Mb (FASTQ, Phred+33)
+ ────────────────────────────────────────────────────────────────────
+ Read length:  all 75 bp
+ Quality:  mean Q36.7  median Q38  range Q2–Q41  ⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡆⡇
+ GC content:  48.9%
+```
+
+```
+$ peek clinvar.vcf.gz
+
+ clinvar.vcf.gz — 4,403,650 variants (VCF)
+ ────────────────────────────────────────────────────────────────────
+ Variants:  4,103,565 snps, 93,659 insertions, 194,377 deletions, 12,049 complexes
+ Ts/Tv:  1.69
+ FILTER:  4,403,650 PASS
+ Chroms:  32 total — top: 1 (398,195), 2 (384,641), 17 (265,676)
+```
+
+## Supported formats
+
+**Core** (no extra dependencies):
+
+| Format | Extensions |
+|--------|-----------|
+| CSV/TSV | `.csv`, `.tsv`, `.txt` |
+| BED | `.bed`, `.narrowPeak`, `.broadPeak`, `.bedGraph` |
+| FASTA | `.fa`, `.fasta` |
+| FASTQ | `.fq`, `.fastq` |
+| VCF | `.vcf`, `.vcf.gz` |
+| GTF/GFF | `.gtf`, `.gff`, `.gff3` |
+
+**Optional** (install what you need):
+
+| Format | Extensions | Install |
+|--------|-----------|---------|
+| SAM/BAM/CRAM | `.sam`, `.bam`, `.cram` | `pip install peek-bio[bam]` |
+| Excel | `.xlsx`, `.xls` | `pip install peek-bio[excel]` |
+| BigWig | `.bw`, `.bigwig` | `pip install peek-bio[bigwig]` |
+| H5AD | `.h5ad` | `pip install peek-bio[h5ad]` |
+
+Or install everything: `pip install peek-bio[all]`
+
+## QC warnings
+
+peek flags common issues automatically:
+
+- Unusual GC content (outside 25-65%)
+- High N content in assemblies (>20%)
+- Low mean base quality in FASTQ (<Q20)
+- Adapter contamination in FASTQ (>5%)
+- Low mapping rate in BAM/SAM (<80%)
+- Low MAPQ scores (<20 mean)
+- High duplicate rate (>30%)
+- Ts/Tv ratio out of range in VCF
+- Low genotype rate in multi-sample VCF (<90%)
+- No gene features or missing gene_id in GTF
+- Single-chromosome GTF (possible subset)
+- Columns with >50% missing data
+- Mixed-type columns (numbers and strings mixed together)
+
+## Usage
+
+```
+peek FILE [FILE ...]          # preview one or more files
+peek --head 20 FILE           # show 20 preview rows instead of 5
+peek --no-color FILE          # plain text output (no ANSI colors)
+peek --formats                # list all supported formats + install status
+peek --version                # print version
+```
+
+Compressed files (`.gz`) are handled transparently.
+
+## License
+
+MIT

peek_bio-0.1.0/README.md

@@ -0,0 +1,125 @@
+# peek-bio
+
+Instant file previews for genomics data. One command, any format.
+
+```
+pip install peek-bio
+```
+
+## What it does
+
+Point `peek` at a file and get a structured summary: row counts, column types,
+quality scores, variant stats, mapping rates, QC warnings. No scripts, no
+notebooks, no googling command flags.
+
+```
+$ peek deseq2_results.csv
+
+ deseq2_results.csv — >10,553 x 7 (CSV, comma-separated)
+ ────────────────────────────────────────────────────────────────────
+ Columns:
+                   str    0610005C13Rik, 0610009B22Rik, ...  (1,000 unique)
+   baseMean        float  3.92 … 1983.92  (median: 25.32, mean: 59.32)  ⡇⡀⡀⡀⡀⡀⡀⡀⡀⡀
+   log2FoldChange  float  -3.29 … 3.60  (median: -0.02, mean: -0.04)    ⡀⡀⡀⡀⡀⡇⡄⡀⡀⡀⡀⡀
+   lfcSE           float  0.11 … 1.23  (median: 0.35, mean: 0.40)       ⡄⡇⡆⡄⡄⡄⡀⡀⡀⡀⡀⡀
+   stat            float  -5.94 … 8.10  (median: -0.06, mean: -0.11)    ⡀⡀⡀⡀⡇⡆⡄⡀⡀⡀⡀
+   pvalue          float  5.46e-16 … 1.00  (median: 0.37, mean: 0.45)   ⡇⡄⡄⡄⡄⡄⡄⡀⡄⡄⡄⡄
+   padj            float  3.42e-13 … 1.00  (median: 0.95, mean: 0.81)   ⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡇
+
+ Missing:  pvalue (1)
+```
+
+```
+$ peek NA12878.bam
+
+ NA12878.bam — 61,614 reads (BAM, indexed)
+ ────────────────────────────────────────────────────────────────────
+ Reference:  3366 sequences, 3.2 Gb  [GRCh38 (with alts)]
+ Reads:  60,749 mapped (98.6%), 865 unmapped
+ Flags:  0.1% duplicates, 1.5% supplementary
+ Paired:  yes (2×250 bp)
+ Insert size:  mean 449  median 428  range 100–999  ⡀⡀⡀⡀⡆⡇⡄⡄⡄⡀⡀⡀
+ Read groups:  3  (NA12878, NA12878, NA12878)
+ Sort order:  coordinate
+ Programs:  bwamem, MarkDuplicates, GATK ApplyBQSR
+ MAPQ:  mean 55.3  median 60  ⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡇
+```
+
+```
+$ peek ERR188273_chrX_1.fq.gz
+
+ ERR188273_chrX_1.fq.gz — 30,531 reads, 2.3 Mb (FASTQ, Phred+33)
+ ────────────────────────────────────────────────────────────────────
+ Read length:  all 75 bp
+ Quality:  mean Q36.7  median Q38  range Q2–Q41  ⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡀⡆⡇
+ GC content:  48.9%
+```
+
+```
+$ peek clinvar.vcf.gz
+
+ clinvar.vcf.gz — 4,403,650 variants (VCF)
+ ────────────────────────────────────────────────────────────────────
+ Variants:  4,103,565 snps, 93,659 insertions, 194,377 deletions, 12,049 complexes
+ Ts/Tv:  1.69
+ FILTER:  4,403,650 PASS
+ Chroms:  32 total — top: 1 (398,195), 2 (384,641), 17 (265,676)
+```
+
+## Supported formats
+
+**Core** (no extra dependencies):
+
+| Format | Extensions |
+|--------|-----------|
+| CSV/TSV | `.csv`, `.tsv`, `.txt` |
+| BED | `.bed`, `.narrowPeak`, `.broadPeak`, `.bedGraph` |
+| FASTA | `.fa`, `.fasta` |
+| FASTQ | `.fq`, `.fastq` |
+| VCF | `.vcf`, `.vcf.gz` |
+| GTF/GFF | `.gtf`, `.gff`, `.gff3` |
+
+**Optional** (install what you need):
+
+| Format | Extensions | Install |
+|--------|-----------|---------|
+| SAM/BAM/CRAM | `.sam`, `.bam`, `.cram` | `pip install peek-bio[bam]` |
+| Excel | `.xlsx`, `.xls` | `pip install peek-bio[excel]` |
+| BigWig | `.bw`, `.bigwig` | `pip install peek-bio[bigwig]` |
+| H5AD | `.h5ad` | `pip install peek-bio[h5ad]` |
+
+Or install everything: `pip install peek-bio[all]`
+
+## QC warnings
+
+peek flags common issues automatically:
+
+- Unusual GC content (outside 25-65%)
+- High N content in assemblies (>20%)
+- Low mean base quality in FASTQ (<Q20)
+- Adapter contamination in FASTQ (>5%)
+- Low mapping rate in BAM/SAM (<80%)
+- Low MAPQ scores (<20 mean)
+- High duplicate rate (>30%)
+- Ts/Tv ratio out of range in VCF
+- Low genotype rate in multi-sample VCF (<90%)
+- No gene features or missing gene_id in GTF
+- Single-chromosome GTF (possible subset)
+- Columns with >50% missing data
+- Mixed-type columns (numbers and strings mixed together)
+
+## Usage
+
+```
+peek FILE [FILE ...]          # preview one or more files
+peek --head 20 FILE           # show 20 preview rows instead of 5
+peek --no-color FILE          # plain text output (no ANSI colors)
+peek --formats                # list all supported formats + install status
+peek --version                # print version
+```
+
+Compressed files (`.gz`) are handled transparently.
+
+## License
+
+MIT

peek_bio-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "peek-bio"
+version = "0.1.0"
+description = "Instant file previews for genomics data"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    { name = "Patrick Wilson" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+]
+keywords = [
+    "bioinformatics",
+    "genomics",
+    "bam",
+    "vcf",
+    "fastq",
+    "fasta",
+    "bed",
+    "gtf",
+    "csv",
+    "preview",
+    "cli",
+]
+
+[project.urls]
+Homepage = "https://github.com/pwilson97/peek-bio"
+Repository = "https://github.com/pwilson97/peek-bio"
+Issues = "https://github.com/pwilson97/peek-bio/issues"
+
+[project.scripts]
+peek = "peek_bio.cli:main"
+
+[project.optional-dependencies]
+excel = ["openpyxl>=3.0"]
+h5ad = ["anndata>=0.8"]
+bigwig = ["pyBigWig>=0.3"]
+bam = ["pysam>=0.20"]
+all = [
+    "openpyxl>=3.0",
+    "anndata>=0.8",
+    "pyBigWig>=0.3",
+    "pysam>=0.20",
+]
+dev = [
+    "pytest>=6.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

peek_bio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

peek_bio-0.1.0/src/peek_bio/__init__.py

@@ -0,0 +1,3 @@
+"""peek-bio: Universal file preview for genomics data."""
+
+__version__ = "0.1.0"

peek_bio-0.1.0/src/peek_bio/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as `python -m peek_bio`."""
+from peek_bio.cli import main
+
+main()

peek_bio-0.1.0/src/peek_bio/cli.py

@@ -0,0 +1,186 @@
+"""CLI entry point for peek."""
+
+import argparse
+import os
+import sys
+
+from peek_bio import __version__
+from peek_bio.detect import FormatType, detect_format, format_label
+from peek_bio.display import Style, error, set_color
+from peek_bio.formats import get_handler
+
+
+def _supported_formats():
+    """List all supported formats and their install status."""
+    from peek_bio.display import separator
+
+    print(f" {Style.BOLD}peek-bio{Style.RESET} v{__version__} — supported formats:\n")
+
+    # Core (always available)
+    core = [
+        ("CSV/TSV", ".csv, .tsv, .txt", "built-in"),
+        ("BED", ".bed, .narrowPeak, .broadPeak, .bedGraph", "built-in"),
+        ("FASTA", ".fa, .fasta", "built-in"),
+        ("GTF/GFF", ".gtf, .gff, .gff3", "built-in"),
+        ("VCF", ".vcf, .vcf.gz", "built-in"),
+        ("FASTQ", ".fq, .fastq", "built-in"),
+    ]
+
+    # Optional
+    optional = []
+
+    try:
+        import openpyxl  # noqa: F401
+        optional.append(("Excel", ".xlsx, .xls", f"{Style.GREEN}installed{Style.RESET}"))
+    except ImportError:
+        optional.append(("Excel", ".xlsx, .xls", f"{Style.YELLOW}pip install peek-bio[excel]{Style.RESET}"))
+
+    try:
+        import anndata  # noqa: F401
+        optional.append(("H5AD", ".h5ad", f"{Style.GREEN}installed{Style.RESET}"))
+    except ImportError:
+        optional.append(("H5AD", ".h5ad", f"{Style.YELLOW}pip install peek-bio[h5ad]{Style.RESET}"))
+
+    try:
+        import pyBigWig  # noqa: F401
+        optional.append(("BigWig", ".bw, .bigwig", f"{Style.GREEN}installed{Style.RESET}"))
+    except ImportError:
+        optional.append(("BigWig", ".bw, .bigwig", f"{Style.YELLOW}pip install peek-bio[bigwig]{Style.RESET}"))
+
+    try:
+        import pysam  # noqa: F401
+        optional.append(("SAM/BAM", ".sam, .bam, .cram", f"{Style.GREEN}installed{Style.RESET}"))
+    except ImportError:
+        optional.append(("SAM/BAM", ".sam, .bam, .cram", f"{Style.YELLOW}pip install peek-bio[bam]{Style.RESET}"))
+
+    # Print
+    max_name = max(len(f[0]) for f in core + optional)
+    max_ext = max(len(f[1]) for f in core + optional)
+
+    for name, ext, status in core:
+        print(f"   {Style.BOLD}{name:<{max_name}}{Style.RESET}  {Style.DIM}{ext:<{max_ext}}{Style.RESET}  {status}")
+    print()
+    for name, ext, status in optional:
+        print(f"   {Style.BOLD}{name:<{max_name}}{Style.RESET}  {Style.DIM}{ext:<{max_ext}}{Style.RESET}  {status}")
+
+    # Coming soon (placeholder for future formats)
+    # print(f"\n {Style.DIM}Coming soon: ...{Style.RESET}")
+
+
+def _peek_one(path, opts):
+    """Preview a single file."""
+    if not os.path.exists(path):
+        error(f"file not found: {path}")
+        return False
+
+    if os.path.isdir(path):
+        error(f"is a directory: {path}")
+        return False
+
+    # Skip index / auxiliary files with a friendly message
+    lower = os.path.basename(path).lower()
+    _index_labels = {
+        ".bai": "BAM index", ".csi": "CSI index", ".tbi": "tabix index",
+        ".fai": "FASTA index", ".idx": "index", ".gzi": "bgzip index",
+    }
+    for iext, ilabel in _index_labels.items():
+        if lower.endswith(iext):
+            # Silently skip — these are companion files, not data
+            return True
+
+    fmt, is_compressed = detect_format(path)
+
+    if fmt == FormatType.UNKNOWN:
+        error(f"unrecognized format: {path}")
+        return False
+
+    handler = get_handler(fmt)
+    if handler is None:
+        # Format recognized but handler not available (missing optional dep)
+        label = format_label(fmt)
+        error(f"{label} format detected but handler not available")
+        dep_hints = {
+            FormatType.EXCEL: "pip install peek-bio[excel]",
+            FormatType.H5AD: "pip install peek-bio[h5ad]",
+            FormatType.BIGWIG: "pip install peek-bio[bigwig]",
+            FormatType.SAM: "pip install peek-bio[bam]",
+            FormatType.BAM: "pip install peek-bio[bam]",
+            FormatType.CRAM: "pip install peek-bio[bam]",
+        }
+        hint = dep_hints.get(fmt)
+        if hint:
+            print(f"   Run: {hint}", file=sys.stderr)
+        return False
+
+    try:
+        handler(path, is_compressed, opts)
+    except Exception as exc:
+        error(f"failed to read {path}: {exc}")
+        return False
+
+    return True
+
+
+def main(argv=None):
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="peek",
+        description="Universal file preview for genomics data",
+    )
+    parser.add_argument(
+        "files",
+        nargs="*",
+        help="file(s) to preview",
+    )
+    parser.add_argument(
+        "--head", "-n",
+        type=int,
+        default=5,
+        help="number of preview rows to show (default: 5)",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="disable colored output",
+    )
+    parser.add_argument(
+        "--formats",
+        action="store_true",
+        help="list supported file formats",
+    )
+    parser.add_argument(
+        "--version", "-v",
+        action="version",
+        version=f"peek-bio {__version__}",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.no_color:
+        set_color(False)
+
+    if args.formats:
+        _supported_formats()
+        return
+
+    if not args.files:
+        parser.print_help()
+        sys.exit(1)
+
+    opts = {
+        "head": args.head,
+    }
+    success = True
+
+    for i, path in enumerate(args.files):
+        if i > 0:
+            print()  # Blank line between files
+        if not _peek_one(path, opts):
+            success = False
+
+    if not success:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()