README.md

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

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.

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), save(data, file), export(data, file), integrate(), parallel(), clear_cache()

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

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
python run.py analysis.blx

# Start the interactive REPL
python run.py