@pikaa-ai/pikaa 0.3.22 → 0.3.24

package/skills/deepchem/SKILL.md

@@ -1,244 +0,0 @@
----
-name: deepchem
-description: Molecular ML with diverse featurizers and pre-built datasets. Use for property prediction (ADMET, toxicity) with traditional ML or GNNs when you want extensive featurization options and MoleculeNet benchmarks. Best for quick experiments with pre-trained models, diverse molecular representations. For graph-first PyTorch workflows use torchdrug; for benchmark datasets use pytdc.
-license: MIT license
-allowed-tools: Read Write Edit Bash
-compatibility: Requires Python 3.7–3.11 (PyPI 2.8.0 caps at <3.12). Install PyTorch, TensorFlow, or JAX before the matching deepchem extra. RDKit is a core dependency.
-metadata:
-  version: "1.4"
-  skill-author: K-Dense Inc.
----
-
-# DeepChem
-
-## Overview
-
-DeepChem is a comprehensive Python library for applying machine learning to chemistry, materials science, and biology. Enable molecular property prediction, drug discovery, materials design, and biomolecule analysis through specialized neural networks, molecular featurization methods, and pretrained models.
-
-**Version note:** Examples target **deepchem 2.8.0** (PyPI stable, Apr 2024). Requires **Python 3.7–3.11** (`<3.12` on PyPI). Core utilities (loaders, featurizers, MoleculeNet) work without a DL backend; GNN and transformer models need the matching extra (`torch`, `tensorflow`, or `jax`). Install the backend framework first when using GPU builds.
-
-## When to Use This Skill
-
-This skill should be used when:
-- Loading and processing molecular data (SMILES strings, SDF files, protein sequences)
-- Predicting molecular properties (solubility, toxicity, binding affinity, ADMET properties)
-- Training models on chemical/biological datasets
-- Using MoleculeNet benchmark datasets (Tox21, BBBP, Delaney, etc.)
-- Converting molecules to ML-ready features (fingerprints, graph representations, descriptors)
-- Implementing graph neural networks for molecules (GCN, GAT, MPNN, AttentiveFP)
-- Applying transfer learning with pretrained models (ChemBERTa, GROVER, MolFormer)
-- Predicting crystal/materials properties (bandgap, formation energy)
-- Analyzing protein or DNA sequences
-
-## Core Capabilities
-
-Eight capability areas, each with worked code, are in
-[references/core_capabilities.md](references/core_capabilities.md):
-
-1. **Molecular data loading and processing** — loaders, `NumpyDataset` / `DiskDataset`.
-2. **Molecular featurization** — circular fingerprints, graph convolution, and descriptors.
-3. **Data splitting** — random, scaffold, stratified, and butina splitters, and why
-   scaffold splitting is the honest default for molecules.
-4. **Model selection and training** — the model families and how to fit them.
-5. **MoleculeNet benchmarks** — loading standard datasets and their published splits.
-6. **Transfer learning** — pretraining and fine-tuning.
-7. **Model evaluation** — metrics appropriate to regression and classification tasks.
-8. **Making predictions** — applying a trained model to new molecules.
-
-Three end-to-end workflows are in
-[references/typical_workflows.md](references/typical_workflows.md).
-
-## Example Scripts
-
-This skill includes three production-ready scripts in the `scripts/` directory:
-
-### 1. `predict_solubility.py`
-Train and evaluate solubility prediction models. Works with Delaney benchmark or custom CSV data.
-
-```bash
-# Use Delaney benchmark
-python scripts/predict_solubility.py
-
-# Use custom data
-python scripts/predict_solubility.py \
-    --data my_data.csv \
-    --smiles-col smiles \
-    --target-col solubility \
-    --predict "CCO" "c1ccccc1"
-```
-
-### 2. `graph_neural_network.py`
-Train various graph neural network architectures on molecular data.
-
-```bash
-# Train GCN on Tox21
-python scripts/graph_neural_network.py --model gcn --dataset tox21
-
-# Train AttentiveFP on custom data
-python scripts/graph_neural_network.py \
-    --model attentivefp \
-    --data molecules.csv \
-    --task-type regression \
-    --targets activity \
-    --epochs 100
-```
-
-### 3. `transfer_learning.py`
-Fine-tune pretrained models (ChemBERTa, GROVER, MolFormer) on molecular property prediction tasks.
-
-```bash
-# Fine-tune ChemBERTa on BBBP
-python scripts/transfer_learning.py --model chemberta --dataset bbbp
-
-# Fine-tune GROVER on custom data
-python scripts/transfer_learning.py \
-    --model grover \
-    --data small_dataset.csv \
-    --target activity \
-    --task-type classification \
-    --epochs 20
-```
-
-## Common Patterns and Best Practices
-
-### Pattern 1: Always Use Scaffold Splitting for Molecules
-```python
-# GOOD: Prevents data leakage
-splitter = dc.splits.ScaffoldSplitter()
-train, test = splitter.train_test_split(dataset)
-
-# BAD: Similar molecules in train and test
-splitter = dc.splits.RandomSplitter()
-train, test = splitter.train_test_split(dataset)
-```
-
-### Pattern 2: Normalize Features and Targets
-```python
-transformers = [
-    dc.trans.NormalizationTransformer(
-        transform_y=True,  # Also normalize target values
-        dataset=train
-    )
-]
-for transformer in transformers:
-    train = transformer.transform(train)
-    test = transformer.transform(test)
-```
-
-### Pattern 3: Start Simple, Then Scale
-1. Start with Random Forest + CircularFingerprint (fast baseline)
-2. Try XGBoost/LightGBM if RF works well
-3. Move to deep learning (MultitaskRegressor) if you have >5K samples
-4. Try GNNs if you have >10K samples
-5. Use transfer learning for small datasets or novel scaffolds
-
-### Pattern 4: Handle Imbalanced Data
-```python
-# Option 1: Balancing transformer
-transformer = dc.trans.BalancingTransformer(dataset=train)
-train = transformer.transform(train)
-
-# Option 2: Use balanced metrics
-metric = dc.metrics.Metric(dc.metrics.balanced_accuracy_score)
-```
-
-### Pattern 5: Avoid Memory Issues
-```python
-# Use DiskDataset for large datasets
-dataset = dc.data.DiskDataset.from_numpy(X, y, w, ids)
-
-# Use smaller batch sizes
-model = dc.models.GCNModel(batch_size=32)  # Instead of 128
-```
-
-## Common Pitfalls
-
-### Issue 1: Data Leakage in Drug Discovery
-**Problem**: Using random splitting allows similar molecules in train/test sets.
-**Solution**: Always use `ScaffoldSplitter` for molecular datasets.
-
-### Issue 2: GNN Underperforming vs Fingerprints
-**Problem**: Graph neural networks perform worse than simple fingerprints.
-**Solutions**:
-- Ensure dataset is large enough (>10K samples typically)
-- Increase training epochs (50-100)
-- Try different architectures (AttentiveFP, DMPNN instead of GCN)
-- Use pretrained models (GROVER)
-
-### Issue 3: Overfitting on Small Datasets
-**Problem**: Model memorizes training data.
-**Solutions**:
-- Use stronger regularization (increase dropout to 0.5)
-- Use simpler models (Random Forest instead of deep learning)
-- Apply transfer learning (ChemBERTa, GROVER)
-- Collect more data
-
-### Issue 4: Import Errors
-**Problem**: `No module named 'torch'` / `No module named 'tensorflow'` warnings, or model classes fail to import.
-**Solution**: DeepChem loads lazily — install the backend that matches your model, then add the matching extra:
-```bash
-uv pip install deepchem              # loaders, featurizers, MoleculeNet only
-uv pip install 'deepchem[torch]'       # GCN, GAT, AttentiveFP, HuggingFaceModel, GroverModel
-uv pip install 'deepchem[tensorflow]'  # legacy Keras models
-uv pip install 'deepchem[jax]'         # Haiku/JAX models
-```
-Install PyTorch or TensorFlow with the correct CUDA build **before** the extra when using GPUs. Quote extras in zsh: `'deepchem[torch]'`.
-
-**Conda + PyTorch users:** If `import deepchem` fails with `undefined symbol: iJIT_NotifyEvent`, pin MKL below 2025 (`conda install "mkl<2025"`) — PyTorch wheels may be incompatible with MKL 2025.0.0.
-
-## Reference Documentation
-
-This skill includes comprehensive reference documentation:
-
-### `references/api_reference.md`
-Complete API documentation including:
-- All data loaders and their use cases
-- Dataset classes and when to use each
-- Complete featurizer catalog with selection guide
-- Model catalog organized by category (50+ models)
-- MoleculeNet dataset descriptions
-- Metrics and evaluation functions
-- Common code patterns
-
-**When to reference**: Search this file when you need specific API details, parameter names, or want to explore available options.
-
-### `references/workflows.md`
-Eight detailed end-to-end workflows:
-1. Molecular property prediction from SMILES
-2. Using MoleculeNet benchmarks
-3. Hyperparameter optimization
-4. Transfer learning with pretrained models
-5. Molecular generation with GANs
-6. Materials property prediction
-7. Protein sequence analysis
-8. Custom model integration
-
-**When to reference**: Use these workflows as templates for implementing complete solutions.
-
-## Installation
-
-Core package (data loaders, featurizers, MoleculeNet, scikit-learn wrappers):
-
-```bash
-uv pip install deepchem
-```
-
-Add the extra that matches your model backend (install PyTorch/TensorFlow/JAX first for GPU builds):
-
-```bash
-uv pip install 'deepchem[torch]'       # GNNs, TorchModel, HuggingFaceModel, GroverModel
-uv pip install 'deepchem[tensorflow]'  # Keras/TensorFlow models
-uv pip install 'deepchem[jax]'         # JAX/Haiku models
-uv pip install 'deepchem[dqc]'         # Differentiable quantum chemistry (torch + xitorch)
-```
-
-Nightly builds: `uv pip install --pre deepchem` (same extras apply with `--pre`).
-
-See [installation guide](https://deepchem.readthedocs.io/en/latest/get_started/installation.html) and [soft requirements](https://deepchem.readthedocs.io/en/latest/requirements.html) for optional dependencies per model class.
-
-## Additional Resources
-
-- Official documentation: https://deepchem.readthedocs.io/
-- GitHub repository: https://github.com/deepchem/deepchem
-- Tutorials: https://deepchem.readthedocs.io/en/latest/get_started/tutorials.html
-- Paper: "MoleculeNet: A Benchmark for Molecular Machine Learning"

package/skills/deepspot-m/SKILL.md

@@ -1,175 +0,0 @@
----
-name: deepspot-m
-description: Generate transcriptome-wide virtual spatial transcriptomics from H&E histology with DeepSpot-M. Use when you need spatial gene expression in log1p-CPM for 224x224 tiles at about 20x, want to query protein-coding genes by symbol instead of a fixed panel, or want to run prediction across a whole slide after tiling with histolab.
-license: PolyForm-Noncommercial-1.0.0
-compatibility: Needs deepspotm 1.0.0 from PyPI (Python 3.10 to 3.13) plus PyTorch. Weights at ratschlab/DeepSpotM on Hugging Face are gated and licensed CC-BY-NC-SA-4.0, so request access on the model page and then run huggingface-cli login. A CUDA GPU speeds up batched inference.
-allowed-tools: Read Write Edit Bash
-metadata:
-  version: "1.0"
-  skill-author: Ratschlab, ETH Zurich
----
-
-# DeepSpot-M
-
-## Overview
-
-DeepSpot-M is a multimodal foundation model that maps a 224x224 H&E histology tile to
-spatial gene expression in log1p-CPM. The output is virtual spatial transcriptomics: one
-value per queried gene per tile, laid out on the grid the tiles came from.
-
-A LoRA-adapted pathology foundation backbone (Midnight) tokenises the tile. A
-cross-attention gene decoder lets each gene query attend to the patch tokens, and a gene
-router hypernetwork builds gene-specific projections from frozen biological embeddings
-(Evo 2, Orthrus, ProtT5, scGPT, Apertus). Genes enter the model as queryable embeddings
-rather than fixed output slots, so the released model covers a ~19k protein-coding gene
-panel including genes unseen in training. The panel ships with the weights as
-`tokens.csv` and is exposed as `model.gene_names`; genes outside it cannot be queried in
-this release.
-
-Applied to TCGA, the model produced a virtual spatial transcriptomics atlas of 28,664
-slides across 32 cancer types.
-
-## Licensing
-
-The code is PolyForm Noncommercial 1.0.0 and the weights are CC-BY-NC-SA-4.0. Use it for
-noncommercial research and check both licences before redistributing outputs.
-
-## Installation
-
-```bash
-uv pip install deepspotm==1.0.0
-```
-
-Version 1.0.0 targets Python 3.10 to 3.13 and pulls in PyTorch. Install the PyTorch build
-that matches your CUDA version first if you want GPU inference.
-
-## Model access
-
-The weights are gated:
-
-1. Open <https://huggingface.co/ratschlab/DeepSpotM> and request access.
-2. Once access is granted, authenticate the machine that will download them:
-
-```bash
-huggingface-cli login
-```
-
-`from_pretrained` reads that cached token, so a login is needed once per machine.
-
-## Quick start
-
-```python
-from deepspotm import DeepSpotM
-
-model, image_processor = DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source="scgpt")
-
-vals = model.predict_genes(image_processor(pil_tile).unsqueeze(0), ["EPCAM", "CD3D"])
-```
-
-`pil_tile` is a PIL image of exactly 224x224 pixels. `image_processor` turns it into a
-tensor, `unsqueeze(0)` adds the batch dimension, and `predict_genes` takes the batch plus a
-list of HGNC gene symbols. Values come back in log1p-CPM, aligned with the gene list you
-passed, so keep that list beside the output to keep the columns labelled. Symbols must be
-in the released ~19k-gene panel (`model.gene_names`); an unknown symbol raises `KeyError`
-naming the offending genes.
-
-## Tile requirements
-
-Tiles must be 224x224 RGB at roughly 20x magnification (about 0.5 microns per pixel). Check
-the size at the boundary of your pipeline rather than passing an unchecked crop through:
-
-```python
-TILE_PX = 224
-
-def require_tile(tile):
-    """Return an RGB 224x224 tile, or raise if the crop is the wrong size."""
-    if tile.size != (TILE_PX, TILE_PX):
-        raise ValueError(
-            f"DeepSpot-M expects a {TILE_PX}x{TILE_PX} tile at about 20x "
-            f"(~0.5 microns per pixel); got {tile.size[0]}x{tile.size[1]}. "
-            "Re-tile at the matching level or resample the crop."
-        )
-    return tile.convert("RGB")
-```
-
-Extract tiles at the slide level whose resolution is nearest 0.5 microns per pixel, then
-crop to 224x224 there. Resampling from a coarser level changes the texture the backbone
-reads.
-
-## Keep the dependency optional
-
-`deepspotm` and its weights are a heavy, gated dependency. Import it inside the function
-that needs it so the surrounding project installs, imports and tests without it, and turn
-an `ImportError` into a message that names every step:
-
-```python
-DEEPSPOTM_HELP = (
-    "DeepSpot-M is unavailable. Install it with `uv pip install deepspotm==1.0.0`, request "
-    "access to the gated weights at https://huggingface.co/ratschlab/DeepSpotM, then "
-    "authenticate with `huggingface-cli login`."
-)
-
-def load_deepspotm(source="scgpt"):
-    try:
-        from deepspotm import DeepSpotM
-    except ImportError as exc:
-        raise RuntimeError(DEEPSPOTM_HELP) from exc
-    return DeepSpotM.from_pretrained("ratschlab/DeepSpotM", source=source)
-```
-
-## Embedding sources
-
-`source` selects which frozen gene embedding the router builds projections from. It is one
-of five values:
-
-| `source`  | Gene embedding                    |
-| --------- | --------------------------------- |
-| `evo2`    | genomic sequence                  |
-| `orthrus` | RNA                               |
-| `prott5`  | protein sequence                  |
-| `scgpt`   | single-cell expression            |
-| `apertus` | language model                    |
-
-Each gives a different view of gene identity. Pick one per run, and run the same tiles
-through more than one source when the choice matters to your analysis. See
-`references/api.md` for the full call surface, batching and device placement, gene symbol
-handling and output units.
-
-## Whole slide workflow
-
-Prediction is per tile, so a slide-scale run is a tiling step followed by batched
-inference:
-
-1. Extract 224x224 tiles on a grid with the `histolab` skill, keeping each tile's
-   coordinates.
-2. Process and stack tiles into batches with `torch.stack`.
-3. Call `predict_genes` once per batch with the same gene list.
-4. Concatenate the batches into a tiles-by-genes matrix and attach the coordinates.
-
-That matrix is the virtual spatial transcriptomics map for the slide, and it drops
-straight into `AnnData` for downstream spatial analysis. `references/whole_slide.md` has a
-worked loop, batch sizing and an `AnnData` assembly step.
-
-## Common use cases
-
-- Spatial expression maps for marker genes across a tumour section.
-- Transcriptome-wide prediction over a slide cohort with no matching assay run.
-- Querying any of the ~19k panel genes by symbol, including genes unseen in training —
-  far beyond the few hundred genes of a typical spatial assay panel.
-- Adding an expression channel to a morphology-only histology pipeline.
-- Building a slide-level cohort atlas, as done for TCGA.
-
-## Detailed references
-
-- `references/api.md`: `from_pretrained` and `predict_genes` in full, the five embedding
-  sources and how to choose, batching, device placement, gene symbol handling, and
-  converting log1p-CPM output.
-- `references/whole_slide.md`: tiling with histolab, a slide-scale prediction loop,
-  assembling and storing a tiles-by-genes matrix, and cohort-scale runs.
-
-## Primary sources
-
-- Paper: <https://doi.org/10.64898/2026.06.19.26356060> (medRxiv, posted 22 June 2026)
-- Code: <https://github.com/ratschlab/DeepSpotM>
-- Weights: <https://huggingface.co/ratschlab/DeepSpotM>
-- PyPI: <https://pypi.org/project/deepspotm/>