BRCA Differential Expression And KEGG Enrichment Analysis
Domain: life_sciences — Genomics & Sequence Analysis

Summary: Analyze a staged BRCA count matrix and metadata on Ubuntu, run pydeseq2 differential expression for tumor versus normal, and generate paired KEGG enrichment outputs.

Task prompt:
You are a bioinformatics analyst working on a Linux VM.

Task directory:
- `base`

Visible input files:
- Count matrix: `base/input/BRCA_selected_samples_counts.tsv`
- Sample metadata: `base/input/BRCA_selected_samples_metadata.tsv`
- Analysis spec: `base/input/analysis_spec.json`
- Output contract: `base/input/output_contract.json`
- Detailed task brief: `base/input/task_description.txt`
- Gene-id to gene-symbol map: `base/input/gene_id_gene_symbol_map.tsv`
- Enrichment config: `base/input/enrichment_config.json`
- Runtime dependency manifest: `base/input/runtime_env/pyproject.toml`
- Requirements file: `base/input/requirements.txt`

What you must do:
1. Read the count matrix, metadata, analysis spec, and output contract first.
2. Use the metadata `condition` column to compare `tumor` against `normal`.
3. Run differential gene expression analysis with `pydeseq2` using the design formula `~ batch + condition`.
4. Use `base/input/gene_id_gene_symbol_map.tsv` to populate the required gene-symbol output fields.
5. Classify each gene as `upregulated`, `downregulated`, or `no significant` using the benchmark rule:
   - `log2FoldChange > 1` and `padj < 0.05` for `upregulated`
   - `log2FoldChange < -1` and `padj < 0.05` for `downregulated`
   - otherwise `no significant`
6. Read `base/input/enrichment_config.json` and run KEGG enrichment separately on the upregulated and downregulated gene sets with `gseapy`.
7. Write exactly these files under `base/output`:
   - `BRCA_deseq2_results.tsv`
   - `BRCA_upregulated_genes_kegg_enrichment.tsv`
   - `BRCA_downregulated_genes_kegg_enrichment.tsv`

Helpful notes:
- The first column of the count matrix is `gene_id`.
- The first column of the metadata file is `sample_id`.
- The sample order in the metadata matches the count-matrix sample columns exactly.
- The benchmark standardizes the enrichment target as `KEGG_2021_Human` on `Human`.
- Outbound network access to Enrichr is allowed and expected for the enrichment step.
- You may install the Python dependencies without modifying `input/`, for example:
  `uv venv .venv && uv pip install --python .venv/bin/python -r base/input/requirements.txt`

Do not modify files under `input/`.
Do not write outputs anywhere except `base/output`.
Do not ask for confirmation. Execute directly.


Required actions:
Read the staged BRCA count matrix, metadata, analysis spec, and output contract.
Install the required Python packages into an agent-owned environment from the staged manifest.
Run pydeseq2 with the explicit design formula `~ batch + condition` to compare `tumor` against `normal`.
Populate the DEG `gene` column from the visible gene-id to gene-symbol map.
Classify genes with the benchmark significance rule based on `log2FoldChange` and `padj`.
Run `gseapy.enrichr` separately for the upregulated and downregulated gene sets against `KEGG_2021_Human`.
Write the DEG result TSV and both KEGG enrichment TSVs under `output/`.

Software: Python
pydeseq2
gseapy

Input files:
name: BRCA_selected_samples_counts.tsv
format: TSV
description: BRCA count matrix with leading `gene_id` column.
name: BRCA_selected_samples_metadata.tsv
format: TSV
description: Sample metadata with leading `sample_id` column and `condition` labels.
name: analysis_spec.json
format: JSON
description: Visible analysis contract for contrast and significance rule.
name: output_contract.json
format: JSON
description: Visible output schema for the DEG and KEGG enrichment tables.
name: task_description.txt
format: TXT
description: Staged task brief aligned with the benchmark prompt.
name: gene_id_gene_symbol_map.tsv
format: TSV
description: Visible gene-id to gene-symbol mapping in the public count-matrix order.
name: enrichment_config.json
format: JSON
description: Visible enrichment target configuration for `KEGG_2021_Human` on `Human`.
name: runtime_env/pyproject.toml
format: TOML
description: Pinned runtime dependency manifest for the agent's own environment.
name: requirements.txt
format: TXT
description: Convenience requirements mirror of the staged runtime manifest.