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

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())

🧪 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

# 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

Full Installation (includes optional memory monitoring)

pip install blixa[full]

The optional psutil library enables advanced memory‑aware cache eviction. If not installed, the cache will rely only on its LRU size limit, and a warning will be shown once.

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.2). https://github.com/your-repo/blixa