# DTP Explain: `dtp_uniprot_relationships`

## 1. Data source and pipeline role

- `data_source.name`: `uniprot_relationships`
- `source_system`: `UniProt`
- source URL in seed: `not_applicable`
- format in seed: `not_applicable`

Pipeline role:
- relationship-only DTP
- consumes staging generated by `dtp_uniprot`
- inserts UniProt-derived links into `EntityRelationship`

Operational dependency:
- run this only after master datasets are loaded, because relationship
  endpoints are resolved by alias lookup against existing entities.

## 2. Extract

Behavior:
- no extraction
- returns success + informational message

Reason:
- raw source data is extracted by `dtp_uniprot`

## 3. Transform

Behavior:
- no transformation
- returns success + informational message

Reason:
- relationship staging is produced by `dtp_uniprot` transform

## 4. Load

Input file:
- `<processed_dir>/<source_system>/uniprot/relationship_data.parquet`
- note: reads from parent source folder `uniprot`

Main goal:
- resolve source/target entities and relationship type IDs
- insert rows into `EntityRelationship`

### 4.1 Preload maps

Group map:
- loads all `EntityGroup`
- maps `group_name.lower() -> group_id`

Relationship type map:
- loads all `EntityRelationshipType`
- maps `code.lower() -> id`

DataFrame mappings:
- `source_group_id` from `source_type`
- `target_group_id` from `target_type`
- `relation_type_id` from `relation_type`

### 4.2 Insert flow

Before insertion:
- deletes all existing relationships from current data source
  (`EntityRelationship.data_source_id = self.data_source.id`)

Per row:
1. split `target_id` by `|`
2. resolve source entity by exact `EntityAlias.alias_value`, active entity, and source group
3. resolve target entity by exact `EntityAlias.alias_value`, active entity, and target group
4. insert relationship:
   - `entity_1_id`, `entity_2_id`
   - `entity_1_group_id`, `entity_2_group_id`
   - `relationship_type_id`
   - `data_source_id`, `etl_package_id`

Commit:
- commits batch at end

## 5. Rejections and diagnostics

Rows not loaded:
- rows with missing required mapped fields
- rows where source/target entity cannot be resolved (or group mismatch)

Output for rejected rows:
- `<processed_dir>/<source_system>/uniprot/relationship_data_not_loaded.csv`

Operational behavior:
- switches DB to write mode
- drops/creates entity index group around load

## 6. Dependency checklist (recommended)

Before running `uniprot_relationships`, ensure at least:
1. `uniprot` completed (to produce relationship staging)
2. target master domains loaded:
   - GO (`Gene Ontology`)
   - Pathways
   - Genes
   - Transcriptomics (if used by RefSeq links)
3. relationship types expected by file are present in `EntityRelationshipType`

