Why BioCheck?

In bioinformatics, over 50% of pipeline failures on HPC clusters are caused by formatting errors:

• Delimiter corruption: A VCF, BED, or GTF file has spaces instead of tabs on line 14,200.
• Chromosome style mismatch: Reference index uses chr1, but your file uses 1, resulting in zero matches.
• FASTQ desynchronization: Sequence length does not match quality string length (len(seq) != len(qual)).
• Windows line endings: Invisible carriage returns (\r\n) breaking Linux tools.
• Inverted or negative coordinates: 0-based vs 1-based bounds errors (start > end or start < 0).

Existing validators are fragmented across multiple programming languages, require complex compilation, and cannot fix anything.

BioCheck is a single standalone binary (~1.8 MB) with zero dependencies. It inspects files at 1.5–3.0 GB/s, displays clear diagnostics with line pointers, and automatically repairs formatting errors with biocheck fix.

Quick Start

BioCheck is distributed as a single standalone executable. It requires no Python setup, no compiler, and zero dependencies.

Option 1: Standalone Binary (Recommended)

Download the pre-compiled binary for your system:

# Linux (x86_64)
curl -L -o biocheck https://gitee.com/l1zhe/bio-check/releases/download/v0.1.0/biocheck-linux-x86_64
chmod +x biocheck
sudo mv biocheck /usr/local/bin/

# Verify installation
biocheck --version

Option 2: Python (pip)

# Installs the standalone 'biocheck' binary into your PATH
pip install biocheck-cli

# Verify installation
biocheck --version

git clone https://gitee.com/l1zhe/bio-check.git
cd bio-check
cargo build --release
# Executable is located at ./target/release/biocheck

CLI Usage

1. Check Files or Directories

BioCheck automatically detects file formats and transparently handles .gz / .bgz compressed files:

# Check a single file
biocheck check sample.vcf

# Check an entire directory
biocheck check data/

# Fast pre-flight check on massive files (default) or full byte scan
biocheck check --full cohort.vcf.gz

Diagnostic Output:

error[VCF001]: Inconsistent delimiter: spaces detected instead of tab ('\t')
  --> data/cohort.vcf:142:5
      |
  142 | chr1    10050    rs123    A    G    .    PASS    DP=20
      |     ^^^^
      |
  = help: Run `biocheck fix --delimiters <file>` to replace spaces with tabs

warning[VCF005]: Inconsistent chromosome naming convention
  --> data/cohort.vcf:305:1
      |
  305 | 1	15000	rs456	C	T	.	PASS	DP=18
      | ^^^^
      |
  = help: Run `biocheck fix --chr-style ucsc <file>` to standardize contig names

Checked 2 files: 1 error, 1 warning in 0.02s

2. Auto-Fix Formatting Errors (biocheck fix)

Unlike legacy validators that only complain and crash, BioCheck automatically repairs common formatting issues:

# Convert spaces to tabs and strip CRLF line endings
biocheck fix corrupted.vcf -o clean.vcf

# Standardize chromosome contigs (force UCSC 'chr1' or Ensembl '1')
biocheck fix sample.bed --chr-style ucsc -o clean.bed

# Coordinate-sort the file
biocheck fix unsorted.vcf --sort -o sorted.vcf

# Drop incomplete trailing reads from truncated FASTQ downloads
biocheck fix truncated.fastq -o fixed.fastq

# Clean and format FASTA sequence lines
biocheck fix genome.fasta --clean-fasta -o cleaned.fasta

# Modify in-place atomically
biocheck fix --in-place data/sample.vcf

3. Pipeline & CI/CD Integration

# Quiet mode: returns exit code (0 = clean, 1 = errors)
biocheck check -q input.fastq.gz

# Machine-readable JSON output
biocheck check --output-format json data/ > report.json

# Compact single-line output (IDE & editor friendly)
biocheck check --output-format compact data/

Performance Comparison

Benchmarked scanning a 3.2 GB Human Reference FASTA (GRCh38.fa):

Supported Formats & Rules

Run biocheck rules to inspect the interactive rule index:

Pre-Commit Hook Integration

Add BioCheck to your .pre-commit-config.yaml to prevent invalid files from being committed:

repos:
  - repo: https://gitee.com/l1zhe/bio-check
    rev: v0.1.0
    hooks:
      - id: biocheck

Nextflow Pre-Flight Recipe

Add BioCheck as a fast pre-flight validation step in Nextflow pipelines:

process PREFLIGHT_CHECK {
    tag "$meta.id"
    
    input:
    tuple val(meta), path(reads)

    script:
    """
    biocheck check -q ${reads}
    """
}

License

Licensed under the MIT License.