Metadata-Version: 2.4
Name: blixa
Version: 1.0.9
Summary: Blixa: A Domain-Specific Language for Biological Research
Author: AHMED TARIG AHMED ABDALGALEEL
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==2.1.1
Requires-Dist: pandas==2.2.3
Requires-Dist: biopython==1.86
Requires-Dist: scanpy==1.10.3
Requires-Dist: anndata==0.10.9
Requires-Dist: matplotlib==3.9.2
Requires-Dist: seaborn==0.13.2
Requires-Dist: scikit-learn==1.5.2
Requires-Dist: statsmodels==0.14.4
Requires-Dist: joblib==1.4.2
Requires-Dist: pytest==8.3.3
Requires-Dist: seqfold==0.10.2
Requires-Dist: gseapy==1.1.4
Provides-Extra: full
Requires-Dist: psutil==6.0.0; extra == "full"
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🧬 Blixa Research Language (Blixa) - Core Syntax v1.0.9

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

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

---

## 🚀 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 uses the ESMFold API (Meta AI) and requires an active internet connection. It sends your protein sequence to the remote API for structure prediction.

### 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) to predict 3D structures. An active internet connection is required, and the sequence must consist only of standard amino acids (length up to ~400 residues is recommended).

---

## 📝 License & Citation

Blixa is released under the MIT License. See [LICENSE](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.0.9). [https://github.com/your-repo/blixa](https://github.com/your-repo/blixa)
