Metadata-Version: 2.4
Name: blixa
Version: 1.1.6
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
Requires-Dist: igraph==0.11.8
Requires-Dist: leidenalg==0.10.2
Requires-Dist: lark==1.3.1
Requires-Dist: RestrictedPython==8.5
Provides-Extra: full
Requires-Dist: psutil==6.0.0; extra == "full"
Dynamic: license-file

# README.md

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

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