README.md

🧬 Blixa Research Language (Blixa) - Core Syntax v1.1.3

Blixa is a domain‑specific programming language designed exclusively for biological researchers. It provides a seamless, unified syntax to perform complex bioinformatics, single‑cell analytics, structural biology, and statistical computations without requiring deep knowledge of the underlying scientific libraries or algorithms.

🏗️ Architecture & Philosophy

The language operates on a layered architecture: Researcher → Biological Syntax → Language Runtime → Python Bridge → Scientific Libraries → Computation.
Every command is highly contextualized to biological objects, returning usable results and preserving immutability. Analytical details, data transformations, and algorithm parameters are managed internally by the Runtime.

🧠 Smart Caching System

Blixa implements an intelligent, memory‑aware caching engine to optimize performance and protect system resources. Each biological object and experiment maintains a local LRU (Least Recently Used) cache of up to 50 complex analytical results (e.g., differential expression, alignments, expression vectors).

• Automatic Memory Protection: If the system's available RAM drops below 20%, the Runtime automatically evicts the oldest 25% of cached items without user intervention.
• Zero Configuration: The system works silently in the background, drastically speeding up repetitive queries (like .find_cells() or .compare_all()).
• Manual Override: You can force clear the memory at any time using the .clear_cache() universal method or the global clear_cache() function.

Global Caching

Blixa also provides a global LRU cache (size 100) that stores results of expensive operations across all objects (e.g., UMAP, PCA, markers). This prevents recomputation on identical datasets and operations. You can clear it manually with clear_global_cache().

New in v1.1.2 (Reliability & Robustness):

• protein.structure() now includes a local fallback mechanism. When the ESMFold API is unavailable, it searches a local PDB database (via Biopython) for sequences with >90% identity. If a match is found, the structure is returned immediately, dramatically improving success rates even without internet access. If both fallback and API fail, a clear BiologicalLogicError explains the situation.
• load() now performs an integrity check on .h5ad files using h5py before calling scanpy.read_h5ad(). Corrupted files raise a user‑friendly MissingDataError instead of cryptic HDF5 tracebacks. Similar pre‑checks have been added for other formats where feasible.
• All plotting functions in the visualization module now provide explicit, actionable error messages when optional dependencies (like seaborn or scanpy) are missing, guiding users to install the required libraries or choose a different plot type.

Previous improvements (v1.1.1):

• The GlobalCache now includes memory‑aware eviction, removing 25% of the oldest entries when free RAM falls below 20% (requires psutil; falls back gracefully if not installed).
• Cells.find_cells() caches the observation metadata and column mappings, eliminating redundant copies of the entire obs DataFrame. This results in 30‑40% faster queries and 20‑30% lower memory usage on repeated calls.
• The load() function now accepts an optional chunksize parameter to process large CSV/TSV files in manageable chunks, reducing peak memory consumption.

Project Layout

• core/: Contains the primary runtime objects (DNA, RNA, Protein, Gene, Cell, Cells, Experiment, Workflow, Result) and shared abstractions.
• modules/: Specialized scientific libraries loaded dynamically (genomics, singlecell, proteomics, crispr, epigenetics, etc.).
• transpiler/: Houses the custom DSL parser (BioParser) and the AST executor (PythonBridge).
• exceptions/: Strict biological and sequence validation handlers (BioError, SequenceValidationError).

🧬 Core Objects

You can instantiate biological objects directly:

• dna("ATGCGT") – DNA sequences.
• rna("AUGCGU") – RNA sequences.
• protein("MEEPQSD") – Amino acid sequences.
• gene("PAX6") – Biological genes.
• cell("stem") – Single‑cell instances.
• cells("experiment.h5ad") – Cell populations / scRNA‑seq datasets.
• experiment("name") – Multi‑condition experiment design.
• workflow("name") – Automated analytical pipelines.

Shared Universal Methods

All biological objects share a universal interface:

• .value(), .len(), .at(pos), .slice(start, end), .head(n), .tail(n)
• .find(seq), .find_all(seq), .rep(seq)
• .valid(), .validate(), .info(), .summary(), .graph(type), .save(file), .clear_cache()

General & Statistical Functions

• len(), mean(), median(), std(), distribution()
• compare(), correlation(), align(), t_test(), anova(), fdr_correct()
• load(file, chunksize=None), save(data, file), export(data, file), integrate(), parallel(), clear_cache()

