Scientific Skills

Claude Scientific Skills

Overview

A comprehensive collection of 139 ready-to-use scientific skills that transform Claude into an AI research assistant capable of executing complex multi-step scientific workflows across biology, chemistry, medicine, and related fields.

When to Use

Invoke this skill when:

• Working on scientific research tasks
• Need access to specialized databases (PubMed, ChEMBL, UniProt, etc.)
• Performing bioinformatics or cheminformatics analysis
• Creating literature reviews or scientific documents
• Analyzing single-cell RNA-seq, proteomics, or multi-omics data
• Drug discovery and molecular analysis workflows
• Statistical analysis and machine learning on scientific data

Quick Start

// Invoke the main skill catalog
Skill({ skill: 'scientific-skills' });

// Or invoke specific sub-skills directly
Skill({ skill: 'scientific-skills/rdkit' }); // Cheminformatics
Skill({ skill: 'scientific-skills/scanpy' }); // Single-cell analysis
Skill({ skill: 'scientific-skills/biopython' }); // Bioinformatics
Skill({ skill: 'scientific-skills/literature-review' }); // Literature review

Skill Categories

Scientific Databases (28+)

Python Analysis Libraries (55+)

Bioinformatics & Genomics

Cheminformatics & Drug Discovery

Scientific Communication

Clinical & Medical

Laboratory & Integration

Core Workflows

Literature Review Workflow

# 7-phase systematic literature review
# 1. Planning with PICO framework
# 2. Multi-database search execution
# 3. Screening with PRISMA flow
# 4. Data extraction and quality assessment
# 5. Thematic synthesis
# 6. Citation verification
# 7. PDF generation

Drug Discovery Workflow

# Using RDKit + ChEMBL + datamol
from rdkit import Chem
from rdkit.Chem import Descriptors, AllChem

# 1. Query ChEMBL for bioactivity data
# 2. Calculate molecular properties
# 3. Filter by drug-likeness (Lipinski)
# 4. Similarity screening
# 5. Substructure analysis

Single-Cell Analysis Workflow

# Using scanpy + anndata
import scanpy as sc

# 1. Load and QC data
# 2. Normalization and feature selection
# 3. Dimensionality reduction (PCA, UMAP)
# 4. Clustering (Leiden algorithm)
# 5. Marker gene identification
# 6. Cell type annotation

Hypothesis Generation Workflow

# 8-step systematic process
# 1. Understand phenomenon
# 2. Literature search
# 3. Synthesize evidence
# 4. Generate competing hypotheses
# 5. Evaluate quality
# 6. Design experiments
# 7. Formulate predictions
# 8. Generate report

Sub-Skill Structure

Each sub-skill follows a consistent structure:

scientific-skills/
├── SKILL.md                    # This file (catalog/index)
├── skills/                     # Individual skill directories
│   ├── rdkit/
│   │   ├── SKILL.md           # Skill documentation
│   │   ├── references/        # API references, patterns
│   │   └── scripts/           # Example scripts
│   ├── scanpy/
│   ├── biopython/
│   └── ... (139 total)

Invoking Sub-Skills

Direct Invocation

// Invoke specific skill
Skill({ skill: 'scientific-skills/rdkit' });
Skill({ skill: 'scientific-skills/scanpy' });

Chained Workflows

// Multi-skill workflow
Skill({ skill: 'scientific-skills/literature-review' });
Skill({ skill: 'scientific-skills/hypothesis-generation' });
Skill({ skill: 'scientific-skills/scientific-schematics' });

Prerequisites

• Python 3.9+ (3.12+ recommended)
• uv package manager (recommended)
• Platform: macOS, Linux, or Windows with WSL2

Best Practices

1. Start with the right skill: Use the category tables above to find appropriate skills 2. Chain skills for complex workflows: Literature review → Hypothesis → Experiment design 3. Use database skills for data access: Query databases before analysis 4. Visualize results: Use matplotlib/seaborn/plotly skills for publication-quality figures 5. Document findings: Use scientific-writing skill for formal documentation

Integration with Agent Framework

Recommended Agent Pairings

Example Agent Spawn

Task({
  task_id: 'task-1',
  subagent_type: 'python-pro',
  description: 'Analyze molecular dataset with RDKit',
  prompt: `You are the PYTHON-PRO agent with scientific research expertise.

## Task
Analyze the molecular dataset for drug-likeness properties.

## Skills to Invoke
1. Skill({ skill: "scientific-skills/rdkit" })
2. Skill({ skill: "scientific-skills/datamol" })

## Workflow
1. Load molecular data
2. Calculate descriptors
3. Apply Lipinski filters
4. Generate visualization
5. Report findings
`,
});

Resources

Bundled Documentation

