Interpro Database

InterPro Database Access

Prerequisites

1. `uv`: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH.
2. User Notification: If .licenses/interpro_database_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://www.ebi.ac.uk/interpro/ and https://www.ebi.ac.uk/about/terms-of-use/, then (2) create the file recording the notification text and timestamp.

Overview

InterPro combines signatures from multiple, diverse databases into a single searchable resource, reducing redundancy and helping users interpret their sequence analysis results. By uniting these member databases (e.g., Pfam, CDD, SMART), InterPro capitalises on their individual strengths to produce a powerful diagnostic tool and integrated resource.

Use interpro-database to:

• Identify what domains, families, and sites are found in a particular protein.
• Identify all proteins that belong to a protein family or contain a particular domain, even when the names and activities of the proteins are highly variable.
• Examine the species in which a particular protein family or domain is found.
• Annotate genomes with protein family information and Gene Ontology (GO) terms.

This skill provides a robust utility, interpro_client.py, to interact with the InterPro API seamlessly. It natively handles rate limiting (HTTP 429), background query sleep tracking (HTTP 408), terminal errors (HTTP 404/410), and lazy pagination.

Core Rules

• Use the Wrapper: ALWAYS execute the scripts/interpro_client.py helper script to query the database rather than accessing the database directly. The scripts automatically enforce fair use and implement retry logic.
• For exploratory queries: ALWAYS use the CLI with a strict --limit. This allows you to rapidly understand the data schema without polluting your context window or fetching millions of results.
• Output to file: Use the CLI with --output to output to a file rather than attempting to print it all to the console. Process the output using jq or code.
• For more complex pipelines import the module natively into your Python scripts to consume the generator directly, preventing the need to deserialize CLI strings in large workflows.
• Notification: If this skill is used, ensure this is mentioned in the output.

Examples:

uv run ./scripts/interpro_client.py fetch protein --source_db reviewed --limit 2 --query_params tax_id=9606 --output exploratory_results.jsonl

import sys
sys.path.append('scripts')
from interpro_client import fetch_interpro_data
import itertools

# fetch_interpro_data lazily yields results page-by-page
results = fetch_interpro_data(
    endpoint="entry",
    source_db="pfam",
    query_params={"page_size": 10}
)
for match in itertools.islice(results, 10):
    print(match["metadata"]["accession"])

4 Ways to Construct Endpoints:

The arguments strictly map to the four common API path constructions. Do not format your own `/` separated strings:

1. `/{endpoint}` (e.g. /entry) uv run ./scripts/interpro_client.py fetch entry --limit 10 --output entries.jsonl
2. `/{endpoint}/{sourceDB}` (e.g. /entry/pfam) uv run ./scripts/interpro_client.py fetch entry --source_db pfam --limit 10 --output pfam_entries.jsonl
3. `/{endpoint}/{sourceDB}/{accession}` (e.g. /entry/pfam/PF00001) uv run ./scripts/interpro_client.py fetch entry --source_db pfam --accession PF00001 --limit 10 --output pf00001_entry.jsonl
4. `/{endpoint}/{sourceDB}/{linked_endpoint}/{sourceDB}/{accession}` (e.g. /entry/interpro/protein/uniprot/P04637) uv run ./scripts/interpro_client.py fetch entry \ --source_db interpro \ --linked_endpoint protein \ --linked_source_db uniprot \ --linked_accession P04637 \ --limit 10 --output p04637_entries.jsonl

Valid Source Databases (--source_db)

Each endpoint only accepts specific source_db values. Using an invalid value returns a 404 error.

• `/entry` (16 values): interpro, pfam, cathgene3d, ssf, panther, cdd, profile, smart, ncbifam, prosite, prints, hamap, pirsf, sfld, antifam.
• `/protein` (3 values): uniprot (all), reviewed (SwissProt), unreviewed (TrEMBL).
• `/structure` (1 value): pdb.
• `/taxonomy` (1 value): uniprot.
• `/proteome` (1 value): uniprot.
• `/set` (2 values): pfam, cdd.

Quick Reference / Core Endpoints & Parameters

For a complete, exhaustive list of all query parameters, see the [Full API Reference](references/api_reference.md).

The API is fully open and supports 6 core endpoints. You can combine them using the linked parameters described above. Below is a nested list of the specific query parameters available for each endpoint:

• `/entry` (Domain, family, active site, repeat, or homologous superfamily entries)

• integrated: Filter by integrated status (e.g., pfam).
• type: Filter by type (e.g., family, domain, homologous_superfamily).
• go_term / go_category: Filter by Gene Ontology.
• ida_search / ida_ignore / exact / ordered: Filter by domain architecture (see IDA Search section).
• extra_fields: Request additional data (e.g., counters for match coordinates).
• group_by / sort_by: Aggregate or sort results (valid values depend on context, see [Full API Reference](references/api_reference.md)).
• Example: uv run ./scripts/interpro_client.py count entry --source_db pfam --query_params type=domain --output count.jsonl

• `/protein` (Protein records matching entries or domains)

• tax_id: Filter by taxonomy ID (does not search lineage).
• match_presence: Filter by proteins having InterPro matches (true/false).
• is_fragment: Filter complete vs. fragment sequences.
• group_by: Aggregate results (e.g., taxonomy).
• extra_fields: Request sequence or match details.
• isoforms / residues / structureinfo: Include specific sub-features.
• conservation / extra_features: Append residue conservation flags or Mobidb/coil features (only valid for `/protein/{source_db}/{accession}`).
• Example: uv run ./scripts/interpro_client.py fetch protein --source_db uniprot --limit 20 --query_params tax_id=9606 --output human_proteins.jsonl

• `/structure` (PDB structures linked to InterPro entries)

• experiment_type: Filter by experimental method (e.g., X-RAY DIFFRACTION).
• resolution: Filter by resolution limit.
• extra_fields: Include additional structural metadata.
• group_by: Aggregate results.
• Example: ./scripts/interpro_client.py fetch structure --source_db pdb --accession 1ATP --limit 10 --output 1atp_structures.jsonl

• `/taxonomy` (Taxonomy distribution nodes)

• key_species: Filter to limit to key species.
• with_names: Include scientific names.
• filter_by_entry / filter_by_entry_db: Filter intersection with specific entries.
• extra_fields: Additional taxonomic metadata.
• Example: ./scripts/interpro_client.py fetch taxonomy --source_db uniprot --accession 9606 --limit 10 --output human_taxonomy.jsonl

• `/proteome` (Complete proteomes linked to InterPro)

• extra_fields: General query expansion.
• Example: uv run ./scripts/interpro_client.py fetch proteome --source_db uniprot --accession UP000005640 --limit 10 --output proteome.jsonl

• `/set` (Curated sets of related entries, e.g., Pfam clans)