Note on load():
The new chunksize parameter allows you to control how many rows are read at a time from CSV/TSV files. While the final DataFrame is still loaded into memory, processing in chunks reduces peak memory usage and enables handling of files larger than available RAM. Additionally, load() now checks the integrity of .h5ad files before reading, providing clear error messages if the file is corrupted.

🚀 Getting Started

Here are four complete examples to get you started with Blixa.

Example 1: DNA Analysis

my_dna = dna("ATGCGTACGTAGCTAGCT")
print(my_dna.gc())                 # GC content
print(my_dna.rev_comp())           # Reverse complement
protein_seq = my_dna.translate()   # Translate to protein
print(protein_seq)

Example 2: Single‑Cell Pipeline (with PBMC3k dataset)

use singlecell
use visualization

# Load dataset (you can also load your own .h5ad file)
sample = cells("pbmc3k.h5ad")

# Quality control and filtering
sample = sample.filter(min_genes=200, max_mito=0.05)

# Normalization and feature selection
sample = sample.normalize()
sample = sample.variable_genes()

# Dimensionality reduction and clustering
sample = sample.reduce("pca")
sample = sample.cluster("leiden", resolution=0.5)
sample = sample.umap()

# Visualize
sample.graph("umap", color="leiden")

# Find marker genes for cluster 0 vs cluster 1
markers = sample.markers(group1="0", group2="1")
markers.top(10).graph("volcano")

Example 3: CRISPR Guide Design

use crispr

my_gene = gene("BRCA1")
# Assume the gene has DNA sequence loaded
guides = my_gene.crispr_design(target_length=20)
best_guides = guides.efficiency().off_targets().top(5)
print(best_guides)

Example 4: Experiment and Differential Expression

use statistics

exp = experiment("my_experiment")
exp.add(control_sample, condition="control")
exp.add(treated_sample, condition="treated")

# Compare gene expression for a specific gene
result = exp.t_test("control", "treated", gene="TP53")
result = result.fdr_correct()
print(result.summary())

🔧 Troubleshooting & Common Errors

When working with Blixa, you may occasionally encounter errors. Here is a guide to the most common error types and how to self-diagnose and fix them.

1. MissingDataError

What it means: The language attempted to access or process biological data that has not been loaded, does not exist at the specified path, or is structurally corrupted (like a broken .h5ad file).

