alterlab-bioservices

Files (9)

• SKILL.md
• evals.json · evals/
• identifier_mapping.md · references/
• services_reference.md · references/
• workflow_patterns.md · references/
• batch_id_converter.py · scripts/
• compound_cross_reference.py · scripts/
• pathway_analysis.py · scripts/
• protein_analysis_workflow.py · scripts/

SKILL.md (first lines)

# BioServices

## Overview

BioServices is a Python package providing programmatic access to roughly 40 bioinformatics web services and databases. Retrieve biological data, perform cross-database queries, map identifiers, analyze sequences, and integrate multiple biological resources in Python workflows.

**Recent changes that break old scripts** (verified against bioservices 1.16.0):

- **SOAP/WSDL support was removed in 1.15** — every active service is REST now, and the
  `WSDLService` class and its `suds` dependency are gone.
- **`PSICQUIC` and `BioGRID` were removed in 1.14.** For protein interactions use the
  `STRING` class (added in 1.14) or `IntactComplex`; `from bioservices import PSICQUIC`
  raises `ImportError`.
- **`UniProt.mapping()` returns the raw UniProt job payload** —
  `{"results": [{"from": ..., "to": ...}, ...], "failedIds": [...]}` — not a
  `{source_id: [target_ids]}` dict. See "Identifier Mapping" below.
- **NCBIblast methods are snake_case** (`get_status`, `get_result`, `get_result_types`,
  `wait`); the old `getStatus`/`getResult` camelCase names are gone. 1.16 also adds
  `ncbiblastapi.NCBIBlastAPI`, which submits to NCBI directly instead of EBI.

## When to Use This Skill

This skill should be used when:
- Retrieving protein sequences, annotations, or structures from UniProt, PDB, Pfam
- Analyzing metabolic pathways and gene functions via KEGG or Reactome
- Searching compound databases (ChEBI, ChEMBL, PubChem) for chemical information
- Converting identifiers between different biological databases (KEGG↔UniProt, compound IDs)
- Running sequence similarity searches (BLAST, MUSCLE alignment)
- Querying gene ontology terms (QuickGO, GO annotations)
- Accessing protein-protein interaction data (STRING, IntactComplex)
- Mining genomic data (BioMart, ArrayExpress, ENA)
- Integrating data from multiple bioinformatics resources in a single workflow

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| A single quick lookup (one gene, one structure, one enrichment) | `alterlab-gget` |
| Parsing sequence/structure files or scripting Entrez directly | `alterlab-biopython` |
| Local BLAST+ / `makeblastdb` / DIAMOND on your own database | `alterlab-blast` |
| Deep work in one database (full KEGG, UniProt, or ChEMBL feature set) | `alterlab-kegg`, `alterlab-uniprot`, `alterlab-chembl` |
| Cheminformatics on the retrieved structures (descriptors, fingerprints) | `alterlab-rdkit` |

## Core Capabilities

### 1. Protein Analysis

Retrieve protein information, sequences, and functional annotations:

```python
from bioservices import UniProt

u = UniProt(verbose=False)

# Search for protein by name. frmt is one of xlsx/fasta/json/gff/tsv — "tab" was
# retired with the June-2022 UniProt API and now raises.
results = u.search("ZAP70_HUMAN", frmt="tsv", columns="accession,gene_names,organism_name")

# Retrieve FASTA sequence (frmt defaults to json)
sequence = u.retrieve("P43403", frmt="fasta")

# Map identifiers between databases -> {"results": [{"from": ..., "to": ...}], "failedIds": [...]}
job = u.mapping(fr="UniProtKB_AC-ID", to="KEGG", query="P43403")
kegg_ids = [r["to"] for r in job["results"]]
```

**Key methods:**
- `search()`: Query UniProt with flexible search terms (`frmt="tsv"`, `columns` as UniProt
  return-field names such as `accession`, `gene_names`, `organism_name`, `length`)
- `retrieve()`: Get protein entries in various formats (json, txt, xml, rdf, gff, fasta)
- `mapping()`: Submit an ID-mapping job and return its results payload

Reference: `references/services_reference.md` for complete UniProt API details.

### 2. Pathway Discovery and Analysis

Access KEGG pathway information for genes and organisms:

```python
from bioservices import KEGG

k = KEGG()
k.organism = "hsa"  # Set to human

# Search for organisms
k.lookfor_organism("droso")  # Find Drosophila species

# Find pathways by name
k.lookfor_pathway("B cell")  # Returns matching pathway IDs

# Get pathways containing specific genes
pathways = k.get_pathway_by_gene("7535", "hsa")  # ZAP70 gene

# Retrieve and parse pathway data
data = k.get("hsa04660")
parsed = k.parse(data)

# Extract pathway interactions
interactions = k.parse_kgml_pathway("hsa04660")
relations = interactions['relations']  # Protein-protein interactions

# Convert to Simple Interaction Format
sif_data = k.pathway2sif("hsa04660")
```

**Key methods:**
- `lookfor_organism()`, `lookfor_pathway()`: Search by name
- `get_pathway_by_gene()`: Find pathways containing genes
- `parse_kgml_pathway()`: Extract structured pathway data
- `pathway2sif()`: Get protein interaction networks

Reference: `references/workflow_patterns.md` for complete pathway analysis workflows.

### 3. Compound Database Searches

Search and cross-reference compounds across multiple databases:

```python
from bioservices import KEGG

From AlterLab-IEU/AlterLab-Academic-Skills, GPL-3.0.

More from AlterLab-IEU/AlterLab-Academic-Skills