• skills/*/SKILL.md - Individual skill documentation
• skills/*/references/ - API references and patterns
• skills/*/scripts/ - Example scripts and templates

External Resources

• K-Dense AI GitHub
• RDKit Documentation
• Scanpy Documentation
• BioPython Tutorial

Iron Laws

1. ALWAYS query scientific databases (PubMed, ChEMBL, UniProt) before performing any analysis — raw analysis without literature and database context produces uninformed conclusions that duplicate prior work. 2. NEVER perform analysis without documenting all steps (data sources, parameters, library versions, transformations) — undocumented research is irreproducible and cannot be peer-reviewed or extended. 3. ALWAYS chain multiple domain-specific skills for complex workflows — single-tool analysis misses interdependencies across biology, chemistry, and clinical domains. 4. NEVER report findings without statistical validation — scientific claims require appropriately sized samples, validated methods, and quantified uncertainty. 5. ALWAYS visualize intermediate results after each major processing step — data errors and outliers surface in visualizations before propagating silently to final conclusions.

Anti-Patterns

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern → .claude/context/memory/learnings.md
• Issue found → .claude/context/memory/issues.md
• Decision made → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

Version History

• v2.17.0 - Current version with 139 skills
• Integrated from K-Dense-AI/claude-scientific-skills repository

License

MIT License - Open source and freely available for research and commercial use.

Invoke the scientific-skills skill and follow it exactly as presented to you

Claude Scientific Skills

 

A comprehensive collection of 140 ready-to-use scientific skills for Claude, created by K-Dense. Transform Claude into your AI research assistant capable of executing complex multi-step scientific workflows across biology, chemistry, medicine, and beyond.

Looking for the full AI co-scientist experience? Try K-Dense Web for 200+ skills, cloud compute, and publication-ready outputs.

<p align="center"> <a href="https://k-dense.ai"> <img src="docs/k-dense-web.gif" alt="K-Dense Web Demo" width="800"/> </a> </p>

---

K-Dense Web - The Full Experience

Want 10x the power with zero setup? [K-Dense Web](https://k-dense.ai) is the complete AI co-scientist platform—everything in this repo, plus:

Researchers at Stanford, MIT, and leading pharma companies use K-Dense Web to accelerate discoveries.

Get $50 in free credits — no credit card required.

<a href="https://k-dense.ai"><img src="https://img.shields.io/badge/Try_K--Dense_Web-Start_Free-blue?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PHBhdGggZD0iTTUgMTJoMTQiLz48cGF0aCBkPSJtMTIgNSA3IDctNyA3Ii8+PC9zdmc+" alt="Try K-Dense Web"></a>

_Learn more at k-dense.ai_ | _Read our detailed comparison →_

---

These skills enable Claude to seamlessly work with specialized scientific libraries, databases, and tools across multiple scientific domains:

• 🧬 Bioinformatics & Genomics - Sequence analysis, single-cell RNA-seq, gene regulatory networks, variant annotation, phylogenetic analysis
• 🧪 Cheminformatics & Drug Discovery - Molecular property prediction, virtual screening, ADMET analysis, molecular docking, lead optimization
• 🔬 Proteomics & Mass Spectrometry - LC-MS/MS processing, peptide identification, spectral matching, protein quantification
• 🏥 Clinical Research & Precision Medicine - Clinical trials, pharmacogenomics, variant interpretation, drug safety, clinical decision support, treatment planning
• 🧠 Healthcare AI & Clinical ML - EHR analysis, physiological signal processing, medical imaging, clinical prediction models
• 🖼️ Medical Imaging & Digital Pathology - DICOM processing, whole slide image analysis, computational pathology, radiology workflows
• 🤖 Machine Learning & AI - Deep learning, reinforcement learning, time series analysis, model interpretability, Bayesian methods
• 🔮 Materials Science & Chemistry - Crystal structure analysis, phase diagrams, metabolic modeling, computational chemistry
• 🌌 Physics & Astronomy - Astronomical data analysis, coordinate transformations, cosmological calculations, symbolic mathematics, physics computations
• ⚙️ Engineering & Simulation - Discrete-event simulation, multi-objective optimization, metabolic engineering, systems modeling, process optimization
• 📊 Data Analysis & Visualization - Statistical analysis, network analysis, time series, publication-quality figures, large-scale data processing, EDA
• 🧪 Laboratory Automation - Liquid handling protocols, lab equipment control, workflow automation, LIMS integration
• 📚 Scientific Communication - Literature review, peer review, scientific writing, document processing, posters, slides, schematics, citation management
• 🔬 Multi-omics & Systems Biology - Multi-modal data integration, pathway analysis, network biology, systems-level insights
• 🧬 Protein Engineering & Design - Protein language models, structure prediction, sequence design, function annotation
• 🎓 Research Methodology - Hypothesis generation, scientific brainstorming, critical thinking, grant writing, scholar evaluation

Transform Claude Code into an 'AI Scientist' on your desktop!

⭐ If you find this repository useful, please consider giving it a star! It helps others discover these tools and encourages us to continue maintaining and expanding this collection.

---

📦 What's Included

This repository provides 140 scientific skills organized into the following categories:

• 28+ Scientific Databases - Direct API access to OpenAlex, PubMed, bioRxiv, ChEMBL, UniProt, COSMIC, ClinicalTrials.gov, and more
• 55+ Python Packages - RDKit, Scanpy, PyTorch Lightning, scikit-learn, BioPython, BioServices, PennyLane, Qiskit, and others
• 15+ Scientific Integrations - Benchling, DNAnexus, LatchBio, OMERO, Protocols.io, and more
• 30+ Analysis & Communication Tools - Literature review, scientific writing, peer review, document processing, posters, slides, schematics, and more
• 10+ Research & Clinical Tools - Hypothesis generation, grant writing, clinical decision support, treatment plans, regulatory compliance

Each skill includes:

• ✅ Comprehensive documentation (SKILL.md)
• ✅ Practical code examples
• ✅ Use cases and best practices
• ✅ Integration guides
• ✅ Reference materials

---

📋 Table of Contents

• What's Included
• Why Use This?
• Getting Started
• Claude Code
• Cursor IDE
• Any MCP Client
• Support Open Source
• Prerequisites
• Quick Examples
• Use Cases
• Available Skills
• Contributing
• Troubleshooting
• FAQ
• Support
• Join Our Community
• Citation
• License

---

🚀 Why Use This?

⚡ Accelerate Your Research

• Save Days of Work - Skip API documentation research and integration setup
• Production-Ready Code - Tested, validated examples following scientific best practices
• Multi-Step Workflows - Execute complex pipelines with a single prompt

🎯 Comprehensive Coverage

• 140 Skills - Extensive coverage across all major scientific domains
• 28+ Databases - Direct access to OpenAlex, PubMed, bioRxiv, ChEMBL, UniProt, COSMIC, and more
• 55+ Python Packages - RDKit, Scanpy, PyTorch Lightning, scikit-learn, BioServices, PennyLane, Qiskit, and others

🔧 Easy Integration

• One-Click Setup - Install via Claude Code or MCP server
• Automatic Discovery - Claude automatically finds and uses relevant skills
• Well Documented - Each skill includes examples, use cases, and best practices

🌟 Maintained & Supported

• Regular Updates - Continuously maintained and expanded by K-Dense team
• Community Driven - Open source with active community contributions
• Enterprise Ready - Commercial support available for advanced needs

---

🎯 Getting Started

Choose your preferred platform to get started:

🖥️ Claude Code (Recommended)

📚 New to Claude Code? Check out the Claude Code Quickstart Guide to get started. When using Claude Code please use the Skills as a plugin. Do not use the MCP server below.

Step 1: Install Claude Code

macOS:

curl -fsSL https://claude.ai/install.sh | bash

Windows:

irm https://claude.ai/install.ps1 | iex

Step 2: Register the Marketplace

In Claude Code, run the following command:

/plugin marketplace add K-Dense-AI/claude-scientific-skills

Step 3: Install the Plugin

Option A: Direct Install (Fastest)

/plugin install scientific-skills@claude-scientific-skills

Option B: Interactive Install

1. Run /plugin in Claude Code 2. Select Browse and install plugins 3. Choose claude-scientific-skills marketplace 4. Select scientific-skills 5. Click Install now

That's it! Claude will automatically use the appropriate skills when you describe your scientific tasks.

Managing Your Plugin:

# Check installed plugins
/plugin → Manage Plugins

# Update the plugin to the latest version
/plugin update scientific-skills@claude-scientific-skills

# Enable/disable the plugin
/plugin enable scientific-skills@claude-scientific-skills
/plugin disable scientific-skills@claude-scientific-skills

# Uninstall if needed
/plugin uninstall scientific-skills@claude-scientific-skills

---

⌨️ Cursor IDE

One-click installation via our hosted MCP server:

<a href="https://cursor.com/en-US/install-mcp?name=claude-scientific-skills&config=eyJ1cmwiOiJodHRwczovL21jcC5rLWRlbnNlLmFpL2NsYXVkZS1zY2llbnRpZmljLXNraWxscy9tY3AifQ%3D%3D"> <picture> <source srcset="https://cursor.com/deeplink/mcp-install-light.svg" media="(prefers-color-scheme: dark)"> <source srcset="https://cursor.com/deeplink/mcp-install-dark.svg" media="(prefers-color-scheme: light)"> <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install MCP Server" style="height:2.7em;"/> </picture> </a>

---

🔌 Any MCP Client (Not for Claude Code)

Access all skills via our MCP server in any MCP-compatible client (ChatGPT, Google ADK, OpenAI Agent SDK, etc.):

Option 1: Hosted MCP Server (Easiest)

https://mcp.k-dense.ai/claude-scientific-skills/mcp

Option 2: Self-Hosted (More Control) 🔗 [claude-skills-mcp](https://github.com/K-Dense-AI/claude-skills-mcp) - Deploy your own MCP server

---

❤️ Support the Open Source Community

Claude Scientific Skills is powered by 50+ incredible open source projects maintained by dedicated developers and research communities worldwide. Projects like Biopython, Scanpy, RDKit, scikit-learn, PyTorch Lightning, and many others form the foundation of these skills.

If you find value in this repository, please consider supporting the projects that make it possible:

• ⭐ Star their repositories on GitHub
• 💰 Sponsor maintainers via GitHub Sponsors or NumFOCUS
• 📝 Cite projects in your publications
• 💻 Contribute code, docs, or bug reports

👉 [View the full list of projects to support](docs/open-source-sponsors.md)

---

⚙️ Prerequisites

• Python: 3.9+ (3.12+ recommended for best compatibility)
• uv: Python package manager (required for installing skill dependencies)
• Client: Claude Code, Cursor, or any MCP-compatible client
• System: macOS, Linux, or Windows with WSL2
• Dependencies: Automatically handled by individual skills (check SKILL.md files for specific requirements)

Installing uv

The skills use uv as the package manager for installing Python dependencies. Install it using the instructions for your operating system:

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative (via pip):

pip install uv

After installation, verify it works by running:

uv --version

For more installation options and details, visit the official uv documentation.

---

💡 Quick Examples

Once you've installed the skills, you can ask Claude to execute complex multi-step scientific workflows. Here are some example prompts:

🧪 Drug Discovery Pipeline

Goal: Find novel EGFR inhibitors for lung cancer treatment

Prompt:

Use available skills you have access to whenever possible. Query ChEMBL for EGFR inhibitors (IC50 < 50nM), analyze structure-activity relationships
with RDKit, generate improved analogs with datamol, perform virtual screening with DiffDock
against AlphaFold EGFR structure, search PubMed for resistance mechanisms, check COSMIC for
mutations, and create visualizations and a comprehensive report.

Skills Used: ChEMBL, RDKit, datamol, DiffDock, AlphaFold DB, PubMed, COSMIC, scientific visualization

---

🔬 Single-Cell RNA-seq Analysis

Goal: Comprehensive analysis of 10X Genomics data with public data integration

Prompt:

Use available skills you have access to whenever possible. Load 10X dataset with Scanpy, perform QC and doublet removal, integrate with Cellxgene
Census data, identify cell types using NCBI Gene markers, run differential expression with
PyDESeq2, infer gene regulatory networks with Arboreto, enrich pathways via Reactome/KEGG,
and identify therapeutic targets with Open Targets.

Skills Used: Scanpy, Cellxgene Census, NCBI Gene, PyDESeq2, Arboreto, Reactome, KEGG, Open Targets

---

🧬 Multi-Omics Biomarker Discovery

Goal: Integrate RNA-seq, proteomics, and metabolomics to predict patient outcomes

Prompt:

Use available skills you have access to whenever possible. Analyze RNA-seq with PyDESeq2, process mass spec with pyOpenMS, integrate metabolites from
HMDB/Metabolomics Workbench, map proteins to pathways (UniProt/KEGG), find interactions via
STRING, correlate omics layers with statsmodels, build predictive model with scikit-learn,
and search ClinicalTrials.gov for relevant trials.

Skills Used: PyDESeq2, pyOpenMS, HMDB, Metabolomics Workbench, UniProt, KEGG, STRING, statsmodels, scikit-learn, ClinicalTrials.gov

---

🎯 Virtual Screening Campaign

Goal: Discover allosteric modulators for protein-protein interactions

Prompt:

Use available skills you have access to whenever possible. Retrieve AlphaFold structures, identify interaction interface with BioPython, search ZINC
for allosteric candidates (MW 300-500, logP 2-4), filter with RDKit, dock with DiffDock,
rank with DeepChem, check PubChem suppliers, search USPTO patents, and optimize leads with
MedChem/molfeat.

Skills Used: AlphaFold DB, BioPython, ZINC, RDKit, DiffDock, DeepChem, PubChem, USPTO, MedChem, molfeat

---

🏥 Clinical Variant Interpretation

Goal: Analyze VCF file for hereditary cancer risk assessment

Prompt:

Use available skills you have access to whenever possible. Parse VCF with pysam, annotate variants with Ensembl VEP, query ClinVar for pathogenicity,
check COSMIC for cancer mutations, retrieve gene info from NCBI Gene, analyze protein impact
with UniProt, search PubMed for case reports, check ClinPGx for pharmacogenomics, generate
clinical report with ReportLab, and find matching trials on ClinicalTrials.gov.

Skills Used: pysam, Ensembl, ClinVar, COSMIC, NCBI Gene, UniProt, PubMed, ClinPGx, ReportLab, ClinicalTrials.gov

---

🌐 Systems Biology Network Analysis

Goal: Analyze gene regulatory networks from RNA-seq data

Prompt:

Use available skills you have access to whenever possible. Query NCBI Gene for annotations, retrieve sequences from UniProt, identify interactions via
STRING, map to Reactome/KEGG pathways, analyze topology with Torch Geometric, reconstruct
GRNs with Arboreto, assess druggability with Open Targets, model with PyMC, visualize
networks, and search GEO for similar patterns.

Skills Used: NCBI Gene, UniProt, STRING, Reactome, KEGG, Torch Geometric, Arboreto, Open Targets, PyMC, GEO

📖 Want more examples? Check out docs/examples.md for comprehensive workflow examples and detailed use cases across all scientific domains.

---

🔬 Use Cases

🧪 Drug Discovery & Medicinal Chemistry

• Virtual Screening: Screen millions of compounds from PubChem/ZINC against protein targets
• Lead Optimization: Analyze structure-activity relationships with RDKit, generate analogs with datamol
• ADMET Prediction: Predict absorption, distribution, metabolism, excretion, and toxicity with DeepChem
• Molecular Docking: Predict binding poses and affinities with DiffDock
• Bioactivity Mining: Query ChEMBL for known inhibitors and analyze SAR patterns

🧬 Bioinformatics & Genomics

• Sequence Analysis: Process DNA/RNA/protein sequences with BioPython and pysam
• Single-Cell Analysis: Analyze 10X Genomics data with Scanpy, identify cell types, infer GRNs with Arboreto
• Variant Annotation: Annotate VCF files with Ensembl VEP, query ClinVar for pathogenicity
• Gene Discovery: Query NCBI Gene, UniProt, and Ensembl for comprehensive gene information
• Network Analysis: Identify protein-protein interactions via STRING, map to pathways (KEGG, Reactome)

🏥 Clinical Research & Precision Medicine

• Clinical Trials: Search ClinicalTrials.gov for relevant studies, analyze eligibility criteria
• Variant Interpretation: Annotate variants with ClinVar, COSMIC, and ClinPGx for pharmacogenomics
• Drug Safety: Query FDA databases for adverse events, drug interactions, and recalls
• Precision Therapeutics: Match patient variants to targeted therapies and clinical trials

🔬 Multi-Omics & Systems Biology

• Multi-Omics Integration: Combine RNA-seq, proteomics, and metabolomics data
• Pathway Analysis: Enrich differentially expressed genes in KEGG/Reactome pathways
• Network Biology: Reconstruct gene regulatory networks, identify hub genes
• Biomarker Discovery: Integrate multi-omics layers to predict patient outcomes

📊 Data Analysis & Visualization

• Statistical Analysis: Perform hypothesis testing, power analysis, and experimental design
• Publication Figures: Create publication-quality visualizations with matplotlib and seaborn
• Network Visualization: Visualize biological networks with NetworkX
• Report Generation: Generate comprehensive PDF reports with ReportLab

🧪 Laboratory Automation

• Protocol Design: Create Opentrons protocols for automated liquid handling
• LIMS Integration: Integrate with Benchling and LabArchives for data management
• Workflow Automation: Automate multi-step laboratory workflows

---

📚 Available Skills

This repository contains 140 scientific skills organized across multiple domains. Each skill provides comprehensive documentation, code examples, and best practices for working with scientific libraries, databases, and tools.

Skill Categories

🧬 Bioinformatics & Genomics (16+ skills)

• Sequence analysis: BioPython, pysam, scikit-bio, BioServices
• Single-cell analysis: Scanpy, AnnData, scvi-tools, Arboreto, Cellxgene Census
• Genomic tools: gget, geniml, gtars, deepTools, FlowIO, Zarr
• Phylogenetics: ETE Toolkit

🧪 Cheminformatics & Drug Discovery (11+ skills)

• Molecular manipulation: RDKit, Datamol, Molfeat
• Deep learning: DeepChem, TorchDrug
• Docking & screening: DiffDock
• Cloud quantum chemistry: Rowan (pKa, docking, cofolding)
• Drug-likeness: MedChem
• Benchmarks: PyTDC

🔬 Proteomics & Mass Spectrometry (2 skills)

• Spectral processing: matchms, pyOpenMS

🏥 Clinical Research & Precision Medicine (12+ skills)

• Clinical databases: ClinicalTrials.gov, ClinVar, ClinPGx, COSMIC, FDA Databases
• Healthcare AI: PyHealth, NeuroKit2, Clinical Decision Support
• Clinical documentation: Clinical Reports, Treatment Plans
• Variant analysis: Ensembl, NCBI Gene

🖼️ Medical Imaging & Digital Pathology (3 skills)

• DICOM processing: pydicom
• Whole slide imaging: histolab, PathML

🧠 Neuroscience & Electrophysiology (1 skill)

• Neural recordings: Neuropixels-Analysis (extracellular spikes, silicon probes, spike sorting)

🤖 Machine Learning & AI (15+ skills)

• Deep learning: PyTorch Lightning, Transformers, Stable Baselines3, PufferLib
• Classical ML: scikit-learn, scikit-survival, SHAP
• Time series: aeon
• Bayesian methods: PyMC
• Optimization: PyMOO
• Graph ML: Torch Geometric
• Dimensionality reduction: UMAP-learn
• Statistical modeling: statsmodels

🔮 Materials Science, Chemistry & Physics (7 skills)

• Materials: Pymatgen
• Metabolic modeling: COBRApy
• Astronomy: Astropy
• Quantum computing: Cirq, PennyLane, Qiskit, QuTiP

⚙️ Engineering & Simulation (4 skills)

• Numerical computing: MATLAB/Octave
• Computational fluid dynamics: FluidSim
• Discrete-event simulation: SimPy
• Data processing: Dask, Polars, Vaex

📊 Data Analysis & Visualization (14+ skills)

• Visualization: Matplotlib, Seaborn, Plotly, Scientific Visualization
• Geospatial analysis: GeoPandas
• Network analysis: NetworkX
• Symbolic math: SymPy
• PDF generation: ReportLab
• Data access: Data Commons
• Exploratory data analysis: EDA workflows
• Statistical analysis: Statistical Analysis workflows

🧪 Laboratory Automation (3 skills)

• Liquid handling: PyLabRobot
• Protocol management: Protocols.io
• LIMS integration: Benchling, LabArchives

🔬 Multi-omics & Systems Biology (5+ skills)

• Pathway analysis: KEGG, Reactome, STRING
• Multi-omics: Denario, HypoGeniC
• Data management: LaminDB

🧬 Protein Engineering & Design (2 skills)

• Protein language models: ESM
• Cloud laboratory platform: Adaptyv (automated protein testing and validation)

📚 Scientific Communication (20+ skills)

• Literature: OpenAlex, PubMed, bioRxiv, Literature Review
• Web search: Perplexity Search (AI-powered search with real-time information)
• Writing: Scientific Writing, Peer Review
• Document processing: XLSX, MarkItDown, Document Skills
• Publishing: Paper-2-Web, Venue Templates
• Presentations: Scientific Slides, LaTeX Posters, PPTX Posters
• Diagrams: Scientific Schematics
• Citations: Citation Management
• Illustration: Generate Image (AI image generation with FLUX.2 Pro and Gemini 3 Pro (Nano Banana Pro))

🔬 Scientific Databases (28+ skills)

• Protein: UniProt, PDB, AlphaFold DB
• Chemical: PubChem, ChEMBL, DrugBank, ZINC, HMDB
• Genomic: Ensembl, NCBI Gene, GEO, ENA, GWAS Catalog
• Literature: bioRxiv (preprints)
• Clinical: ClinVar, COSMIC, ClinicalTrials.gov, ClinPGx, FDA Databases
• Pathways: KEGG, Reactome, STRING
• Targets: Open Targets
• Metabolomics: Metabolomics Workbench
• Enzymes: BRENDA
• Patents: USPTO

🔧 Infrastructure & Platforms (6+ skills)

• Cloud compute: Modal
• Genomics platforms: DNAnexus, LatchBio
• Microscopy: OMERO
• Automation: Opentrons
• Tool discovery: ToolUniverse, Get Available Resources

🎓 Research Methodology & Planning (8+ skills)

• Ideation: Scientific Brainstorming, Hypothesis Generation
• Critical analysis: Scientific Critical Thinking, Scholar Evaluation
• Funding: Research Grants
• Discovery: Research Lookup
• Market analysis: Market Research Reports

⚖️ Regulatory & Standards (1 skill)

• Medical device standards: ISO 13485 Certification

📖 For complete details on all skills, see docs/scientific-skills.md

💡 Looking for practical examples? Check out docs/examples.md for comprehensive workflow examples across all scientific domains.

---

🤝 Contributing

We welcome contributions to expand and improve this scientific skills repository!

Ways to Contribute

✨ Add New Skills

• Create skills for additional scientific packages or databases
• Add integrations for scientific platforms and tools

📚 Improve Existing Skills

• Enhance documentation with more examples and use cases
• Add new workflows and reference materials
• Improve code examples and scripts
• Fix bugs or update outdated information

🐛 Report Issues

• Submit bug reports with detailed reproduction steps
• Suggest improvements or new features

How to Contribute

1. Fork the repository 2. Create a feature branch (git checkout -b feature/amazing-skill) 3. Follow the existing directory structure and documentation patterns 4. Ensure all new skills include comprehensive SKILL.md files 5. Test your examples and workflows thoroughly 6. Commit your changes (git commit -m 'Add amazing skill') 7. Push to your branch (git push origin feature/amazing-skill) 8. Submit a pull request with a clear description of your changes

Contribution Guidelines

✅ Adhere to the [Agent Skills Specification](https://agentskills.io/specification) — Every skill must follow the official spec (valid SKILL.md frontmatter, naming conventions, directory structure) ✅ Maintain consistency with existing skill documentation format ✅ Ensure all code examples are tested and functional ✅ Follow scientific best practices in examples and workflows ✅ Update relevant documentation when adding new capabilities ✅ Provide clear comments and docstrings in code ✅ Include references to official documentation

Recognition

Contributors are recognized in our community and may be featured in:

• Repository contributors list
• Special mentions in release notes
• K-Dense community highlights

Your contributions help make scientific computing more accessible and enable researchers to leverage AI tools more effectively!

Support Open Source

This project builds on 50+ amazing open source projects. If you find value in these skills, please consider supporting the projects we depend on.

---

🔧 Troubleshooting

Common Issues

Problem: Skills not loading in Claude Code

• Solution: Ensure you've installed the latest version of Claude Code
• Verify the plugin is installed: /plugin → Manage Plugins
• Try reinstalling: /plugin uninstall scientific-skills@claude-scientific-skills then /plugin install scientific-skills@claude-scientific-skills
• Re-add the marketplace if needed: /plugin marketplace add K-Dense-AI/claude-scientific-skills

Problem: Missing Python dependencies

• Solution: Check the specific SKILL.md file for required packages
• Install dependencies: uv pip install package-name

Problem: API rate limits

• Solution: Many databases have rate limits. Review the specific database documentation
• Consider implementing caching or batch requests

Problem: Authentication errors

• Solution: Some services require API keys. Check the SKILL.md for authentication setup
• Verify your credentials and permissions

Problem: Outdated examples

• Solution: Report the issue via GitHub Issues
• Check the official package documentation for updated syntax

---

❓ FAQ

General Questions

Q: Is this free to use? A: Yes! This repository is MIT licensed. However, each individual skill has its own license specified in the license metadata field within its SKILL.md file—be sure to review and comply with those terms.

Q: Why are all skills grouped into one plugin instead of separate plugins? A: We believe good science in the age of AI is inherently interdisciplinary. Bundling all skills into a single plugin makes it trivial for you (and Claude) to bridge across fields—e.g., combining genomics, cheminformatics, clinical data, and machine learning in one workflow—without worrying about which individual skills to install or wire together.

Q: Can I use this for commercial projects? A: The repository itself is MIT licensed, which allows commercial use. However, individual skills may have different licenses—check the license field in each skill's SKILL.md file to ensure compliance with your intended use.

Q: Do all skills have the same license? A: No. Each skill has its own license specified in the license metadata field within its SKILL.md file. These licenses may differ from the repository's MIT License. Users are responsible for reviewing and adhering to the license terms of each individual skill they use.

Q: How often is this updated? A: We regularly update skills to reflect the latest versions of packages and APIs. Major updates are announced in release notes.

Q: Can I use this with other AI models? A: The skills are optimized for Claude but can be adapted for other models with MCP support. The MCP server works with any MCP-compatible client.

Installation & Setup

Q: Do I need all the Python packages installed? A: No! Only install the packages you need. Each skill specifies its requirements in its SKILL.md file.

Q: What if a skill doesn't work? A: First check the Troubleshooting section. If the issue persists, file an issue on GitHub with detailed reproduction steps.

Q: Do the skills work offline? A: Database skills require internet access to query APIs. Package skills work offline once Python dependencies are installed.

Contributing

Q: Can I contribute my own skills? A: Absolutely! We welcome contributions. See the Contributing section for guidelines and best practices.

Q: How do I report bugs or suggest features? A: Open an issue on GitHub with a clear description. For bugs, include reproduction steps and expected vs actual behavior.

---

💬 Support

Need help? Here's how to get support:

• 📖 Documentation: Check the relevant SKILL.md and references/ folders
• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Submit a feature request
• 💼 Enterprise Support: Contact K-Dense for commercial support
• 🌐 MCP Support: Visit the claude-skills-mcp repository or use our hosted MCP server

---

🎉 Join Our Community!

We'd love to have you join us! 🚀

Connect with other scientists, researchers, and AI enthusiasts using Claude for scientific computing. Share your discoveries, ask questions, get help with your projects, and collaborate with the community!

🌟 [Join our Slack Community](https://join.slack.com/t/k-densecommunity/shared_invite/zt-3iajtyls1-EwmkwIZk0g_o74311Tkf5g) 🌟

Whether you're just getting started or you're a power user, our community is here to support you. We share tips, troubleshoot issues together, showcase cool projects, and discuss the latest developments in AI-powered scientific research.

See you there! 💬

---

📖 Citation

If you use Claude Scientific Skills in your research or project, please cite it as:

BibTeX

@software{claude_scientific_skills_2025,
  author = {{K-Dense Inc.}},
  title = {Claude Scientific Skills: A Comprehensive Collection of Scientific Tools for Claude AI},
  year = {2025},
  url = {https://github.com/K-Dense-AI/claude-scientific-skills},
  note = {skills covering databases, packages, integrations, and analysis tools}
}

APA

K-Dense Inc. (2025). Claude Scientific Skills: A comprehensive collection of scientific tools for Claude AI [Computer software]. https://github.com/K-Dense-AI/claude-scientific-skills

MLA

K-Dense Inc. Claude Scientific Skills: A Comprehensive Collection of Scientific Tools for Claude AI. 2025, github.com/K-Dense-AI/claude-scientific-skills.

Plain Text

Claude Scientific Skills by K-Dense Inc. (2025)
Available at: https://github.com/K-Dense-AI/claude-scientific-skills

We appreciate acknowledgment in publications, presentations, or projects that benefit from these skills!

---

📄 License

This project is licensed under the MIT License.

Copyright © 2025 K-Dense Inc. (k-dense.ai)

Key Points:

• ✅ Free for any use (commercial and noncommercial)
• ✅ Open source - modify, distribute, and use freely
• ✅ Permissive - minimal restrictions on reuse
• ⚠️ No warranty - provided "as is" without warranty of any kind

See LICENSE.md for full terms.

Individual Skill Licenses

⚠️ Important: Each skill has its own license specified in the license metadata field within its SKILL.md file. These licenses may differ from the repository's MIT License and may include additional terms or restrictions. Users are responsible for reviewing and adhering to the license terms of each individual skill they use.

Star History


Scientific Skills Research Requirements (2026)

Verified Tech Stack

• Python: 3.9+ (3.12+ recommended)
• Package Manager: uv (recommended)
• Platform: macOS, Linux, or Windows with WSL2

Core Libraries

Cheminformatics

• RDKit: Molecular manipulation, descriptor calculation
• Datamol: Molecular data handling
• Molfeat: Molecular featurization

Bioinformatics

• BioPython: Computational biology tools
• Scanpy: Single-cell RNA-seq analysis
• AnnData: Annotated data matrices

Machine Learning

• PyTorch Lightning: Deep learning framework
• scikit-learn: Machine learning library
• Transformers: NLP and deep learning models

Data Analysis

• Pandas/Polars/Vaex: Data manipulation
• Matplotlib/Seaborn/Plotly: Visualization
• Statsmodels: Statistical modeling

Database APIs

• PubMed: Literature search via Entrez
• ChEMBL: Bioactivity queries via REST API
• UniProt: Protein data via REST API
• PDB: Structure data via RCSB API

Source References

• RDKit Documentation
• Scanpy Documentation
• BioPython Tutorial
• K-Dense AI GitHub

scientific-skills Rules

Purpose

Comprehensive scientific research toolkit with 139 specialized skills for biology, chemistry, medicine, data science, and computational research.

Best Practices

• Always query scientific databases (PubMed, ChEMBL, UniProt) before performing any analysis
• Document all steps: data sources, parameters, library versions, transformations
• Chain multiple domain-specific skills for complex workflows
• Report findings with statistical validation
• Visualize intermediate results after each major processing step

Integration Points

• Scientific databases: PubMed, ChEMBL, UniProt, PDB, DrugBank
• Python libraries: RDKit, Scanpy, BioPython, PyTorch Lightning
• Workflow patterns: Literature review, Drug discovery, Single-cell analysis

Iron Laws

1. ALWAYS query databases first 2. NEVER skip documentation 3. ALWAYS chain skills for multi-domain work 4. NEVER report without statistical validation 5. ALWAYS visualize intermediate results

See SKILL.md for complete documentation.

/adaptyv

Run scientific-skills/skills/adaptyv with TDD checkpoints and ecosystem validation.

Adaptyv API Reference

Base URL

https://kq5jp7qj7wdqklhsxmovkzn4l40obksv.lambda-url.eu-central-1.on.aws

Authentication

All API requests require bearer token authentication in the request header:

Authorization: Bearer YOUR_API_KEY

To obtain API access:

1. Contact support@adaptyvbio.com 2. Request API access during alpha/beta period 3. Receive your personal access token

Store your API key securely:

• Use environment variables: ADAPTYV_API_KEY
• Never commit API keys to version control
• Use .env files with .gitignore for local development

Endpoints

Experiments

Create Experiment

Submit protein sequences for experimental testing.

Endpoint: POST /experiments

Request Body:

{
  "sequences": ">protein1\nMKVLWALLGLLGAA...\n>protein2\nMATGVLWALLG...",
  "experiment_type": "binding|expression|thermostability|enzyme_activity",
  "target_id": "optional_target_identifier",
  "webhook_url": "https://your-webhook.com/callback",
  "metadata": {
    "project": "optional_project_name",
    "notes": "optional_notes"
  }
}

Sequence Format:

• FASTA format with headers
• Multiple sequences supported
• Standard amino acid codes

Response:

{
  "experiment_id": "exp_abc123xyz",
  "status": "submitted",
  "created_at": "2025-11-24T10:00:00Z",
  "estimated_completion": "2025-12-15T10:00:00Z"
}

Get Experiment Status

Check the current status of an experiment.

Endpoint: GET /experiments/{experiment_id}

Response:

{
  "experiment_id": "exp_abc123xyz",
  "status": "submitted|processing|completed|failed",
  "created_at": "2025-11-24T10:00:00Z",
  "updated_at": "2025-11-25T14:30:00Z",
  "progress": {
    "stage": "sequencing|expression|assay|analysis",
    "percentage": 45
  }
}

Status Values:

• submitted - Experiment received and queued
• processing - Active testing in progress
• completed - Results available for download
• failed - Experiment encountered an error

List Experiments

Retrieve all experiments for your organization.

Endpoint: GET /experiments

Query Parameters:

• status - Filter by status (optional)
• limit - Number of results per page (default: 50)
• offset - Pagination offset (default: 0)

Response:

{
  "experiments": [
    {
      "experiment_id": "exp_abc123xyz",
      "status": "completed",
      "experiment_type": "binding",
      "created_at": "2025-11-24T10:00:00Z"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Results

Get Experiment Results

Download results from a completed experiment.

Endpoint: GET /experiments/{experiment_id}/results

Response:

{
  "experiment_id": "exp_abc123xyz",
  "results": [
    {
      "sequence_id": "protein1",
      "measurements": {
        "kd": 1.2e-9,
        "kon": 1.5e5,
        "koff": 1.8e-4
      },
      "quality_metrics": {
        "confidence": "high",
        "r_squared": 0.98
      }
    }
  ],
  "download_urls": {
    "raw_data": "https://...",
    "analysis_package": "https://...",
    "report": "https://..."
  }
}

Targets

Search Target Catalog

Search the ACROBiosystems antigen catalog.

Endpoint: GET /targets

Query Parameters:

• search - Search term (protein name, UniProt ID, etc.)
• species - Filter by species
• category - Filter by category

Response:

{
  "targets": [
    {
      "target_id": "tgt_12345",
      "name": "Human PD-L1",
      "species": "Homo sapiens",
      "uniprot_id": "Q9NZQ7",
      "availability": "in_stock|custom_order",
      "price_usd": 450
    }
  ]
}

Request Custom Target

Request an antigen not in the standard catalog.

Endpoint: POST /targets/request

Request Body:

{
  "target_name": "Custom target name",
  "uniprot_id": "optional_uniprot_id",
  "species": "species_name",
  "notes": "Additional requirements"
}

Organization

Get Credits Balance

Check your organization's credit balance and usage.

Endpoint: GET /organization/credits

Response:

{
  "balance": 10000,
  "currency": "USD",
  "usage_this_month": 2500,
  "experiments_remaining": 22
}

Webhooks

Configure webhook URLs to receive notifications when experiments complete.

Webhook Payload:

{
  "event": "experiment.completed",
  "experiment_id": "exp_abc123xyz",
  "status": "completed",
  "timestamp": "2025-12-15T10:00:00Z",
  "results_url": "/experiments/exp_abc123xyz/results"
}

Webhook Events:

• experiment.submitted - Experiment received
• experiment.started - Processing began
• experiment.completed - Results available
• experiment.failed - Error occurred

Security:

• Verify webhook signatures (details provided during onboarding)
• Use HTTPS endpoints only
• Respond with 200 OK to acknowledge receipt

Error Handling

Error Response Format:

{
  "error": {
    "code": "invalid_sequence",
    "message": "Sequence contains invalid amino acid codes",
    "details": {
      "sequence_id": "protein1",
      "position": 45,
      "character": "X"
    }
  }
}

Common Error Codes:

• authentication_failed - Invalid or missing API key
• invalid_sequence - Malformed FASTA or invalid amino acids
• insufficient_credits - Not enough credits for experiment
• target_not_found - Specified target ID doesn't exist
• rate_limit_exceeded - Too many requests
• experiment_not_found - Invalid experiment ID
• internal_error - Server-side error

Rate Limits

• 100 requests per minute per API key
• 1000 experiments per day per organization
• Batch submissions encouraged for large-scale testing

When rate limited, response includes:

HTTP 429 Too Many Requests
Retry-After: 60

Best Practices

1. Use webhooks for long-running experiments instead of polling 2. Batch sequences when submitting multiple variants 3. Cache results to avoid redundant API calls 4. Implement retry logic with exponential backoff 5. Monitor credits to avoid experiment failures 6. Validate sequences locally before submission 7. Use descriptive metadata for better experiment tracking

API Versioning

The API is currently in alpha/beta. Breaking changes may occur but will be:

• Announced via email to registered users
• Documented in the changelog
• Supported with migration guides

Current version is reflected in response headers:

X-API-Version: alpha-2025-11

Support

For API issues or questions:

• Email: support@adaptyvbio.com
• Documentation updates: https://docs.adaptyvbio.com
• Report bugs with experiment IDs and request details

Code Examples

Setup and Authentication

Basic Setup

import os
import requests
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Configuration
API_KEY = os.getenv("ADAPTYV_API_KEY")
BASE_URL = "https://kq5jp7qj7wdqklhsxmovkzn4l40obksv.lambda-url.eu-central-1.on.aws"

# Standard headers
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def check_api_connection():
    """Verify API connection and credentials"""
    try:
        response = requests.get(f"{BASE_URL}/organization/credits", headers=HEADERS)
        response.raise_for_status()
        print("✓ API connection successful")
        print(f"  Credits remaining: {response.json()['balance']}")
        return True
    except requests.exceptions.HTTPError as e:
        print(f"✗ API authentication failed: {e}")
        return False

Environment Setup

Create a .env file:

ADAPTYV_API_KEY=your_api_key_here

Install dependencies:

uv pip install requests python-dotenv

Experiment Submission

Submit Single Sequence

def submit_single_experiment(sequence, experiment_type="binding", target_id=None):
    """
    Submit a single protein sequence for testing

    Args:
        sequence: Amino acid sequence string
        experiment_type: Type of experiment (binding, expression, thermostability, enzyme_activity)
        target_id: Optional target identifier for binding assays

    Returns:
        Experiment ID and status
    """

    # Format as FASTA
    fasta_content = f">protein_sequence\n{sequence}\n"

    payload = {
        "sequences": fasta_content,
        "experiment_type": experiment_type
    }

    if target_id:
        payload["target_id"] = target_id

    response = requests.post(
        f"{BASE_URL}/experiments",
        headers=HEADERS,
        json=payload
    )

    response.raise_for_status()
    result = response.json()

    print(f"✓ Experiment submitted")
    print(f"  Experiment ID: {result['experiment_id']}")
    print(f"  Status: {result['status']}")
    print(f"  Estimated completion: {result['estimated_completion']}")

    return result

# Example usage
sequence = "MKVLWAALLGLLGAAAAFPAVTSAVKPYKAAVSAAVSKPYKAAVSAAVSKPYK"
experiment = submit_single_experiment(sequence, experiment_type="expression")

Submit Multiple Sequences (Batch)

def submit_batch_experiment(sequences_dict, experiment_type="binding", metadata=None):
    """
    Submit multiple protein sequences in a single batch

    Args:
        sequences_dict: Dictionary of {name: sequence}
        experiment_type: Type of experiment
        metadata: Optional dictionary of additional information

    Returns:
        Experiment details
    """

    # Format all sequences as FASTA
    fasta_content = ""
    for name, sequence in sequences_dict.items():
        fasta_content += f">{name}\n{sequence}\n"

    payload = {
        "sequences": fasta_content,
        "experiment_type": experiment_type
    }

    if metadata:
        payload["metadata"] = metadata

    response = requests.post(
        f"{BASE_URL}/experiments",
        headers=HEADERS,
        json=payload
    )

    response.raise_for_status()
    result = response.json()

    print(f"✓ Batch experiment submitted")
    print(f"  Experiment ID: {result['experiment_id']}")
    print(f"  Sequences: {len(sequences_dict)}")
    print(f"  Status: {result['status']}")

    return result

# Example usage
sequences = {
    "variant_1": "MKVLWAALLGLLGAAA...",
    "variant_2": "MKVLSAALLGLLGAAA...",
    "variant_3": "MKVLAAALLGLLGAAA...",
    "wildtype": "MKVLWAALLGLLGAAA..."
}

metadata = {
    "project": "antibody_optimization",
    "round": 3,
    "notes": "Testing solubility-optimized variants"
}

experiment = submit_batch_experiment(sequences, "expression", metadata)

Submit with Webhook Notification

def submit_with_webhook(sequences_dict, experiment_type, webhook_url):
    """
    Submit experiment with webhook for completion notification

    Args:
        sequences_dict: Dictionary of {name: sequence}
        experiment_type: Type of experiment
        webhook_url: URL to receive notification when complete
    """

    fasta_content = ""
    for name, sequence in sequences_dict.items():
        fasta_content += f">{name}\n{sequence}\n"

    payload = {
        "sequences": fasta_content,
        "experiment_type": experiment_type,
        "webhook_url": webhook_url
    }

    response = requests.post(
        f"{BASE_URL}/experiments",
        headers=HEADERS,
        json=payload
    )

    response.raise_for_status()
    result = response.json()

    print(f"✓ Experiment submitted with webhook")
    print(f"  Experiment ID: {result['experiment_id']}")
    print(f"  Webhook: {webhook_url}")

    return result

# Example
webhook_url = "https://your-server.com/adaptyv-webhook"
experiment = submit_with_webhook(sequences, "binding", webhook_url)

Tracking Experiments

Check Experiment Status

def check_experiment_status(experiment_id):
    """
    Get current status of an experiment

    Args:
        experiment_id: Experiment identifier

    Returns:
        Status information
    """

    response = requests.get(
        f"{BASE_URL}/experiments/{experiment_id}",
        headers=HEADERS
    )

    response.raise_for_status()
    status = response.json()

    print(f"Experiment: {experiment_id}")
    print(f"  Status: {status['status']}")
    print(f"  Created: {status['created_at']}")
    print(f"  Updated: {status['updated_at']}")

    if 'progress' in status:
        print(f"  Progress: {status['progress']['percentage']}%")
        print(f"  Current stage: {status['progress']['stage']}")

    return status

# Example
status = check_experiment_status("exp_abc123xyz")

List All Experiments

def list_experiments(status_filter=None, limit=50):
    """
    List experiments with optional status filtering

    Args:
        status_filter: Filter by status (submitted, processing, completed, failed)
        limit: Maximum number of results

    Returns:
        List of experiments
    """

    params = {"limit": limit}
    if status_filter:
        params["status"] = status_filter

    response = requests.get(
        f"{BASE_URL}/experiments",
        headers=HEADERS,
        params=params
    )

    response.raise_for_status()
    result = response.json()

    print(f"Found {result['total']} experiments")
    for exp in result['experiments']:
        print(f"  {exp['experiment_id']}: {exp['status']} ({exp['experiment_type']})")

    return result['experiments']

# Example - list all completed experiments
completed_experiments = list_experiments(status_filter="completed")

Poll Until Complete

import time

def wait_for_completion(experiment_id, check_interval=3600):
    """
    Poll experiment status until completion

    Args:
        experiment_id: Experiment identifier
        check_interval: Seconds between status checks (default: 1 hour)

    Returns:
        Final status
    """

    print(f"Monitoring experiment {experiment_id}...")

    while True:
        status = check_experiment_status(experiment_id)

        if status['status'] == 'completed':
            print("✓ Experiment completed!")
            return status
        elif status['status'] == 'failed':
            print("✗ Experiment failed")
            return status

        print(f"  Status: {status['status']} - checking again in {check_interval}s")
        time.sleep(check_interval)

# Example (not recommended - use webhooks instead!)
# status = wait_for_completion("exp_abc123xyz", check_interval=3600)

Retrieving Results

Download Experiment Results

import json

def download_results(experiment_id, output_dir="results"):
    """
    Download and parse experiment results

    Args:
        experiment_id: Experiment identifier
        output_dir: Directory to save results

    Returns:
        Parsed results data
    """

    # Get results
    response = requests.get(
        f"{BASE_URL}/experiments/{experiment_id}/results",
        headers=HEADERS
    )

    response.raise_for_status()
    results = response.json()

    # Save results JSON
    os.makedirs(output_dir, exist_ok=True)
    output_file = f"{output_dir}/{experiment_id}_results.json"

    with open(output_file, 'w') as f:
        json.dump(results, f, indent=2)

    print(f"✓ Results downloaded: {output_file}")
    print(f"  Sequences tested: {len(results['results'])}")

    # Download raw data if available
    if 'download_urls' in results:
        for data_type, url in results['download_urls'].items():
            print(f"  {data_type} available at: {url}")

    return results

# Example
results = download_results("exp_abc123xyz")

Parse Binding Results

import pandas as pd

def parse_binding_results(results):
    """
    Parse binding assay results into DataFrame

    Args:
        results: Results dictionary from API

    Returns:
        pandas DataFrame with organized results
    """

    data = []
    for result in results['results']:
        row = {
            'sequence_id': result['sequence_id'],
            'kd': result['measurements']['kd'],
            'kd_error': result['measurements']['kd_error'],
            'kon': result['measurements']['kon'],
            'koff': result['measurements']['koff'],
            'confidence': result['quality_metrics']['confidence'],
            'r_squared': result['quality_metrics']['r_squared']
        }
        data.append(row)

    df = pd.DataFrame(data)

    # Sort by affinity (lower KD = stronger binding)
    df = df.sort_values('kd')

    print("Top 5 binders:")
    print(df.head())

    return df

# Example
experiment_id = "exp_abc123xyz"
results = download_results(experiment_id)
binding_df = parse_binding_results(results)

# Export to CSV
binding_df.to_csv(f"{experiment_id}_binding_results.csv", index=False)

Parse Expression Results

def parse_expression_results(results):
    """
    Parse expression testing results into DataFrame

    Args:
        results: Results dictionary from API

    Returns:
        pandas DataFrame with organized results
    """

    data = []
    for result in results['results']:
        row = {
            'sequence_id': result['sequence_id'],
            'yield_mg_per_l': result['measurements']['total_yield_mg_per_l'],
            'soluble_fraction': result['measurements']['soluble_fraction_percent'],
            'purity': result['measurements']['purity_percent'],
            'percentile': result['ranking']['percentile']
        }
        data.append(row)

    df = pd.DataFrame(data)

    # Sort by yield
    df = df.sort_values('yield_mg_per_l', ascending=False)

    print(f"Mean yield: {df['yield_mg_per_l'].mean():.2f} mg/L")
    print(f"Top performer: {df.iloc[0]['sequence_id']} ({df.iloc[0]['yield_mg_per_l']:.2f} mg/L)")

    return df

# Example
results = download_results("exp_expression123")
expression_df = parse_expression_results(results)

Target Catalog

Search for Targets

def search_targets(query, species=None, category=None):
    """
    Search the antigen catalog

    Args:
        query: Search term (protein name, UniProt ID, etc.)
        species: Optional species filter
        category: Optional category filter

    Returns:
        List of matching targets
    """

    params = {"search": query}
    if species:
        params["species"] = species
    if category:
        params["category"] = category

    response = requests.get(
        f"{BASE_URL}/targets",
        headers=HEADERS,
        params=params
    )

    response.raise_for_status()
    targets = response.json()['targets']

    print(f"Found {len(targets)} targets matching '{query}':")
    for target in targets:
        print(f"  {target['target_id']}: {target['name']}")
        print(f"    Species: {target['species']}")
        print(f"    Availability: {target['availability']}")
        print(f"    Price: ${target['price_usd']}")

    return targets

# Example
targets = search_targets("PD-L1", species="Homo sapiens")

Request Custom Target

def request_custom_target(target_name, uniprot_id=None, species=None, notes=None):
    """
    Request a custom antigen not in the standard catalog

    Args:
        target_name: Name of the target protein
        uniprot_id: Optional UniProt identifier
        species: Species name
        notes: Additional requirements or notes

    Returns:
        Request confirmation
    """

    payload = {
        "target_name": target_name,
        "species": species
    }

    if uniprot_id:
        payload["uniprot_id"] = uniprot_id
    if notes:
        payload["notes"] = notes

    response = requests.post(
        f"{BASE_URL}/targets/request",
        headers=HEADERS,
        json=payload
    )

    response.raise_for_status()
    result = response.json()

    print(f"✓ Custom target request submitted")
    print(f"  Request ID: {result['request_id']}")
    print(f"  Status: {result['status']}")

    return result

# Example
request = request_custom_target(
    target_name="Novel receptor XYZ",
    uniprot_id="P12345",
    species="Mus musculus",
    notes="Need high purity for structural studies"
)

Complete Workflows

End-to-End Binding Assay

def complete_binding_workflow(sequences_dict, target_id, project_name):
    """
    Complete workflow: submit sequences, track, and retrieve binding results

    Args:
        sequences_dict: Dictionary of {name: sequence}
        target_id: Target identifier from catalog
        project_name: Project name for metadata

    Returns:
        DataFrame with binding results
    """

    print("=== Starting Binding Assay Workflow ===")

    # Step 1: Submit experiment
    print("\n1. Submitting experiment...")
    metadata = {
        "project": project_name,
        "target": target_id
    }

    experiment = submit_batch_experiment(
        sequences_dict,
        experiment_type="binding",
        metadata=metadata
    )

    experiment_id = experiment['experiment_id']

    # Step 2: Save experiment info
    print("\n2. Saving experiment details...")
    with open(f"{experiment_id}_info.json", 'w') as f:
        json.dump(experiment, f, indent=2)

    print(f"✓ Experiment {experiment_id} submitted")
    print("  Results will be available in ~21 days")
    print("  Use webhook or poll status for updates")

    # Note: In practice, wait for completion before this step
    # print("\n3. Waiting for completion...")
    # status = wait_for_completion(experiment_id)

    # print("\n4. Downloading results...")
    # results = download_results(experiment_id)

    # print("\n5. Parsing results...")
    # df = parse_binding_results(results)

    # return df

    return experiment_id

# Example
antibody_variants = {
    "variant_1": "EVQLVESGGGLVQPGG...",
    "variant_2": "EVQLVESGGGLVQPGS...",
    "variant_3": "EVQLVESGGGLVQPGA...",
    "wildtype": "EVQLVESGGGLVQPGG..."
}

experiment_id = complete_binding_workflow(
    antibody_variants,
    target_id="tgt_pdl1_human",
    project_name="antibody_affinity_maturation"
)

Optimization + Testing Pipeline

# Combine computational optimization with experimental testing

def optimization_and_testing_pipeline(initial_sequences, experiment_type="expression"):
    """
    Complete pipeline: optimize sequences computationally, then submit for testing

    Args:
        initial_sequences: Dictionary of {name: sequence}
        experiment_type: Type of experiment

    Returns:
        Experiment ID for tracking
    """

    print("=== Optimization and Testing Pipeline ===")

    # Step 1: Computational optimization
    print("\n1. Computational optimization...")
    from protein_optimization import complete_optimization_pipeline

    optimized = complete_optimization_pipeline(initial_sequences)

    print(f"✓ Optimization complete")
    print(f"  Started with: {len(initial_sequences)} sequences")
    print(f"  Optimized to: {len(optimized)} sequences")

    # Step 2: Select top candidates
    print("\n2. Selecting top candidates for testing...")
    top_candidates = optimized[:50]  # Top 50

    sequences_to_test = {
        seq_data['name']: seq_data['sequence']
        for seq_data in top_candidates
    }

    # Step 3: Submit for experimental validation
    print("\n3. Submitting to Adaptyv...")
    metadata = {
        "optimization_method": "computational_pipeline",
        "initial_library_size": len(initial_sequences),
        "computational_scores": [s['combined'] for s in top_candidates]
    }

    experiment = submit_batch_experiment(
        sequences_to_test,
        experiment_type=experiment_type,
        metadata=metadata
    )

    print(f"✓ Pipeline complete")
    print(f"  Experiment ID: {experiment['experiment_id']}")

    return experiment['experiment_id']

# Example
initial_library = {
    f"variant_{i}": generate_random_sequence()
    for i in range(1000)
}

experiment_id = optimization_and_testing_pipeline(
    initial_library,
    experiment_type="expression"
)

Batch Result Analysis

def analyze_multiple_experiments(experiment_ids):
    """
    Download and analyze results from multiple experiments

    Args:
        experiment_ids: List of experiment identifiers

    Returns:
        Combined DataFrame with all results
    """

    all_results = []

    for exp_id in experiment_ids:
        print(f"Processing {exp_id}...")

        # Download results
        results = download_results(exp_id, output_dir=f"results/{exp_id}")

        # Parse based on experiment type
        exp_type = results.get('experiment_type', 'unknown')

        if exp_type == 'binding':
            df = parse_binding_results(results)
            df['experiment_id'] = exp_id
            all_results.append(df)

        elif exp_type == 'expression':
            df = parse_expression_results(results)
            df['experiment_id'] = exp_id
            all_results.append(df)

    # Combine all results
    combined_df = pd.concat(all_results, ignore_index=True)

    print(f"\n✓ Analysis complete")
    print(f"  Total experiments: {len(experiment_ids)}")
    print(f"  Total sequences: {len(combined_df)}")

    return combined_df

# Example
experiment_ids = [
    "exp_round1_abc",
    "exp_round2_def",
    "exp_round3_ghi"
]

all_data = analyze_multiple_experiments(experiment_ids)
all_data.to_csv("combined_results.csv", index=False)

Error Handling

Robust API Wrapper

import time
from requests.exceptions import RequestException, HTTPError

def api_request_with_retry(method, url, max_retries=3, backoff_factor=2, **kwargs):
    """
    Make API request with retry logic and error handling

    Args:
        method: HTTP method (GET, POST, etc.)
        url: Request URL
        max_retries: Maximum number of retry attempts
        backoff_factor: Exponential backoff multiplier
        **kwargs: Additional arguments for requests

    Returns:
        Response object

    Raises:
        RequestException: If all retries fail
    """

    for attempt in range(max_retries):
        try:
            response = requests.request(method, url, **kwargs)
            response.raise_for_status()
            return response

        except HTTPError as e:
            if e.response.status_code == 429:  # Rate limit
                wait_time = backoff_factor ** attempt
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
                continue

            elif e.response.status_code >= 500:  # Server error
                if attempt < max_retries - 1:
                    wait_time = backoff_factor ** attempt
                    print(f"Server error. Retrying in {wait_time}s...")
                    time.sleep(wait_time)
                    continue
                else:
                    raise

            else:  # Client error (4xx) - don't retry
                error_data = e.response.json() if e.response.content else {}
                print(f"API Error: {error_data.get('error', {}).get('message', str(e))}")
                raise

        except RequestException as e:
            if attempt < max_retries - 1:
                wait_time = backoff_factor ** attempt
                print(f"Request failed. Retrying in {wait_time}s...")
                time.sleep(wait_time)
                continue
            else:
                raise

    raise RequestException(f"Failed after {max_retries} attempts")

# Example usage
response = api_request_with_retry(
    "POST",
    f"{BASE_URL}/experiments",
    headers=HEADERS,
    json={"sequences": fasta_content, "experiment_type": "binding"}
)

Utility Functions

Validate FASTA Format

def validate_fasta(fasta_string):
    """
    Validate FASTA format and sequences

    Args:
        fasta_string: FASTA-formatted string

    Returns:
        Tuple of (is_valid, error_message)
    """

    lines = fasta_string.strip().split('\n')

    if not lines:
        return False, "Empty FASTA content"

    if not lines[0].startswith('>'):
        return False, "FASTA must start with header line (>)"

    valid_amino_acids = set("ACDEFGHIKLMNPQRSTVWY")
    current_header = None

    for i, line in enumerate(lines):
        if line.startswith('>'):
            if not line[1:].strip():
                return False, f"Line {i+1}: Empty header"
            current_header = line[1:].strip()

        else:
            if current_header is None:
                return False, f"Line {i+1}: Sequence before header"

            sequence = line.strip().upper()
            invalid = set(sequence) - valid_amino_acids

            if invalid:
                return False, f"Line {i+1}: Invalid amino acids: {invalid}"

    return True, None

# Example
fasta = ">protein1\nMKVLWAALLG\n>protein2\nMATGVLWALG"
is_valid, error = validate_fasta(fasta)

if is_valid:
    print("✓ FASTA format valid")
else:
    print(f"✗ FASTA validation failed: {error}")

Format Sequences to FASTA

def sequences_to_fasta(sequences_dict):
    """
    Convert dictionary of sequences to FASTA format

    Args:
        sequences_dict: Dictionary of {name: sequence}

    Returns:
        FASTA-formatted string
    """

    fasta_content = ""
    for name, sequence in sequences_dict.items():
        # Clean sequence (remove whitespace, ensure uppercase)
        clean_seq = ''.join(sequence.split()).upper()

        # Validate
        is_valid, error = validate_fasta(f">{name}\n{clean_seq}")
        if not is_valid:
            raise ValueError(f"Invalid sequence '{name}': {error}")

        fasta_content += f">{name}\n{clean_seq}\n"

    return fasta_content

# Example
sequences = {
    "var1": "MKVLWAALLG",
    "var2": "MATGVLWALG"
}

fasta = sequences_to_fasta(sequences)
print(fasta)

Experiment Types and Workflows

Overview

Adaptyv provides multiple experimental assay types for comprehensive protein characterization. Each experiment type has specific applications, workflows, and data outputs.

Binding Assays

Description

Measure protein-target interactions using biolayer interferometry (BLI), a label-free technique that monitors biomolecular binding in real-time.

Use Cases

• Antibody-antigen binding characterization
• Receptor-ligand interaction analysis
• Protein-protein interaction studies
• Affinity maturation screening
• Epitope binning experiments

Technology: Biolayer Interferometry (BLI)

BLI measures the interference pattern of reflected light from two surfaces:

• Reference layer - Biosensor tip surface
• Biological layer - Accumulated bound molecules

As molecules bind, the optical thickness increases, causing a wavelength shift proportional to binding.

Advantages:

• Label-free detection
• Real-time kinetics
• High-throughput compatible
• Works in crude samples
• Minimal sample consumption

Measured Parameters

Kinetic constants:

• KD - Equilibrium dissociation constant (binding affinity)
• kon - Association rate constant (binding speed)
• koff - Dissociation rate constant (unbinding speed)

Typical ranges:

• Strong binders: KD < 1 nM
• Moderate binders: KD = 1-100 nM
• Weak binders: KD > 100 nM

Workflow

1. Sequence submission - Provide protein sequences in FASTA format 2. Expression - Proteins expressed in appropriate host system 3. Purification - Automated purification protocols 4. BLI assay - Real-time binding measurements against specified targets 5. Analysis - Kinetic curve fitting and quality assessment 6. Results delivery - Binding parameters with confidence metrics

Sample Requirements

• Protein sequence (standard amino acid codes)
• Target specification (from catalog or custom request)
• Buffer conditions (standard or custom)
• Expected concentration range (optional, improves assay design)

Results Format

{
  "sequence_id": "antibody_variant_1",
  "target": "Human PD-L1",
  "measurements": {
    "kd": 2.5e-9,
    "kd_error": 0.3e-9,
    "kon": 1.8e5,
    "kon_error": 0.2e5,
    "koff": 4.5e-4,
    "koff_error": 0.5e-4
  },
  "quality_metrics": {
    "confidence": "high|medium|low",
    "r_squared": 0.97,
    "chi_squared": 0.02,
    "flags": []
  },
  "raw_data_url": "https://..."
}

Expression Testing

Description

Quantify protein expression levels in various host systems to assess producibility and optimize sequences for manufacturing.

Use Cases

• Screening variants for high expression
• Optimizing codon usage
• Identifying expression bottlenecks
• Selecting candidates for scale-up
• Comparing expression systems

Host Systems

Available expression platforms:

• E. coli - Rapid, cost-effective, prokaryotic system
• Mammalian cells - Native post-translational modifications
• Yeast - Eukaryotic system with simpler growth requirements
• Insect cells - Alternative eukaryotic platform

Measured Parameters

• Total protein yield (mg/L culture)
• Soluble fraction (percentage)
• Purity (after initial purification)
• Expression time course (optional)

Workflow

1. Sequence submission - Provide protein sequences 2. Construct generation - Cloning into expression vectors 3. Expression - Culture in specified host system 4. Quantification - Protein measurement via multiple methods 5. Analysis - Expression level comparison and ranking 6. Results delivery - Yield data and recommendations

Results Format

{
  "sequence_id": "variant_1",
  "host_system": "E. coli",
  "measurements": {
    "total_yield_mg_per_l": 25.5,
    "soluble_fraction_percent": 78,
    "purity_percent": 92
  },
  "ranking": {
    "percentile": 85,
    "notes": "High expression, good solubility"
  }
}

Thermostability Testing

Description

Measure protein thermal stability to assess structural integrity, predict shelf-life, and identify stabilizing mutations.

Use Cases

• Selecting thermally stable variants
• Formulation development
• Shelf-life prediction
• Stability-driven protein engineering
• Quality control screening

Measurement Techniques

Differential Scanning Fluorimetry (DSF):

• Monitors protein unfolding via fluorescent dye binding
• Determines melting temperature (Tm)
• High-throughput capable

Circular Dichroism (CD):

• Secondary structure analysis
• Thermal unfolding curves
• Reversibility assessment

Measured Parameters

• Tm - Melting temperature (midpoint of unfolding)
• ΔH - Enthalpy of unfolding
• Aggregation temperature (Tagg)
• Reversibility - Refolding after heating

Workflow

1. Sequence submission - Provide protein sequences 2. Expression and purification - Standard protocols 3. Thermostability assay - Temperature gradient analysis 4. Data analysis - Curve fitting and parameter extraction 5. Results delivery - Stability metrics with ranking

Results Format

{
  "sequence_id": "variant_1",
  "measurements": {
    "tm_celsius": 68.5,
    "tm_error": 0.5,
    "tagg_celsius": 72.0,
    "reversibility_percent": 85
  },
  "quality_metrics": {
    "curve_quality": "excellent",
    "cooperativity": "two-state"
  }
}

Enzyme Activity Assays

Description

Measure enzymatic function including substrate turnover, catalytic efficiency, and inhibitor sensitivity.

Use Cases

• Screening enzyme variants for improved activity
• Substrate specificity profiling
• Inhibitor testing
• pH and temperature optimization
• Mechanistic studies

Assay Types

Continuous assays:

• Chromogenic substrates
• Fluorogenic substrates
• Real-time monitoring

Endpoint assays:

• HPLC quantification
• Mass spectrometry
• Colorimetric detection

Measured Parameters

Kinetic parameters:

• kcat - Turnover number (catalytic rate constant)
• KM - Michaelis constant (substrate affinity)
• kcat/KM - Catalytic efficiency
• IC50 - Inhibitor concentration for 50% inhibition

Activity metrics:

• Specific activity (units/mg protein)
• Relative activity vs. reference
• Substrate specificity profile

Workflow

1. Sequence submission - Provide enzyme sequences 2. Expression and purification - Optimized for activity retention 3. Activity assay - Substrate turnover measurements 4. Kinetic analysis - Michaelis-Menten fitting 5. Results delivery - Kinetic parameters and rankings

Results Format

{
  "sequence_id": "enzyme_variant_1",
  "substrate": "substrate_name",
  "measurements": {
    "kcat_per_second": 125,
    "km_micromolar": 45,
    "kcat_km": 2.8,
    "specific_activity": 180
  },
  "quality_metrics": {
    "confidence": "high",
    "r_squared": 0.99
  },
  "ranking": {
    "relative_activity": 1.8,
    "improvement_vs_wildtype": "80%"
  }
}

Experiment Design Best Practices

Sequence Submission

1. Use clear identifiers - Name sequences descriptively 2. Include controls - Submit wild-type or reference sequences 3. Batch similar variants - Group related sequences in single submission 4. Validate sequences - Check for errors before submission

Sample Size

• Pilot studies - 5-10 sequences to test feasibility
• Library screening - 50-500 sequences for variant exploration
• Focused optimization - 10-50 sequences for fine-tuning
• Large-scale campaigns - 500+ sequences for ML-driven design

Quality Control

Adaptyv includes automated QC steps:

• Expression verification before assay
• Replicate measurements for reliability
• Positive/negative controls in each batch
• Statistical validation of results

Timeline Expectations

Standard turnaround: ~21 days from submission to results

Timeline breakdown:

• Construct generation: 3-5 days
• Expression: 5-7 days
• Purification: 2-3 days
• Assay execution: 3-5 days
• Analysis and QC: 2-3 days

Factors affecting timeline:

• Custom targets (add 1-2 weeks)
• Novel assay development (add 2-4 weeks)
• Large batch sizes (may add 1 week)

Cost Optimization

1. Batch submissions - Lower per-sequence cost 2. Standard targets - Catalog antigens are faster/cheaper 3. Standard conditions - Custom buffers add cost 4. Computational pre-filtering - Submit only promising candidates

Combining Experiment Types

For comprehensive protein characterization, combine multiple assays:

Therapeutic antibody development:

1. Binding assay → Identify high-affinity binders 2. Expression testing → Select manufacturable candidates 3. Thermostability → Ensure formulation stability

Enzyme engineering:

1. Activity assay → Screen for improved catalysis 2. Expression testing → Ensure producibility 3. Thermostability → Validate industrial robustness

Sequential vs. Parallel:

• Sequential - Use results from early assays to filter candidates
• Parallel - Run all assays simultaneously for faster results

Data Integration

Results integrate with computational workflows:

1. Download raw data via API 2. Parse results into standardized format 3. Feed into ML models for next-round design 4. Track experiments with metadata tags 5. Visualize trends across design iterations

Support and Troubleshooting

Common issues:

• Low expression → Consider sequence optimization (see protein_optimization.md)
• Poor binding → Verify target specification and expected range
• Variable results → Check sequence quality and controls
• Incomplete data → Contact support with experiment ID

Getting help:

• Email: support@adaptyvbio.com
• Include experiment ID and specific question
• Provide context (design goals, expected results)
• Response time: <24 hours for active experiments

Protein Sequence Optimization

Overview

Before submitting protein sequences for experimental testing, use computational tools to optimize sequences for improved expression, solubility, and stability. This pre-screening reduces experimental costs and increases success rates.

Common Protein Expression Problems

1. Unpaired Cysteines

Problem:

• Unpaired cysteines form unwanted disulfide bonds
• Leads to aggregation and misfolding
• Reduces expression yield and stability

Solution:

• Remove unpaired cysteines unless functionally necessary
• Pair cysteines appropriately for structural disulfides
• Replace with serine or alanine in non-critical positions

Example:

# Check for cysteine pairs
from Bio.Seq import Seq

def check_cysteines(sequence):
    cys_count = sequence.count('C')
    if cys_count % 2 != 0:
        print(f"Warning: Odd number of cysteines ({cys_count})")
    return cys_count

2. Excessive Hydrophobicity

Problem:

• Long hydrophobic patches promote aggregation
• Exposed hydrophobic residues drive protein clumping
• Poor solubility in aqueous buffers

Solution:

• Maintain balanced hydropathy profiles
• Use short, flexible linkers between domains
• Reduce surface-exposed hydrophobic residues

Metrics:

• Kyte-Doolittle hydropathy plots
• GRAVY score (Grand Average of Hydropathy)
• pSAE (percent Solvent-Accessible hydrophobic residues)

3. Low Solubility

Problem:

• Proteins precipitate during expression or purification
• Inclusion body formation
• Difficult downstream processing

Solution:

• Use solubility prediction tools for pre-screening
• Apply sequence optimization algorithms
• Add solubilizing tags if needed

Computational Tools for Optimization

NetSolP - Initial Solubility Screening

Purpose: Fast solubility prediction for filtering sequences.

Method: Machine learning model trained on E. coli expression data.

Usage:

# Install: uv pip install requests
import requests

def predict_solubility_netsolp(sequence):
    """Predict protein solubility using NetSolP web service"""
    url = "https://services.healthtech.dtu.dk/services/NetSolP-1.0/api/predict"

    data = {
        "sequence": sequence,
        "format": "fasta"
    }

    response = requests.post(url, data=data)
    return response.json()

# Example
sequence = "MKVLWAALLGLLGAAA..."
result = predict_solubility_netsolp(sequence)
print(f"Solubility score: {result['score']}")

Interpretation:

• Score > 0.5: Likely soluble
• Score < 0.5: Likely insoluble
• Use for initial filtering before more expensive predictions

When to use:

• First-pass filtering of large libraries
• Quick validation of designed sequences
• Prioritizing sequences for experimental testing

SoluProt - Comprehensive Solubility Prediction

Purpose: Advanced solubility prediction with higher accuracy.

Method: Deep learning model incorporating sequence and structural features.

Usage:

# Install: uv pip install soluprot
from soluprot import predict_solubility

def screen_variants_soluprot(sequences):
    """Screen multiple sequences for solubility"""
    results = []
    for name, seq in sequences.items():
        score = predict_solubility(seq)
        results.append({
            'name': name,
            'sequence': seq,
            'solubility_score': score,
            'predicted_soluble': score > 0.6
        })
    return results

# Example
sequences = {
    'variant_1': 'MKVLW...',
    'variant_2': 'MATGV...'
}

results = screen_variants_soluprot(sequences)
soluble_variants = [r for r in results if r['predicted_soluble']]

Interpretation:

• Score > 0.6: High solubility confidence
• Score 0.4-0.6: Uncertain, may need optimization
• Score < 0.4: Likely problematic

When to use:

• After initial NetSolP filtering
• When higher prediction accuracy is needed
• Before committing to expensive synthesis/testing

SolubleMPNN - Sequence Redesign

Purpose: Redesign protein sequences to improve solubility while maintaining function.

Method: Graph neural network that suggests mutations to increase solubility.

Usage:

# Install: uv pip install soluble-mpnn
from soluble_mpnn import optimize_sequence

def optimize_for_solubility(sequence, structure_pdb=None):
    """
    Redesign sequence for improved solubility

    Args:
        sequence: Original amino acid sequence
        structure_pdb: Optional PDB file for structure-aware design

    Returns:
        Optimized sequence variants ranked by predicted solubility
    """

    variants = optimize_sequence(
        sequence=sequence,
        structure=structure_pdb,
        num_variants=10,
        temperature=0.1  # Lower = more conservative mutations
    )

    return variants

# Example
original_seq = "MKVLWAALLGLLGAAA..."
optimized_variants = optimize_for_solubility(original_seq)

for i, variant in enumerate(optimized_variants):
    print(f"Variant {i+1}:")
    print(f"  Sequence: {variant['sequence']}")
    print(f"  Solubility score: {variant['solubility_score']}")
    print(f"  Mutations: {variant['mutations']}")

Design strategy:

• Conservative (temperature=0.1): Minimal changes, safer
• Moderate (temperature=0.3): Balance between change and safety
• Aggressive (temperature=0.5): More mutations, higher risk

When to use:

• Primary tool for sequence optimization
• Default starting point for improving problematic sequences
• Generating diverse soluble variants

Best practices:

• Generate 10-50 variants per sequence
• Use structure information when available (improves accuracy)
• Validate key functional residues are preserved
• Test multiple temperature settings

ESM (Evolutionary Scale Modeling) - Sequence Likelihood

Purpose: Assess how "natural" a protein sequence appears based on evolutionary patterns.

Method: Protein language model trained on millions of natural sequences.

Usage:

# Install: uv pip install fair-esm
import torch
from esm import pretrained

def score_sequence_esm(sequence):
    """
    Calculate ESM likelihood score for sequence
    Higher scores indicate more natural/stable sequences
    """

    model, alphabet = pretrained.esm2_t33_650M_UR50D()
    batch_converter = alphabet.get_batch_converter()

    data = [("protein", sequence)]
    _, _, batch_tokens = batch_converter(data)

    with torch.no_grad():
        results = model(batch_tokens, repr_layers=[33])
        token_logprobs = results["logits"].log_softmax(dim=-1)

    # Calculate perplexity as sequence quality metric
    sequence_score = token_logprobs.mean().item()

    return sequence_score

# Example - Compare variants
sequences = {
    'original': 'MKVLW...',
    'optimized_1': 'MKVLS...',
    'optimized_2': 'MKVLA...'
}

for name, seq in sequences.items():
    score = score_sequence_esm(seq)
    print(f"{name}: ESM score = {score:.3f}")

Interpretation:

• Higher scores → More "natural" sequence
• Use to avoid unlikely mutations
• Balance with functional requirements

When to use:

• Filtering synthetic designs
• Comparing SolubleMPNN variants
• Ensuring sequences aren't too artificial
• Avoiding expression bottlenecks

Integration with design:

def rank_variants_by_esm(variants):
    """Rank protein variants by ESM likelihood"""
    scored = []
    for v in variants:
        esm_score = score_sequence_esm(v['sequence'])
        v['esm_score'] = esm_score
        scored.append(v)

    # Sort by combined solubility and ESM score
    scored.sort(
        key=lambda x: x['solubility_score'] * x['esm_score'],
        reverse=True
    )

    return scored

ipTM - Interface Stability (AlphaFold-Multimer)

Purpose: Assess protein-protein interface stability and binding confidence.

Method: Interface predicted TM-score from AlphaFold-Multimer predictions.

Usage:

# Requires AlphaFold-Multimer installation
# Or use ColabFold for easier access

def predict_interface_stability(protein_a_seq, protein_b_seq):
    """
    Predict interface stability using AlphaFold-Multimer

    Returns ipTM score: higher = more stable interface
    """
    from colabfold import run_alphafold_multimer

    sequences = {
        'chainA': protein_a_seq,
        'chainB': protein_b_seq
    }

    result = run_alphafold_multimer(sequences)

    return {
        'ipTM': result['iptm'],
        'pTM': result['ptm'],
        'pLDDT': result['plddt']
    }

# Example for antibody-antigen binding
antibody_seq = "EVQLVESGGGLVQPGG..."
antigen_seq = "MKVLWAALLGLLGAAA..."

stability = predict_interface_stability(antibody_seq, antigen_seq)
print(f"Interface pTM: {stability['ipTM']:.3f}")

# Interpretation
if stability['ipTM'] > 0.7:
    print("High confidence interface")
elif stability['ipTM'] > 0.5:
    print("Moderate confidence interface")
else:
    print("Low confidence interface - may need redesign")

Interpretation:

• ipTM > 0.7: Strong predicted interface
• ipTM 0.5-0.7: Moderate interface confidence
• ipTM < 0.5: Weak interface, consider redesign

When to use:

• Antibody-antigen design
• Protein-protein interaction engineering
• Validating binding interfaces
• Comparing interface variants

pSAE - Solvent-Accessible Hydrophobic Residues

Purpose: Quantify exposed hydrophobic residues that promote aggregation.

Method: Calculates percentage of solvent-accessible surface area (SASA) occupied by hydrophobic residues.

Usage:

# Requires structure (PDB file or AlphaFold prediction)
# Install: uv pip install biopython

from Bio.PDB import PDBParser, DSSP
import numpy as np

def calculate_psae(pdb_file):
    """
    Calculate percent Solvent-Accessible hydrophobic residues (pSAE)

    Lower pSAE = better solubility
    """

    parser = PDBParser(QUIET=True)
    structure = parser.get_structure('protein', pdb_file)

    # Run DSSP to get solvent accessibility
    model = structure[0]
    dssp = DSSP(model, pdb_file, acc_array='Wilke')

    hydrophobic = ['ALA', 'VAL', 'ILE', 'LEU', 'MET', 'PHE', 'TRP', 'PRO']

    total_sasa = 0
    hydrophobic_sasa = 0

    for residue in dssp:
        res_name = residue[1]
        rel_accessibility = residue[3]

        total_sasa += rel_accessibility
        if res_name in hydrophobic:
            hydrophobic_sasa += rel_accessibility

    psae = (hydrophobic_sasa / total_sasa) * 100

    return psae

# Example
pdb_file = "protein_structure.pdb"
psae_score = calculate_psae(pdb_file)
print(f"pSAE: {psae_score:.2f}%")

# Interpretation
if psae_score < 25:
    print("Good solubility expected")
elif psae_score < 35:
    print("Moderate solubility")
else:
    print("High aggregation risk")

Interpretation:

• pSAE < 25%: Low aggregation risk
• pSAE 25-35%: Moderate risk
• pSAE > 35%: High aggregation risk

When to use:

• Analyzing designed structures
• Post-AlphaFold validation
• Identifying aggregation hotspots
• Guiding surface mutations

Recommended Optimization Workflow

Step 1: Initial Screening (Fast)

def initial_screening(sequences):
    """
    Quick first-pass filtering using NetSolP
    Filters out obviously problematic sequences
    """
    passed = []
    for name, seq in sequences.items():
        netsolp_score = predict_solubility_netsolp(seq)
        if netsolp_score > 0.5:
            passed.append((name, seq))

    return passed

Step 2: Detailed Assessment (Moderate)

def detailed_assessment(filtered_sequences):
    """
    More thorough analysis with SoluProt and ESM
    Ranks sequences by multiple criteria
    """
    results = []
    for name, seq in filtered_sequences:
        soluprot_score = predict_solubility(seq)
        esm_score = score_sequence_esm(seq)

        combined_score = soluprot_score * 0.7 + esm_score * 0.3

        results.append({
            'name': name,
            'sequence': seq,
            'soluprot': soluprot_score,
            'esm': esm_score,
            'combined': combined_score
        })

    results.sort(key=lambda x: x['combined'], reverse=True)
    return results

Step 3: Sequence Optimization (If needed)

def optimize_problematic_sequences(sequences_needing_optimization):
    """
    Use SolubleMPNN to redesign problematic sequences
    Returns improved variants
    """
    optimized = []
    for name, seq in sequences_needing_optimization:
        # Generate multiple variants
        variants = optimize_sequence(
            sequence=seq,
            num_variants=10,
            temperature=0.2
        )

        # Score variants with ESM
        for variant in variants:
            variant['esm_score'] = score_sequence_esm(variant['sequence'])

        # Keep best variants
        variants.sort(
            key=lambda x: x['solubility_score'] * x['esm_score'],
            reverse=True
        )

        optimized.extend(variants[:3])  # Top 3 variants per sequence

    return optimized

Step 4: Structure-Based Validation (For critical sequences)

def structure_validation(top_candidates):
    """
    Predict structures and calculate pSAE for top candidates
    Final validation before experimental testing
    """
    validated = []
    for candidate in top_candidates:
        # Predict structure with AlphaFold
        structure_pdb = predict_structure_alphafold(candidate['sequence'])

        # Calculate pSAE
        psae = calculate_psae(structure_pdb)

        candidate['psae'] = psae
        candidate['pass_structure_check'] = psae < 30

        validated.append(candidate)

    return validated

Complete Workflow Example

def complete_optimization_pipeline(initial_sequences):
    """
    End-to-end optimization pipeline

    Input: Dictionary of {name: sequence}
    Output: Ranked list of optimized, validated sequences
    """

    print("Step 1: Initial screening with NetSolP...")
    filtered = initial_screening(initial_sequences)
    print(f"  Passed: {len(filtered)}/{len(initial_sequences)}")

    print("Step 2: Detailed assessment with SoluProt and ESM...")
    assessed = detailed_assessment(filtered)

    # Split into good and needs-optimization
    good_sequences = [s for s in assessed if s['soluprot'] > 0.6]
    needs_optimization = [s for s in assessed if s['soluprot'] <= 0.6]

    print(f"  Good sequences: {len(good_sequences)}")
    print(f"  Need optimization: {len(needs_optimization)}")

    if needs_optimization:
        print("Step 3: Optimizing problematic sequences with SolubleMPNN...")
        optimized = optimize_problematic_sequences(needs_optimization)
        all_sequences = good_sequences + optimized
    else:
        all_sequences = good_sequences

    print("Step 4: Structure-based validation for top candidates...")
    top_20 = all_sequences[:20]
    final_validated = structure_validation(top_20)

    # Final ranking
    final_validated.sort(
        key=lambda x: (
            x['pass_structure_check'],
            x['combined'],
            -x['psae']
        ),
        reverse=True
    )

    return final_validated

# Usage
initial_library = {
    'variant_1': 'MKVLWAALLGLLGAAA...',
    'variant_2': 'MATGVLWAALLGLLGA...',
    # ... more sequences
}

optimized_library = complete_optimization_pipeline(initial_library)

# Submit top sequences to Adaptyv
top_sequences_for_testing = optimized_library[:50]

Best Practices Summary

1. Always pre-screen before experimental testing 2. Use NetSolP first for fast filtering of large libraries 3. Apply SolubleMPNN as default optimization tool 4. Validate with ESM to avoid unnatural sequences 5. Calculate pSAE for structure-based validation 6. Test multiple variants per design to account for prediction uncertainty 7. Keep controls - include wild-type or known-good sequences 8. Iterate - use experimental results to refine predictions

Integration with Adaptyv

After computational optimization, submit sequences to Adaptyv:

# After optimization pipeline
optimized_sequences = complete_optimization_pipeline(initial_library)

# Prepare FASTA format
fasta_content = ""
for seq_data in optimized_sequences[:50]:  # Top 50
    fasta_content += f">{seq_data['name']}\n{seq_data['sequence']}\n"

# Submit to Adaptyv
import requests
response = requests.post(
    "https://kq5jp7qj7wdqklhsxmovkzn4l40obksv.lambda-url.eu-central-1.on.aws/experiments",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "sequences": fasta_content,
        "experiment_type": "expression",
        "metadata": {
            "optimization_method": "SolubleMPNN_ESM_pipeline",
            "computational_scores": [s['combined'] for s in optimized_sequences[:50]]
        }
    }
)

Troubleshooting

Issue: All sequences score poorly on solubility predictions

• Check if sequences contain unusual amino acids
• Verify FASTA format is correct
• Consider if protein family is naturally low-solubility
• May need experimental validation despite predictions

Issue: SolubleMPNN changes functionally important residues

• Provide structure file to preserve spatial constraints
• Mask critical residues from mutation
• Lower temperature parameter for conservative changes
• Manually revert problematic mutations

Issue: ESM scores are low after optimization

• Optimization may be too aggressive
• Try lower temperature in SolubleMPNN
• Balance between solubility and naturalness
• Consider that some optimization may require non-natural mutations

Issue: Predictions don't match experimental results

• Predictions are probabilistic, not deterministic
• Host system and conditions affect expression
• Some proteins may need experimental validation
• Use predictions as enrichment, not absolute filters

Research Requirements

• Exa-first research
• WebFetch/arXiv fallback
• Map findings to hooks/rules/schemas/workflows

adaptyv Rules

• Apply safe, minimal, test-backed updates.
• Keep nested skill behavior aligned with ecosystem contracts.

adaptyv Implementation Template

TDD

1. Red 2. Green 3. Refactor

/aeon

Run scientific-skills/skills/aeon with TDD checkpoints and ecosystem validation.

Anomaly Detection

Aeon provides anomaly detection methods for identifying unusual patterns in time series at both series and collection levels.

Collection Anomaly Detectors

Detect anomalous time series within a collection:

• ClassificationAdapter - Adapts classifiers for anomaly detection
• Train on normal data, flag outliers during prediction
• Use when: Have labeled normal data, want classification-based approach

• OutlierDetectionAdapter - Wraps sklearn outlier detectors
• Works with IsolationForest, LOF, OneClassSVM
• Use when: Want to use sklearn anomaly detectors on collections

Series Anomaly Detectors

Detect anomalous points or subsequences within a single time series.

Distance-Based Methods

Use similarity metrics to identify anomalies:

• CBLOF - Cluster-Based Local Outlier Factor
• Clusters data, identifies outliers based on cluster properties
• Use when: Anomalies form sparse clusters

• KMeansAD - K-means based anomaly detection
• Distance to nearest cluster center indicates anomaly
• Use when: Normal patterns cluster well

• LeftSTAMPi - Left STAMP incremental
• Matrix profile for online anomaly detection
• Use when: Streaming data, need online detection

• STOMP - Scalable Time series Ordered-search Matrix Profile
• Computes matrix profile for subsequence anomalies
• Use when: Discord discovery, motif detection

• MERLIN - Matrix profile-based method
• Efficient matrix profile computation
• Use when: Large time series, need scalability

• LOF - Local Outlier Factor adapted for time series
• Density-based outlier detection
• Use when: Anomalies in low-density regions

• ROCKAD - ROCKET-based semi-supervised detection
• Uses ROCKET features for anomaly identification
• Use when: Have some labeled data, want feature-based approach

Distribution-Based Methods

Analyze statistical distributions:

• COPOD - Copula-Based Outlier Detection
• Models marginal and joint distributions
• Use when: Multi-dimensional time series, complex dependencies

• DWT_MLEAD - Discrete Wavelet Transform Multi-Level Anomaly Detection
• Decomposes series into frequency bands
• Use when: Anomalies at specific frequencies

Isolation-Based Methods

Use isolation principles:

• IsolationForest - Random forest-based isolation
• Anomalies easier to isolate than normal points
• Use when: High-dimensional data, no assumptions about distribution

• OneClassSVM - Support vector machine for novelty detection
• Learns boundary around normal data
• Use when: Well-defined normal region, need robust boundary

• STRAY - Streaming Robust Anomaly Detection
• Robust to data distribution changes
• Use when: Streaming data, distribution shifts

External Library Integration

• PyODAdapter - Bridges PyOD library to aeon
• Access 40+ PyOD anomaly detectors
• Use when: Need specific PyOD algorithm

Quick Start

from aeon.anomaly_detection import STOMP
import numpy as np

# Create time series with anomaly
y = np.concatenate([
    np.sin(np.linspace(0, 10, 100)),
    [5.0],  # Anomaly spike
    np.sin(np.linspace(10, 20, 100))
])

# Detect anomalies
detector = STOMP(window_size=10)
anomaly_scores = detector.fit_predict(y)

# Higher scores indicate more anomalous points
threshold = np.percentile(anomaly_scores, 95)
anomalies = anomaly_scores > threshold

Point vs Subsequence Anomalies

• Point anomalies: Single unusual values
• Use: COPOD, DWT_MLEAD, IsolationForest

• Subsequence anomalies (discords): Unusual patterns
• Use: STOMP, LeftSTAMPi, MERLIN

• Collective anomalies: Groups of points forming unusual pattern
• Use: Matrix profile methods, clustering-based

Evaluation Metrics

Specialized metrics for anomaly detection:

from aeon.benchmarking.metrics.anomaly_detection import (
    range_precision,
    range_recall,
    range_f_score,
    roc_auc_score
)

# Range-based metrics account for window detection
precision = range_precision(y_true, y_pred, alpha=0.5)
recall = range_recall(y_true, y_pred, alpha=0.5)
f1 = range_f_score(y_true, y_pred, alpha=0.5)

Algorithm Selection

• Speed priority: KMeansAD, IsolationForest
• Accuracy priority: STOMP, COPOD
• Streaming data: LeftSTAMPi, STRAY
• Discord discovery: STOMP, MERLIN
• Multi-dimensional: COPOD, PyODAdapter
• Semi-supervised: ROCKAD, OneClassSVM
• No training data: IsolationForest, STOMP

Best Practices

1. Normalize data: Many methods sensitive to scale 2. Choose window size: For matrix profile methods, window size critical 3. Set threshold: Use percentile-based or domain-specific thresholds 4. Validate results: Visualize detections to verify meaningfulness 5. Handle seasonality: Detrend/deseasonalize before detection

Time Series Classification

Aeon provides 13 categories of time series classifiers with scikit-learn compatible APIs.

Convolution-Based Classifiers

Apply random convolutional transformations for efficient feature extraction:

• Arsenal - Ensemble of ROCKET classifiers with varied kernels
• HydraClassifier - Multi-resolution convolution with dilation
• RocketClassifier - Random convolution kernels with ridge regression
• MiniRocketClassifier - Simplified ROCKET variant for speed
• MultiRocketClassifier - Combines multiple ROCKET variants

Use when: Need fast, scalable classification with strong performance across diverse datasets.

Deep Learning Classifiers

Neural network architectures optimized for temporal sequences:

• FCNClassifier - Fully convolutional network
• ResNetClassifier - Residual networks with skip connections
• InceptionTimeClassifier - Multi-scale inception modules
• TimeCNNClassifier - Standard CNN for time series
• MLPClassifier - Multi-layer perceptron baseline
• EncoderClassifier - Generic encoder wrapper
• DisjointCNNClassifier - Shapelet-focused architecture

Use when: Large datasets available, need end-to-end learning, or complex temporal patterns.

Dictionary-Based Classifiers

Transform time series into symbolic representations:

• BOSSEnsemble - Bag-of-SFA-Symbols with ensemble voting
• TemporalDictionaryEnsemble - Multiple dictionary methods combined
• WEASEL - Word ExtrAction for time SEries cLassification
• MrSEQLClassifier - Multiple symbolic sequence learning

Use when: Need interpretable models, sparse patterns, or symbolic reasoning.

Distance-Based Classifiers

Leverage specialized time series distance metrics:

• KNeighborsTimeSeriesClassifier - k-NN with temporal distances (DTW, LCSS, ERP, etc.)
• ElasticEnsemble - Combines multiple elastic distance measures
• ProximityForest - Tree ensemble using distance-based splits

Use when: Small datasets, need similarity-based classification, or interpretable decisions.

Feature-Based Classifiers

Extract statistical and signature features before classification:

• Catch22Classifier - 22 canonical time-series characteristics
• TSFreshClassifier - Automated feature extraction via tsfresh
• SignatureClassifier - Path signature transformations
• SummaryClassifier - Summary statistics extraction
• FreshPRINCEClassifier - Combines multiple feature extractors

Use when: Need interpretable features, domain expertise available, or feature engineering approach.

Interval-Based Classifiers

Extract features from random or supervised intervals:

• CanonicalIntervalForestClassifier - Random interval features with decision trees
• DrCIFClassifier - Diverse Representation CIF with catch22 features
• TimeSeriesForestClassifier - Random intervals with summary statistics
• RandomIntervalClassifier - Simple interval-based approach
• RandomIntervalSpectralEnsembleClassifier - Spectral features from intervals
• SupervisedTimeSeriesForest - Supervised interval selection

Use when: Discriminative patterns occur in specific time windows.

Shapelet-Based Classifiers

Identify discriminative subsequences (shapelets):

• ShapeletTransformClassifier - Discovers and uses discriminative shapelets
• LearningShapeletClassifier - Learns shapelets via gradient descent
• SASTClassifier - Scalable approximate shapelet transform
• RDSTClassifier - Random dilated shapelet transform

Use when: Need interpretable discriminative patterns or phase-invariant features.

Hybrid Classifiers

Combine multiple classification paradigms:

• HIVECOTEV1 - Hierarchical Vote Collective of Transformation-based Ensembles (version 1)
• HIVECOTEV2 - Enhanced version with updated components

Use when: Maximum accuracy required, computational resources available.

Early Classification

Make predictions before observing entire time series:

• TEASER - Two-tier Early and Accurate Series Classifier
• ProbabilityThresholdEarlyClassifier - Prediction when confidence exceeds threshold

Use when: Real-time decisions needed, or observations have cost.

Ordinal Classification

Handle ordered class labels:

• OrdinalTDE - Temporal dictionary ensemble for ordinal outputs

Use when: Classes have natural ordering (e.g., severity levels).

Composition Tools

Build custom pipelines and ensembles:

• ClassifierPipeline - Chain transformers with classifiers
• WeightedEnsembleClassifier - Weighted combination of classifiers
• SklearnClassifierWrapper - Adapt sklearn classifiers for time series

Quick Start

from aeon.classification.convolution_based import RocketClassifier
from aeon.datasets import load_classification

# Load data
X_train, y_train = load_classification("GunPoint", split="train")
X_test, y_test = load_classification("GunPoint", split="test")

# Train and predict
clf = RocketClassifier()
clf.fit(X_train, y_train)
accuracy = clf.score(X_test, y_test)

Algorithm Selection

• Speed priority: MiniRocketClassifier, Arsenal
• Accuracy priority: HIVECOTEV2, InceptionTimeClassifier
• Interpretability: ShapeletTransformClassifier, Catch22Classifier
• Small data: KNeighborsTimeSeriesClassifier, Distance-based methods
• Large data: Deep learning classifiers, ROCKET variants

Time Series Clustering

Aeon provides clustering algorithms adapted for temporal data with specialized distance metrics and averaging methods.

Partitioning Algorithms

Standard k-means/k-medoids adapted for time series:

• TimeSeriesKMeans - K-means with temporal distance metrics (DTW, Euclidean, etc.)
• TimeSeriesKMedoids - Uses actual time series as cluster centers
• TimeSeriesKShape - Shape-based clustering algorithm
• TimeSeriesKernelKMeans - Kernel-based variant for nonlinear patterns

Use when: Known number of clusters, spherical cluster shapes expected.

Large Dataset Methods

Efficient clustering for large collections:

• TimeSeriesCLARA - Clustering Large Applications with sampling
• TimeSeriesCLARANS - Randomized search variant of CLARA

Use when: Dataset too large for standard k-medoids, need scalability.

Elastic Distance Clustering

Specialized for alignment-based similarity:

• KASBA - K-means with shift-invariant elastic averaging
• ElasticSOM - Self-organizing map using elastic distances

Use when: Time series have temporal shifts or warping.

Spectral Methods

Graph-based clustering:

• KSpectralCentroid - Spectral clustering with centroid computation

Use when: Non-convex cluster shapes, need graph-based approach.

Deep Learning Clustering

Neural network-based clustering with auto-encoders:

• AEFCNClusterer - Fully convolutional auto-encoder
• AEResNetClusterer - Residual network auto-encoder
• AEDCNNClusterer - Dilated CNN auto-encoder
• AEDRNNClusterer - Dilated RNN auto-encoder
• AEBiGRUClusterer - Bidirectional GRU auto-encoder
• AEAttentionBiGRUClusterer - Attention-enhanced BiGRU auto-encoder

Use when: Large datasets, need learned representations, or complex patterns.

Feature-Based Clustering

Transform to feature space before clustering:

• Catch22Clusterer - Clusters on 22 canonical features
• SummaryClusterer - Uses summary statistics
• TSFreshClusterer - Automated tsfresh features

Use when: Raw time series not informative, need interpretable features.

Composition

Build custom clustering pipelines:

• ClustererPipeline - Chain transformers with clusterers

Averaging Methods

Compute cluster centers for time series:

• mean_average - Arithmetic mean
• ba_average - Barycentric averaging with DTW
• kasba_average - Shift-invariant averaging
• shift_invariant_average - General shift-invariant method

Use when: Need representative cluster centers for visualization or initialization.

Quick Start

from aeon.clustering import TimeSeriesKMeans
from aeon.datasets import load_classification

# Load data (using classification data for clustering)
X_train, _ = load_classification("GunPoint", split="train")

# Cluster time series
clusterer = TimeSeriesKMeans(
    n_clusters=3,
    distance="dtw",  # Use DTW distance
    averaging_method="ba"  # Barycentric averaging
)
labels = clusterer.fit_predict(X_train)
centers = clusterer.cluster_centers_

Algorithm Selection

• Speed priority: TimeSeriesKMeans with Euclidean distance
• Temporal alignment: KASBA, TimeSeriesKMeans with DTW
• Large datasets: TimeSeriesCLARA, TimeSeriesCLARANS
• Complex patterns: Deep learning clusterers
• Interpretability: Catch22Clusterer, SummaryClusterer
• Non-convex clusters: KSpectralCentroid

Distance Metrics

Compatible distance metrics include:

• Euclidean, Manhattan, Minkowski (lock-step)
• DTW, DDTW, WDTW (elastic with alignment)
• ERP, EDR, LCSS (edit-based)
• MSM, TWE (specialized elastic)

Evaluation

Use clustering metrics from sklearn or aeon benchmarking:

• Silhouette score
• Davies-Bouldin index
• Calinski-Harabasz index

Time Series Forecasting

Aeon provides forecasting algorithms for predicting future time series values.

Naive and Baseline Methods

Simple forecasting strategies for comparison:

• NaiveForecaster - Multiple strategies: last value, mean, seasonal naive
• Parameters: strategy ("last", "mean", "seasonal"), sp (seasonal period)
• Use when: Establishing baselines or simple patterns

Statistical Models

Classical time series forecasting methods:

ARIMA

• ARIMA - AutoRegressive Integrated Moving Average
• Parameters: p (AR order), d (differencing), q (MA order)
• Use when: Linear patterns, stationary or difference-stationary series

Exponential Smoothing

• ETS - Error-Trend-Seasonal decomposition
• Parameters: error, trend, seasonal types
• Use when: Trend and seasonal patterns present

Threshold Autoregressive

• TAR - Threshold Autoregressive model for regime switching
• AutoTAR - Automated threshold discovery
• Use when: Series exhibits different behaviors in different regimes

Theta Method

• Theta - Classical Theta forecasting
• Parameters: theta, weights for decomposition
• Use when: Simple but effective baseline needed

Time-Varying Parameter

• TVP - Time-varying parameter model with Kalman filtering
• Use when: Parameters change over time

Deep Learning Forecasters

Neural networks for complex temporal patterns:

• TCNForecaster - Temporal Convolutional Network
• Dilated convolutions for large receptive fields
• Use when: Long sequences, need non-recurrent architecture

• DeepARNetwork - Probabilistic forecasting with RNNs
• Provides prediction intervals
• Use when: Need probabilistic forecasts, uncertainty quantification

Regression-Based Forecasting

Apply regression to lagged features:

• RegressionForecaster - Wraps regressors for forecasting
• Parameters: window_length, horizon
• Use when: Want to use any regressor as forecaster

Quick Start

from aeon.forecasting.naive import NaiveForecaster
from aeon.forecasting.arima import ARIMA
import numpy as np

# Create time series
y = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])

# Naive baseline
naive = NaiveForecaster(strategy="last")
naive.fit(y)
forecast_naive = naive.predict(fh=[1, 2, 3])

# ARIMA model
arima = ARIMA(order=(1, 1, 1))
arima.fit(y)
forecast_arima = arima.predict(fh=[1, 2, 3])

Forecasting Horizon

The forecasting horizon (fh) specifies which future time points to predict:

# Relative horizon (next 3 steps)
fh = [1, 2, 3]

# Absolute horizon (specific time indices)
from aeon.forecasting.base import ForecastingHorizon
fh = ForecastingHorizon([11, 12, 13], is_relative=False)

Model Selection

• Baseline: NaiveForecaster with seasonal strategy
• Linear patterns: ARIMA
• Trend + seasonality: ETS
• Regime changes: TAR, AutoTAR
• Complex patterns: TCNForecaster
• Probabilistic: DeepARNetwork
• Long sequences: TCNForecaster
• Short sequences: ARIMA, ETS

Evaluation Metrics

Use standard forecasting metrics:

from aeon.performance_metrics.forecasting import (
    mean_absolute_error,
    mean_squared_error,
    mean_absolute_percentage_error
)

# Calculate error
mae = mean_absolute_error(y_true, y_pred)
mse = mean_squared_error(y_true, y_pred)
mape = mean_absolute_percentage_error(y_true, y_pred)

Exogenous Variables

Many forecasters support exogenous features:

# Train with exogenous variables
forecaster.fit(y, X=X_train)

# Predict requires future exogenous values
y_pred = forecaster.predict(fh=[1, 2, 3], X=X_test)

Base Classes

• BaseForecaster - Abstract base for all forecasters
• BaseDeepForecaster - Base for deep learning forecasters

Extend these to implement custom forecasting algorithms.

Research Requirements

• Exa-first research
• WebFetch/arXiv fallback
• Map findings to hooks/rules/schemas/workflows

aeon Implementation Template

TDD

1. Red 2. Green 3. Refactor