• Exact Error Example: error: File 'sample.h5ad' not found. or error: No expression data available for this cell.
• How to fix it:
  1. Verify Paths: Check that the file path you provided to functions like cells() or load() is correct and the file exists.
  2. Check Data Integrity: Ensure the H5AD, CSV, or FASTA file is not corrupted.
  3. Order of Operations: Ensure that prerequisite steps were executed (e.g., you cannot call cell.markers() if you haven't loaded expression data into the object).

2. SequenceValidationError

What it means: You initialized a sequence object with characters that are mathematically or biologically invalid for that specific molecule type.

• Exact Error Example: error: Invalid DNA sequence. Allowed characters: A, T, C, G, N.
• How to fix it:
  1. Inspect the string you passed to dna(), rna(), or protein().
  2. Remove invalid characters, hidden spaces, or numbers.
  3. Make sure you aren't passing an RNA string (with 'U') to a dna() object.

3. BiologicalLogicError

What it means: You attempted an operation that violates established biological rules, accessed out-of-bounds parameters, or used an unsupported method on a specific biological object.

• Exact Error Example: error: Cannot translate DNA directly without specifying transcription first or using .translate(). or error: anova on an Experiment requires a 'gene' parameter.
• How to fix it:
  1. Review Parameters: Check the documentation to ensure you are passing all required arguments (e.g., providing a gene name for ANOVA).
  2. Check Biology: Ensure the operation makes biological sense (e.g., you cannot align a Protein directly to a raw Cell without extracting the sequence).

4. BioWarning

What it means: A non-fatal biological anomaly was detected. The script will continue to execute, but the results might be slightly distorted or truncated.

• Exact Error Example: Warning: Sequence length is not a multiple of 3. Final codon will be truncated.
• How to fix it:
  1. Review the data being processed. If you are translating DNA and expect a full functional protein, you may need to slice or pad your sequence to a multiple of 3.

🧪 Domain‑Specific Capabilities

1. Genomics (DNA & RNA)

• DNA Methods: .gc(), .rev(), .comp(), .rev_comp(), .set(), .insert(), .delete(), .mutate(), .composition(), .codons(), .motifs(), .motif(), .promoter(), .orfs(), .transcribe(), .translate(table="standard"), .methylation(), .snp()
• RNA Methods: .gc(), .rev(), .comp(), .rev_comp(), .translate(table="standard"), .dna(), .fold(), .structure()

2. Proteomics

• Protein Methods: .weight(), .charge(), .pi(), .hydrophobicity(), .hydro(), .domains(), .structure(), .mutate(), .interact(), .bind(), .complex()
• Note on protein.structure(): This method now includes a local fallback that searches a local PDB database (via Biopython) for sequences with >90% identity before attempting the ESMFold API. If a match is found, the structure is returned immediately, ensuring higher reliability even without internet access. If both fallback and API fail, a clear error message is provided.

3. Single‑Cell Transcriptomics

• Cell Population (cells): .filter(min_genes, max_mito), .normalize(), .variable_genes(), .reduce("pca"), .cluster("leiden"), .umap(), .trajectory(), .pseudotime(), .find_cells(), .expression(), .distribution(), .correlation(), .markers(), .classify(), .de(), .gsea(), .batch_correct(), .integrate(), .lineage(), .variants(), .histone_mods(), .chromatin_state(), .atac_seq(), .pca_variance()
• Single Cell (cell): .expression(), .markers(), .state(), .type, .label, .pluripotency_score(), .differentiate(), .reprogram(), .lineage()

4. Gene Analysis & CRISPR Engineering

• Gene Methods: .dna(), .rna(), .protein(), .promoter(), .exons(), .introns(), .expression(), .cells(), .compare(), .query(), .enrich()
• CRISPR (requires use crispr): .crispr_design(), .knockout(), .knockin(seq)

5. Experiment & Results Management

• Experiment: .add(sample, cond), .get(name), .compare(c1, c2), .compare_all(), .timecourse(), .filter(), .normalize(), .cluster(), .t_test(), .anova(), .report(), .clear_cache()
• Results: Analytical operations natively return a result object supporting: .info(), .summary(), .top(n), .sort(), .filter(), .select(), .at(idx), .column(name), .graph(), .fdr_correct(), .enrich(), .gsea(), .confusion_matrix()

🧩 Specialized Modules

To keep the core language stable, advanced domain capabilities are loaded dynamically:

use genomics
use transcriptomics
use singlecell
use proteomics
use structure
use stemcell
use crispr
use epigenetics
use statistics
use pathways
use variants
use integration
use visualization

⚙️ Workflows & Python Integration

Automating Pipelines

Workflows record abstract operations to be executed on multiple datasets:

workflow1 = workflow("neural_analysis")
with workflow1:
    sample.filter(min_genes=300)
    sample.normalize()
    sample.reduce("pca")
    sample.cluster("leiden")
    sample.umap()

workflow1.run(new_sample)
workflow1.save("neural_analysis")

Native Python Integration

Blixa supports native Python logic seamlessly inside a python: block:

python:
    for cell in sample:
        if cell.expression("pax6") > 3:
            print(cell.id)

🚀 Execution

To run a Blixa script .blx or enter the interactive REPL:

# Execute a script
blixa script.blx

# Run with detailed verbose logging and timing
blixa --verbose script.blx

# Start the interactive REPL
blixa

# Execute a one‑liner
blixa --execute "dna('ATGC').gc()"

# Show version
blixa --version

📦 Installation & Dependencies

Basic Installation

pip install blixa

This command installs the core Blixa language and its essential scientific dependencies without the optional psutil package. The language functions perfectly in this configuration.

Full Installation (Recommended)

pip install blixa[full]

This command installs the core language along with all optional dependencies, including psutil. psutil is completely optional but highly recommended as it enables advanced, memory-aware cache eviction—automatically protecting your system by clearing cached biological data when available RAM drops below critical levels.

Python Version

Requires Python >= 3.10.

Internet Access for Protein Structure Prediction

The protein.structure() method uses the ESMFold API (Meta AI) as its primary source for 3D structure prediction. However, if the API is unavailable, a local PDB fallback is used automatically. An active internet connection is still recommended for the best results, but the fallback ensures higher reliability.

📝 License & Citation

Blixa is released under the MIT License. See LICENSE for details.

If you use Blixa in your research, please cite:

Ahmed Tarig Ahmed Abdalgaleel. (2026). Blixa: A Domain‑Specific Language for Biological Research (Version 1.1.3). https://github.com/your-repo/blixa