Tutorials
Hypothesis Library

Hypothesis Library Tutorial

The Hypothesis Library lets you save, organize, and reuse hypotheses across experiments. This tutorial covers managing your hypothesis collection.

Why Use the Hypothesis Library?

  • Reuse hypotheses across multiple experiments
  • Track hypothesis history from generation to validation
  • Organize research by experiment type or project
  • Connect to Edison for AI-generated hypotheses

Creating a Hypothesis

From the API

curl -X POST https://api.litmus.science/hypotheses \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Compound X antibacterial activity",
    "statement": "Compound X inhibits E. coli growth with MIC ≤ 32 μg/mL",
    "null_hypothesis": "Compound X has no antibacterial activity against E. coli",
    "experiment_type": "MIC_MBC_ASSAY"
  }'

With an Intake Draft

Pre-fill experiment parameters when converting to an experiment:

{
  "title": "Compound X antibacterial activity",
  "statement": "Compound X inhibits E. coli growth with MIC ≤ 32 μg/mL",
  "experiment_type": "MIC_MBC_ASSAY",
  "intake_draft": {
    "compliance": { "bsl": "BSL1" },
    "mic_mbc_assay": {
      "target_organisms": ["Escherichia coli"],
      "test_compounds": [
        {"name": "Compound X", "concentrations_ug_ml": [0.5, 1, 2, 4, 8, 16, 32]}
      ]
    }
  }
}

Hypothesis Lifecycle

DRAFT → USED → ARCHIVED
StatusDescriptionCan Edit?
DRAFTWork in progressYes
USEDConnected to an experimentNo
ARCHIVEDSoft-deletedNo

Listing Your Hypotheses

Basic Listing

curl https://api.litmus.science/hypotheses \
  -H "Authorization: Bearer YOUR_TOKEN"

Filtering

# By status
curl "https://api.litmus.science/hypotheses?status=DRAFT" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# By experiment type
curl "https://api.litmus.science/hypotheses?experiment_type=MIC_MBC_ASSAY" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# Search by text
curl "https://api.litmus.science/hypotheses?search=antibacterial" \
  -H "Authorization: Bearer YOUR_TOKEN"

Converting to an Experiment

When you're ready to test a hypothesis:

curl -X POST https://api.litmus.science/hypotheses/hyp_abc123/to-experiment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "additional_fields": {
      "privacy": "open",
      "turnaround_budget": {
        "max_days": 14,
        "max_usd": 400
      }
    }
  }'

The hypothesis status automatically changes to USED.

Updating a Hypothesis

Only DRAFT hypotheses can be updated:

curl -X PATCH https://api.litmus.science/hypotheses/hyp_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "Updated hypothesis statement",
    "null_hypothesis": "Updated null hypothesis"
  }'

Archiving a Hypothesis

Archive hypotheses you no longer need:

curl -X DELETE https://api.litmus.science/hypotheses/hyp_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Archived hypotheses are hidden from listings but remain in the database.

Edison-Generated Hypotheses

Hypotheses generated by Edison Scientific include additional metadata:

{
  "id": "hyp_abc123",
  "title": "Edison: Antibiotic resistance mechanisms",
  "statement": "Efflux pump inhibitors restore antibiotic sensitivity",
  "edison_agent": "hypothesis_generation",
  "edison_query": "Novel mechanisms for overcoming antibiotic resistance",
  "edison_response": {
    "reasoning_trace": [...],
    "sources": [...]
  }
}

See the Edison Integration Tutorial for generating hypotheses with AI.

Best Practices

  1. Use descriptive titles — Make hypotheses easy to find later
  2. Include null hypotheses — Essential for proper experimental design
  3. Save intake drafts — Pre-fill experiments for faster submission
  4. Archive instead of delete — Keep a record of your research history
  5. Link to Edison — Save AI-generated hypotheses with full context

Next Steps

Hypothesis FormulationEdison Integration