ExperimentalInterpretationAgent & InterpretExperimentalResultsSkill

Version: 1.0.0 Category: Analysis / Experimental Status: ✅ Production Ready

Overview

The ExperimentalInterpretationAgent orchestrates the generation of evidence-based biological interpretations from experimental growth data. It produces three publication-ready documents:

Main Interpretation Report - Comprehensive biological interpretation with recommendations
Evidence Companion File - Data snippets and literature citations
Citation-Based Report - Interpretation with inline [E#] and [L#] references

These documents are designed for:

Scientific documentation and record-keeping
Publication preparation
Grant proposals and progress reports
Communicating results to stakeholders

Architecture

Components

ExperimentalInterpretationAgent (Orchestrator)
    ↓
InterpretExperimentalResultsSkill (Core Logic)
    ↓
Experimental Analysis Data (Input)
    ↓
Three Interpretation Reports (Output)

Agent Responsibilities:

Directory discovery (auto-find analysis and clustering results)
Data validation (check required files exist)
Workflow orchestration (execute skill, save metadata)
User feedback (progress messages, summary statistics)

Skill Responsibilities:

Load experimental data (control stats, top conditions, clustering)
Detect boundary effects (identify peaks at design space limits)
Generate evidence data (structured data snippets + literature refs)
Write reports (three output formats)

Usage

Quick Start

from microgrowagents.agents.analysis import ExperimentalInterpretationAgent

# Initialize agent with version identifier
agent = ExperimentalInterpretationAgent(source_version="v10")

# Run the workflow
result = agent.run()

# Access generated files
print(result['interpretation_report'])
print(result['evidence_report'])
print(result['citation_report'])

Convenience Function

from microgrowagents.agents.analysis import run_interpretation

# One-line execution
result = run_interpretation(source_version="v10")

Using the Skill Directly

from microgrowagents.skills.analysis.experimental import InterpretExperimentalResultsSkill

skill = InterpretExperimentalResultsSkill()

result = skill.execute(
    source_version="v10",
    organism_name="Methylorubrum extorquens AM-1",
    include_literature=True,
)

Configuration Options

Agent Parameters

agent = ExperimentalInterpretationAgent(
    source_version="v10",              # Version identifier for auto-discovery
    analysis_dir=None,                 # Override auto-discovery with direct path
    clustering_dir=None,               # Override auto-discovery for clustering
    output_dir=None,                   # Output directory (defaults to analysis_dir)
    organism_name="Methylorubrum extorquens AM-1",  # Organism name
    include_literature=True,           # Include literature citations
    base_dir=None,                     # Base directory (defaults to cwd)
)

Skill Parameters

result = skill.execute(
    source_version="v10",              # Required if analysis_dir not provided
    analysis_dir=None,                 # Direct path to analysis results
    clustering_dir=None,               # Direct path to clustering results
    output_dir=None,                   # Output directory
    organism_name="Methylorubrum extorquens AM-1",
    include_literature=True,           # Include literature evidence
)

Input Requirements

Directory Structure

The agent expects the following directory structure (auto-discovered by version):

outputs/
  └── {source_design_id}_experimental_analysis/
      ├── *control_statistics.tsv          # Required
      ├── *replicate_statistics.tsv        # Required
      ├── *processed_data_normalized.tsv   # Optional
      └── ...
  └── {source_design_id}_experimental_analysis_clustering/
      ├── *cluster_descriptions_growth.txt # Optional
      └── ...

Example:

outputs/plate_designs_v10_maxprooptblock_long__results_experimental_analysis/
outputs/plate_designs_v10_maxprooptblock_long__results_experimental_analysis_clustering/

Required Data Files

Control Statistics TSV (*control_statistics.tsv)
- Control well statistics (mean, std, n)
- OD600 measurements at each timepoint
Replicate Statistics TSV (*replicate_statistics.tsv)
- Per-condition statistics
- Columns: Condition_ID, max_OD600_norm, Total_Phosphate_mM_first, (NH4)2SO4_mM_first, etc.

Optional Data Files

Cluster Descriptions (*cluster_descriptions_growth.txt)
- K-means clustering results
- Cluster summaries with mean nutrient levels

Output Files

1. INTERPRETATION_REPORT.md

Purpose: Main interpretation report without citations (clean, readable)

Content:

Executive Summary
Results Summary (quality, growth distribution)
Factor-by-Factor Interpretation (P, N, C sources)
Metabolic Insights (carbon utilization, stoichiometry)
Evidence-Based Hypotheses (testable predictions)
Recommendations for Next Design
Optimal Media Formulation

Format: Markdown with tables, lists, structured sections

Example:

## Executive Summary

**Key Finding:** Growth is nutrient-limited with peaks at boundaries.

## Factor-by-Factor Interpretation

### 1. Phosphate (K₂HPO₄ + NaH₂PO₄)

**v10 Range:** 0.675 - 49.881 mM
**Optimal Growth:** 49.27 mM (near upper boundary)

**Biological Interpretation:**
- Phosphate is limiting at concentrations below 50 mM
...

2. INTERPRETATION_EVIDENCE.md

Purpose: Evidence companion file with data snippets and literature references

Content:

Data Evidence (E1-E#):
- E1: Dataset Quality and Completeness
- E2: Top Performing Conditions (table with nutrient compositions)
- E3: Clustering Analysis (growth patterns)
- E4: Boundary Effects (optimal concentrations)
- E5+: Additional evidence as needed
Literature Evidence (L1-L#):
- L1: M. extorquens metabolism (Chistoserdova et al. 2003)
- L2: PQQ-dependent MDH (Anthony & Williams 2003)
- L3: Rare earth elements (Pol et al. 2014)
- L4+: Additional references

Format: Markdown with code blocks, tables, citations with DOIs

Example:

### E2. Top Performing Conditions

**Top 10 conditions by maximum normalized OD600:**

| Rank | Condition | OD600 | Phosphate (mM) | ... |
|------|-----------|-------|----------------|-----|
| 1    | MPOB_040  | 0.9484| 45.38          | ... |
...

### L1. Methylorubrum extorquens AM-1 Metabolism

**Citation:** Chistoserdova et al. (2003)
**DOI:** [10.1128/JB.185.10.2980-2987.2003](https://doi.org/...)
**Key Finding:** M. extorquens possesses complete methylotrophic pathways

3. INTERPRETATION_REPORT_evidence.md

Purpose: Citation-based interpretation with inline evidence references

Content: Same structure as INTERPRETATION_REPORT.md but with:

Inline citations: [E1], [E2], [L1], [L2], etc.
Bibliography section at end
Complete evidence references

Format: Markdown with inline citations and bibliography

Example:

## Executive Summary

**Key Finding:** Growth is nutrient-limited [E4], with peaks at boundaries [E4, L9].

...

### 1. Phosphate

**Biological Interpretation:**
- Phosphate is limiting below 50 mM [L4]
- M. extorquens has high phosphate demand [L1, L4]

**Evidence for Higher Range:**
- Boundary effect: peak at 49.27 mM (99% of 49.88 mM) [E4, L9]

...

## Bibliography

### Data Evidence Sources

**E1.** Dataset Quality and Completeness
Source: v10_maxprooptblock_long__results_control_statistics.tsv

**E4.** Boundary Effects
Source: DesignRecommendationAgent analysis

### Literature Evidence Sources

**L1.** Chistoserdova et al. (2003). Methylotrophy in M. extorquens AM1
DOI: 10.1128/JB.185.10.2980-2987.2003

4. interpretation_metadata.json

Purpose: Execution metadata for tracking and reproducibility

Content:

{
  "agent": "ExperimentalInterpretationAgent",
  "version": "1.0.0",
  "execution_timestamp": "2026-02-12T19:19:29.299104",
  "source_version": "v10",
  "organism": "Methylorubrum extorquens AM-1",
  "directories": {
    "analysis": "/path/to/analysis",
    "clustering": "/path/to/clustering",
    "output": "/path/to/output"
  },
  "outputs": {
    "interpretation_report": "/path/to/INTERPRETATION_REPORT.md",
    "evidence_report": "/path/to/INTERPRETATION_EVIDENCE.md",
    "citation_report": "/path/to/INTERPRETATION_REPORT_evidence.md"
  },
  "summary": {
    "n_conditions": 10,
    "n_clusters": 6,
    "boundary_effects": 3,
    "evidence_snippets": 4,
    "literature_refs": 3
  }
}

Workflow Details

Step 1: Directory Discovery

Auto-discovery (if source_version provided):

# Searches for directories matching pattern
outputs/*{source_version}*experimental_analysis/
outputs/*{source_version}*experimental_analysis_clustering/

# Example matches for source_version="v10":
outputs/plate_designs_v10_maxprooptblock_long__results_experimental_analysis/
outputs/experimental_analysis_v10/  # Fallback to old naming

Direct paths (if analysis_dir provided):

agent = ExperimentalInterpretationAgent(
    analysis_dir="outputs/experimental_analysis_v10"
)

Step 2: Data Loading

Control Statistics:

Loads *control_statistics.tsv
Extracts mean, std, n for OD600 at each timepoint
Used for data quality assessment

Top Conditions:

Loads *replicate_statistics.tsv
Sorts by max_OD600_norm descending
Extracts top 10 performers with nutrient compositions

Clustering Data:

Loads *cluster_descriptions_growth.txt
Parses cluster summaries
Extracts growth performance and nutrient profiles per cluster

Boundary Effects:

Currently uses placeholder data
Future: integrate with DesignRecommendationAgent for real boundary detection

Step 3: Evidence Generation

Data Evidence Snippets (E1-E#):

E1: Control statistics with quality metrics
E2: Top 10 conditions table
E3: Clustering results (if available)
E4: Boundary effects with optimal concentrations

Literature Evidence (L1-L#):

Template citations with DOIs
Key findings relevant to interpretation
User can customize/expand literature references

Evidence Structure:

{
    "data_evidence": [
        {"id": "E1", "title": "...", "type": "...", "data": {...}},
        {"id": "E2", "title": "...", "type": "...", "data": [...]},
    ],
    "literature_evidence": [
        {"id": "L1", "citation": "...", "doi": "...", "key_finding": "..."},
        {"id": "L2", "citation": "...", "doi": "...", "key_finding": "..."},
    ]
}

Step 4: Report Writing

Three parallel writes:

INTERPRETATION_REPORT.md (no citations)
- Clean, readable format
- For stakeholders who want biological insights without citation clutter
INTERPRETATION_EVIDENCE.md (evidence file)
- Detailed evidence snippets
- Complete data tables and literature references
- For researchers who want to verify claims
INTERPRETATION_REPORT_evidence.md (with citations)
- Inline [E#] and [L#] references
- Bibliography at end
- For publication preparation

Integration with Other Agents

Upstream: ExperimentalAnalysisAgent

# 1. Run experimental analysis (generates data files)
from microgrowagents.agents.analysis import ExperimentalAnalysisAgent

analysis_agent = ExperimentalAnalysisAgent(source_version="v10")
analysis_result = analysis_agent.run()

# 2. Run interpretation (uses analysis outputs)
from microgrowagents.agents.analysis import ExperimentalInterpretationAgent

interp_agent = ExperimentalInterpretationAgent(source_version="v10")
interp_result = interp_agent.run()

Downstream: DesignRecommendationAgent

# 1. Generate interpretation (understand biology)
interp_result = run_interpretation(source_version="v10")

# 2. Generate recommendations (design next experiment)
from microgrowagents.agents.analysis import DesignRecommendationAgent

rec_agent = DesignRecommendationAgent(source_version="v10")
recommendations = rec_agent.generate_recommendations()

Customization

Adding Custom Literature References

Edit the _generate_evidence_data method in the skill:

literature_evidence = [
    {
        "id": "L1",
        "title": "Your Title",
        "citation": "Author et al. (2020)",
        "doi": "10.xxxx/xxxxx",
        "key_finding": "Description of key finding",
    },
    # Add more...
]

Modifying Interpretation Content

Override the _write_interpretation_report method:

class CustomInterpretationSkill(InterpretExperimentalResultsSkill):
    def _write_interpretation_report(self, output_file, evidence_data, ...):
        # Custom report generation logic
        pass

Changing Output Format

Subclass and override writer methods:

class JSONInterpretationSkill(InterpretExperimentalResultsSkill):
    def _write_evidence_file(self, output_file, evidence_data, ...):
        # Write JSON instead of Markdown
        import json
        with open(output_file.with_suffix('.json'), 'w') as f:
            json.dump(evidence_data, f, indent=2)

Testing

Unit Tests

# Run tests for skill and agent
uv run pytest tests/agents/test_experimental_interpretation_agent.py -v

Manual Testing

# Test with v10 data
from microgrowagents.agents.analysis import run_interpretation

result = run_interpretation(source_version="v10")

# Verify files exist
from pathlib import Path
assert Path(result['interpretation_report']).exists()
assert Path(result['evidence_report']).exists()
assert Path(result['citation_report']).exists()

Skill Metadata

metadata = InterpretExperimentalResultsSkill().get_metadata()

{
    "name": "interpret-experimental-results",
    "description": "Generate evidence-based biological interpretation",
    "category": "analysis/experimental",
    "version": "1.0.0",
    "dependencies": ["analyze-od600"],
    "triggers": [
        "interpret results",
        "biological interpretation",
        "explain experimental data",
        "analyze growth patterns",
        "generate interpretation report",
    ],
    "workflow_stage": "review",
    "supports_parallel": True,
    "tags": ["interpretation", "biology", "evidence", "documentation"],
}

Future Enhancements

Planned Features

Real Boundary Detection Integration
- Replace placeholder boundary effects with DesignRecommendationAgent results
- Automatically detect peaks at design space limits
Time-Course Analysis
- Distinguish growth rate vs final yield
- Identify fast vs slow growers
- Lag phase analysis
Statistical Significance Testing
- ANOVA for factor effects
- Tukey HSD for pairwise comparisons
- Confidence intervals for optima
Interactive Visualization
- Generate Plotly/Altair interactive plots
- Embed in HTML report
- Drill-down to condition details
Multi-Organism Support
- Compare interpretation across organisms
- Identify organism-specific vs universal patterns
- Phylogenetic context
Automated Literature Search
- Use PubMed API to fetch relevant papers
- Extract key findings with LLM
- Automatically populate literature evidence

Troubleshooting

Error: "Could not locate analysis directory"

Cause: Auto-discovery failed (wrong version or missing directory)

Solution:

# Use direct path instead
agent = ExperimentalInterpretationAgent(
    analysis_dir="outputs/your_analysis_directory"
)

Error: "Required data file not found: *control_statistics.tsv"

Cause: Missing required data file

Solution: Run experimental analysis first:

from microgrowagents.agents.analysis import ExperimentalAnalysisAgent
analysis_agent = ExperimentalAnalysisAgent(source_version="v10")
analysis_agent.run()

Warning: "Clustering directory not found"

Cause: Clustering analysis was not run (optional)

Impact: Report will not include clustering evidence (E3)

Solution (optional): Run clustering analysis or proceed without it

References

Related Agents:
- ExperimentalAnalysisAgent (upstream data provider)
- DesignRecommendationAgent (downstream consumer)
Related Skills:
- analyze-od600 (dependency)
- recommend-next-design (downstream)
Documentation:
- DESIGN_RECOMMENDATION_AGENT.md
- NAMING_CONVENTIONS.md

Document Status: ✅ Production Ready Last Updated: 2026-02-12 Author: MicroGrowAgents Version: 1.0.0

FilesExpand file tree

EXPERIMENTAL_INTERPRETATION_AGENT.md

Latest commit

History

EXPERIMENTAL_INTERPRETATION_AGENT.md

File metadata and controls

ExperimentalInterpretationAgent & InterpretExperimentalResultsSkill

Overview

Architecture

Components

Usage

Quick Start

Convenience Function

Using the Skill Directly

Configuration Options

Agent Parameters

Skill Parameters

Input Requirements

Directory Structure

Required Data Files

Optional Data Files

Output Files

1. INTERPRETATION_REPORT.md

2. INTERPRETATION_EVIDENCE.md

3. INTERPRETATION_REPORT_evidence.md

4. interpretation_metadata.json

Workflow Details

Step 1: Directory Discovery

Step 2: Data Loading

Step 3: Evidence Generation

Step 4: Report Writing

Integration with Other Agents

Upstream: ExperimentalAnalysisAgent

Downstream: DesignRecommendationAgent

Customization

Adding Custom Literature References

Modifying Interpretation Content

Changing Output Format

Testing

Unit Tests

Manual Testing

Skill Metadata

Future Enhancements

Planned Features

Troubleshooting

Error: "Could not locate analysis directory"

Error: "Required data file not found: *control_statistics.tsv"

Warning: "Clustering directory not found"

References