# Scripts

This directory contains various scripts for author disambiguation and benchmarking.

## Data Processing Scripts

### `add_author_ids.py`
Processes the EMBO membership candidates dataset to add OpenAlex Author IDs by matching authors from work IDs.

**Usage:**
```bash
python scripts/add_author_ids.py
```

**Input:** `data/embo_membership_candidates_with_work_ids.xlsx`  
**Output:** `data/embo_membership_candidates_with_author_ids.xlsx`

### `clean_embo_members.py`
Cleans the EMBO members dataset by filtering and removing duplicates.

**Filters applied:**
1. Remove rows where ELECTED = 'no' (keeps 'yes' and empty/NaN for older members)
2. Remove rows with missing first name or last name

**Usage:**
```bash
python scripts/clean_embo_members.py --input data/emboplanet_allmem_2026-01-07.xlsx
```

**Output:** `data/emboplanet_allmem_cleaned_YYYY-MM-DD.xlsx`

### `get_all_embo_members_openalex_ids.py`
Finds OpenAlex IDs for all EMBO members using a hybrid strategy:

**Strategy:**
1. **ORCID available:** Use agent with ORCID + verify with publications
2. **Publications available:** Use agent with publications as context + extract work IDs
3. **Otherwise:** Use agent with name + affiliations + keywords

**Usage:**
```bash
# Process first 10 members (for testing)
python scripts/get_all_embo_members_openalex_ids.py \
    --input data/emboplanet_allmem_cleaned_2026-01-07.xlsx \
    --max-members 10 \
    --save-every 5

# Process all members
python scripts/get_all_embo_members_openalex_ids.py \
    --input data/emboplanet_allmem_cleaned_2026-01-07.xlsx \
    --save-every 10

# Resume from a specific index
python scripts/get_all_embo_members_openalex_ids.py \
    --input data/emboplanet_allmem_cleaned_2026-01-07.xlsx \
    --start-from 100 \
    --save-every 10
```

**Features:**
- Incremental saving (every N members)
- Resumable processing
- Captures both work IDs and author IDs
- Assigns certainty flags for quality control

**Output:**
- Excel file: `data/emboplanet_allmem_with_openalex_ids.xlsx`
- JSON file: `output/embo_members_openalex_results.json`

### `get_embo_members_openalex_ids.py`
Earlier version of the EMBO members processing script with a tiered strategy.

**Note:** `get_all_embo_members_openalex_ids.py` is the recommended version with improved hybrid strategy.

## Benchmark Scripts

### `run_benchmark.py`
Main benchmark script that evaluates the disambiguation agent against ground truth data.

**Features:**
- Compares against two ground truth sources:
  - `matched_author_openalex_id` (from work matching)
  - `member_author_ids` (pre-existing IDs)
- Evaluates accuracy at ranks 1-5
- Provides detailed failure analysis
- Generates comparison report

**Usage:**
```bash
# Run benchmark on 100 random authors
python scripts/run_benchmark.py \
    --input data/embo_membership_candidates_with_author_ids.xlsx \
    --n 100

# Run benchmark with specific min match score
python scripts/run_benchmark.py \
    --input data/embo_membership_candidates_with_author_ids.xlsx \
    --n 100 \
    --min-match-score 0.9
```

**Output:** `output/benchmark_YYYYMMDD_HHMMSS.json`

See [BENCHMARK_GUIDE.md](../BENCHMARK_GUIDE.md) for detailed instructions.

### `run_context_benchmarks.py`
Evaluates disambiguation performance with different context levels to understand the impact of contextual information.

**Benchmark Types:**
1. **No Context:** Only first name, last name, affiliation
2. **Light Context:** First name, last name, affiliation + abstract (proxy for keywords/subject areas)

**Usage:**
```bash
# Run both benchmarks with 50 samples each
python scripts/run_context_benchmarks.py --n-samples 50

# Custom input file
python scripts/run_context_benchmarks.py \
    --input data/embo_membership_candidates_with_author_ids.xlsx \
    --n-samples 50 \
    --output-dir output
```

**Output:**
- `output/benchmark_no_context_YYYYMMDD_HHMMSS.json`
- `output/benchmark_keywords_YYYYMMDD_HHMMSS.json`
- `output/benchmark_comparison_YYYYMMDD_HHMMSS.json`

**Use Cases:**
- Understand how much context improves disambiguation
- Evaluate agent performance with minimal information
- Compare effectiveness of different context types

## Common Arguments

Most scripts support:
- `--input`: Input file path
- `--output`: Output file path
- `--help`: Show detailed help message

## Environment Setup

Before running any scripts, ensure you have:
1. Activated the virtual environment: `source .venv/bin/activate`
2. Set the OpenAlex API key: `export OPENALEX_API_KEY="your_email@example.com"`
3. Set the Anthropic API key: `export ANTHROPIC_API_KEY="your_api_key"`

## Notes

- All scripts save progress incrementally to handle interruptions
- Most scripts can be resumed from where they left off
- JSON outputs contain detailed results for analysis
- Excel outputs are enriched with disambiguation results
