# InterProScan PyHMMER Metadata

This folder contains a standalone metadata map built from the local InterProScan
package at:

`/Users/jiachenyao/Downloads/interproscan-5.78-109.0`

Use it to annotate PyHMMER hits from InterProScan member HMM libraries with
signature descriptions, InterPro accessions, InterPro names/types, and links to
GO/pathway metadata when InterProScan has those mappings.

## Main Files

- `interproscan_5_78_109_pyhmmer_metadata.tsv`
  - Main lookup table.
  - One row per HMM model.
  - Best for joining against tabular PyHMMER output.

- `interproscan_5_78_109_pyhmmer_metadata.jsonl`
  - Same rows as the TSV, but one JSON object per line.
  - Useful if you want structured parsing in Python.

- `interproscan_5_78_109_pyhmmer_metadata.interpro_xrefs.json`
  - Detailed InterPro-level cross-references keyed by InterPro accession.
  - Contains GO terms and pathway mappings without duplicating them into every
    HMM row.

- `interproscan_5_78_109_pyhmmer_metadata.summary.json`
  - Counts by database and metadata status.

## TSV Join Columns

For PyHMMER annotation, first try matching your PyHMMER model name/accession to:

1. `model_id`
2. `hmm_name`
3. `hmm_accession`
4. `signature_accession`

The safest display description for a hit is usually:

1. `interpro_name` and `interpro_description`, when `interpro_accession` is present
2. for PIRSR, `signature_description` plus the `pirsr_*` rule columns
3. otherwise `signature_name` and `signature_description`
4. otherwise `hmm_description`

The `metadata_status` column tells how much annotation was found:

- `signature_and_interpro`: model maps to both a member-database signature and an
  InterPro entry.
- `signature_only`: model has member-database signature metadata, but no InterPro
  entry in the local package.
- `missing`: model was found in the HMM file, but no local metadata row was found
  with the current normalization rules.
- `pirsr_rule_and_interpro`: PIRSR model was annotated from `sr_uru.json` and
  also mapped to an InterPro entry.
- `pirsr_rule`: PIRSR model was annotated from `sr_uru.json`, but did not map
  to an InterPro entry.

## Included Databases

The table includes these InterProScan member HMM databases:

- AntiFam
- CATH-FunFam
- CATH-Gene3D
- NCBIFAM
- PANTHER
- Pfam
- PIRSF
- PIRSR
- SFLD
- SUPERFAMILY

SMART is also included for completeness, but `pyhmmer_compatible` is `false`
because this InterProScan package stores SMART as HMMER2 models.

## Important ID Normalization

Some HMM model names are not identical to InterProScan signature accessions.
The build script normalizes common cases:

- Pfam: removes version suffixes, e.g. `PF00001.25` to `PF00001`
- NCBIFAM: removes version suffixes, e.g. `NF000004.1` to `NF000004`
- FunFam: converts names like `1.10.10.10-FF-000001` to
  `G3DSA:1.10.10.10:FF:000001`
- Gene3D: uses InterProScan's `model_to_family_map.tsv`
- SUPERFAMILY: uses InterProScan's `model.tab`
- PANTHER: maps model names to family-level accessions such as `PTHR32401`

## Caveats

- Not every InterProScan member-database signature is integrated into InterPro,
  so blank `interpro_accession` values are expected.
- PIRSR rows are annotated from `data/pirsr/2025_05/sr_uru.json`. These
  descriptions are rule-level: trigger family/InterPro accession, taxonomic
  scope, source model, and feature rules such as active sites, binding sites,
  metal-binding sites, or disulfide bonds.
- CATH-FunFam has many rows with signature-level model IDs but no InterPro
  accession, which is normal for this package.
- SMART is not suitable for PyHMMER searches from this package unless converted
  or replaced with a HMMER3-compatible source.

## PIRSR Rule Columns

The PIRSR-specific columns are populated only for PIRSR rows:

- `pirsr_rule_accession`
- `pirsr_trigger_database` and `pirsr_trigger_accession`
- `pirsr_trigger_name` and `pirsr_trigger_description`
- `pirsr_scope`
- `pirsr_feature_count`
- `pirsr_feature_labels`
- `pirsr_feature_examples`
- `pirsr_feature_model`
- `pirsr_feature_from`

## Rebuild

Run the builder from the `interproscan_hmm` folder:

```bash
python3 scripts/build_interpro_pyhmmer_metadata.py \
  --interproscan-dir /Users/jiachenyao/Downloads/interproscan-5.78-109.0 \
  --output-prefix metadata/interproscan_5_78_109_pyhmmer_metadata \
  --include-smart
```