# Task Brief — Computation Track
## GLMP Validation: RegulonDB Cross-Reference Analysis
### Estimated time: 10–11 hours over 3 weeks
### Supervised by: Prof. Konstantinos Krampis, Hunter College CUNY

---

## Your task in one sentence

Write a Python script that compares our computationally predicted
transcription factor binding sites against RegulonDB's experimentally
validated binding sites, and produce a structured report documenting
what matches, what doesn't, and what might explain any discrepancies.

---

## Background

The GLMP DNA Decoder uses FIMO motif scanning to identify where
transcription factors bind in regulatory DNA sequences. FIMO scans
a promoter sequence against a database of known binding motifs
(JASPAR) and reports high-confidence matches.

RegulonDB is an independently curated database maintained by the
Collado-Vides lab at UNAM (regulondb.ccg.unam.mx). It contains
experimentally validated transcription factor binding sites, promoter
locations, and regulatory interactions for E. coli K-12 — based on
decades of published experimental data, not computational prediction.

Your job is to check whether our FIMO predictions agree with what
RegulonDB says should be there.

---

## Files you need

**Our decoder output (in decode-results/):**
- `ecoli_lac_operon_logic.json`
- `ecoli_ara_operon_logic.json`
- `ecoli_trp_operon_logic.json`

Each JSON file contains:
- `binding_sites` — array of predicted binding sites with:
  - `tf` — transcription factor name
  - `position` — genomic coordinate (NC_000913.3)
  - `strand` — + or -
  - `q_value` — statistical confidence
  - `matched_sequence` — the actual DNA sequence matched

**RegulonDB flat files (in regulondb-v14/):**
- `TF-RISet.tsv` — the primary file you need
- `TFSet.tsv` — transcription factor reference

See `regulondb-v14/README-regulondb.txt` for column descriptions.

**Annotation review (for context):**
- `annotation-review/lac-operon-annotation-review.html`
  Open in a browser — explains the biology and what we expect to find.

---

## What to build

### Step 1 — Parse the decoder output (1–2 hours)

Write a Python script that reads each decode result JSON and extracts:
- Circuit name
- Each predicted binding site (TF, position, strand, q-value)

```python
import json

with open('decode-results/ecoli_lac_operon_logic.json') as f:
    result = json.load(f)

binding_sites = result.get('binding_sites', [])
for site in binding_sites:
    print(site['tf'], site['position'], site['q_value'])
```

### Step 2 — Parse the RegulonDB regulatory interaction file (2–3 hours)

`TF-RISet.tsv` is tab-delimited. Key columns:
- Transcription factor name
- Gene regulated
- Left position (genomic)
- Right position (genomic)
- Strand
- Evidence type (experimental vs computational)

Filter to only experimentally validated sites (evidence type contains
"Confirmed" or similar — check the file header for exact values).

Build a lookup structure: for each TF, which positions are validated?

### Step 3 — Overlap analysis (2–3 hours)

For each of our predicted binding sites, check:

**True positive:** our prediction overlaps a RegulonDB validated site
for the same TF within a tolerance window (±20 bp is reasonable
given promoter scanning resolution).

**False positive:** our prediction has no corresponding RegulonDB
entry for that TF near that position.

**False negative:** RegulonDB has a validated site for a key TF
that our decoder missed entirely.

Define "overlap" as: same TF name, positions within ±20 bp,
same chromosome (NC_000913.3).

### Step 4 — Report (2 hours)

For each of the three circuits, report:
- How many of our predicted sites were confirmed by RegulonDB?
- How many were not found in RegulonDB?
- What does RegulonDB have that we missed?
- For each discrepancy: what might explain it?
  (e.g. TF absent from JASPAR, coordinate shift, different strain)

Use the report template (`report-template.md`) for structure.

---

## Things to watch for

**TF name mismatches:** JASPAR uses different TF naming conventions
than RegulonDB. For example, CRP in RegulonDB may appear as CAP
or catabolite activator protein elsewhere. Check for synonyms.

**Coordinate systems:** Our decoder uses NC_000913.3 (E. coli K-12
MG1655 GenBank accession). RegulonDB uses the same reference genome
but column definitions may differ slightly — check the file header.

**AraC is missing from JASPAR:** Our ara operon decode shows
INSUFFICIENT_EVIDENCE for AraC binding because AraC is not in the
JASPAR database (it's prokaryote-specific). This is expected and
documented. Note it in your report but it is not an error.

**Evidence levels:** RegulonDB distinguishes between experimentally
confirmed sites and computationally predicted ones. Focus your
comparison on the experimentally confirmed sites — those are the
ground truth.

---

## Deliverable

A validation report following the template in `report-template.md`,
submitted as a Google Doc or PDF to gwelz@gc.cuny.edu.

Include your analysis script as an appendix or separate file.

Questions: gwelz@gc.cuny.edu