alterlab-hypogenic
Runs automated hypothesis generation and empirical testing on tabular datasets.
Install
mkdir -p .claude/skills/alterlab-hypogenic && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/16034" && unzip -o skill.zip -d .claude/skills/alterlab-hypogenic && rm skill.zipInstalls to .claude/skills/alterlab-hypogenic
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Runs automated LLM-driven hypothesis generation and testing on tabular datasets with HypoGeniC, combining literature insights with data-driven testing. Use when systematically exploring hypotheses about patterns in empirical data (for example deception detection or content analysis). For manual hypothesis formulation use alterlab-hypothesis-gen; for open-ended creative ideation use alterlab-scientific-brainstorm. Part of the AlterLab Academic Skills suite.Key capabilities
- →Generate scientific hypotheses from observational datasets.
- →Test multiple competing hypotheses systematically.
- →Combine literature insights with empirical patterns.
- →Accelerate research discovery through automated hypothesis ideation.
- →Extract insights from research papers via PDF processing.
- →Prune near-duplicate hypotheses with a redundancy checker.
How it works
The skill uses LLMs to generate hypotheses from data, refines them based on performance, and can integrate insights from literature. It supports different methods like HypoGeniC, HypoRefine, and Union methods.
Inputs & outputs
When to use alterlab-hypogenic
- →Data-driven hypothesis generation
- →Empirical data analysis
- →Testing patterns in tabular data
About this skill
Hypogenic
Overview
Hypogenic provides automated hypothesis generation and testing using large language models to accelerate scientific discovery. The framework supports three approaches: HypoGeniC (data-driven hypothesis generation), HypoRefine (synergistic literature and data integration), and Union methods (mechanistic combination of literature and data-driven hypotheses).
Keyless by default: Claude runs the HypoGeniC loop
The large language model that HypoGeniC needs is Claude — so the whole loop runs in this
conversation with no package and no API key. The deterministic scoring is a bundled
stdlib script; Claude does the generate/refine reasoning. This is the default path; the
hypogenic package (below) is an optional scaled-up alternative.
The loop (the HypoGeniC method, data-driven):
- Generate. Claude reads the labelled training split and proposes candidate
hypotheses, each written as a checkable keyword rule — e.g. "texts containing any of
{furthermore, moreover, additionally, consequently} are AI-generated". Record them in a
small JSON bank (
scripts/score_hypotheses.py --emit-templateprints the shape). - Score. Run the bundled, LLM-free scorer on a held-out split:
It reports each hypothesis's held-out accuracy, the best single hypothesis, the first-match bank accuracy, and the examples the bank misclassifies. Pure stdlib, fully reproducible — no model call.python scripts/score_hypotheses.py \ --data your_labelled_data.jsonl --hypotheses bank.json --split test - Refine. Claude reads the scores and the misclassified examples, drops or edits weak hypotheses, and adds new ones aimed at the errors; re-score. Repeat until held-out accuracy plateaus (HypoGeniC's iterative refinement, done keyless).
- Report. Hand back the final hypothesis bank and its held-out accuracy, with the evidence (per-hypothesis and bank numbers from the scorer).
A worked example ships as a fixture: evals/fixtures/ai_vs_human_texts.jsonl (24 labelled
human-vs-AI texts, train/test split). On its test split the connector hypothesis scores
0.875 and a two-hypothesis bank reaches 1.000 — verified with the scorer, so the loop is
checkable end to end without any credential.
For your own data, give the scorer a .jsonl/.csv with text, label, and split
columns (or pass --text-field/--label-field/--split-field). When features are not
keyword-expressible, Claude can still apply each natural-language hypothesis to each
held-out example to emit a predicted label, then compute accuracy the same deterministic
way.
Scaled-up option: the hypogenic package
The upstream hypogenic package automates the same loop against an LLM provider and adds
HypoRefine (literature) and Union methods. It needs its own environment and an LLM provider
API key, and is worth it mainly for large banks, HypoRefine's PDF/literature integration, or
heavy batch inference. Everything below documents that optional package.
Quick Start (optional package)
Get started with the hypogenic package in minutes:
# Install into its own environment: hypogenic 0.3.5 pins numpy~=1.26, pandas~=2.1,
# torch~=2.4, transformers~=4.45, openai~=1.40 and anthropic~=0.32 (Python 3.10–3.12)
uv venv .venv-hypogenic --python 3.10 && source .venv-hypogenic/bin/activate
uv pip install hypogenic
# Clone example datasets
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data
# Run data-driven hypothesis generation (model_type: gpt | claude | vllm | huggingface)
hypogenic_generation --task_config_path ./data/your_task/config.yaml \
--model_type gpt --model_name <provider-model-id> \
--max_num_hypotheses 20 --output_folder ./outputs/your_task
# Run inference with a saved hypothesis bank
hypogenic_inference --task_config_path ./data/your_task/config.yaml \
--hypothesis_file ./outputs/your_task/<hypotheses_*.json> \
--model_type gpt --model_name <provider-model-id>
Flags verified against the
hypogenic0.3.5 console scripts (hypogenic_cmd). The CLI covers data-driven HypoGeniC generation and inference; HypoRefine and Union runs are driven by the example scripts (below). Run--helpfor the full option list.
Or use the example scripts (the library ships runnable scripts under examples/; there is no one-line fluent task.generate_hypotheses(...) API — see "Python API Usage" below for the real classes):
python ./examples/generation.py --help # HypoGeniC data-driven generation
python ./examples/inference.py --help # single-hypothesis inference
When to Use This Skill
Use this skill when working on:
- Generating scientific hypotheses from observational datasets
- Testing multiple competing hypotheses systematically
- Combining literature insights with empirical patterns
- Accelerating research discovery through automated hypothesis ideation
- Domains requiring hypothesis-driven analysis: deception detection, AI-generated content identification, mental health indicators, predictive modeling, or other empirical research
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Hand-formulating falsifiable hypotheses and predictions from observations (no LLM pipeline) | alterlab-hypothesis-gen |
| Open-ended ideation or research-gap brainstorming with no dataset yet | alterlab-scientific-brainstorm |
| Topic models, dictionaries, or supervised classifiers over text as social-science measurement | alterlab-text-as-data |
| Testing one pre-specified hypothesis with a conventional statistical test | alterlab-statistical-analysis |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-hypothesis-gen) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Key Features
Automated Hypothesis Generation
- Generate 10-20+ testable hypotheses from data in minutes
- Iterative refinement based on validation performance
- Support for both API-based (OpenAI, Anthropic) and local LLMs
Literature Integration
- Extract insights from research papers via PDF processing
- Combine theoretical foundations with empirical patterns
- Systematic literature-to-hypothesis pipeline with GROBID
Performance Optimization
- Redis caching reduces API costs for repeated experiments
- Parallel processing for large-scale hypothesis testing
- Adaptive refinement focuses on challenging examples
Flexible Configuration
- Template-based prompt engineering with variable injection
- Custom label extraction for domain-specific tasks
- Modular architecture for easy extension
Reported Results (from arXiv:2410.17309, Literature Meets Data)
- +8.97% over few-shot, +15.75% over literature-only, +3.37% over data-driven-only baselines
- Human accuracy improved +7.44% (deception detection) and +14.19% (AI-generated content detection)
- A redundancy checker prunes near-duplicate hypotheses to keep the final bank diverse
Core Capabilities
1. HypoGeniC: Data-Driven Hypothesis Generation
Generate hypotheses solely from observational data through iterative refinement.
Process:
- Initialize with a small data subset to generate candidate hypotheses
- Iteratively refine hypotheses based on performance
- Replace poorly-performing hypotheses with new ones from challenging examples
Best for: Exploratory research without existing literature, pattern discovery in novel datasets
2. HypoRefine: Literature and Data Integration
Synergistically combine existing literature with empirical data through an agentic framework.
Process:
- Extract insights from relevant research papers (typically 10 papers)
- Generate theory-grounded hypotheses from literature
- Generate data-driven hypotheses from observational patterns
- Refine both hypothesis banks through iterative improvement
Best for: Research with established theoretical foundations, validating or extending existing theories
3. Union Methods
Mechanistically combine literature-only hypotheses with framework outputs.
Variants:
- Literature ∪ HypoGeniC: Combines literature hypotheses with data-driven generation
- Literature ∪ HypoRefine: Combines literature hypotheses with integrated approach
Best for: Comprehensive hypothesis coverage, eliminating redundancy while maintaining diverse perspectives
Installation
Install via pip:
uv pip install hypogenic
Because of the pinned dependency versions above, keep hypogenic out of your main analysis environment.
Optional dependencies:
- Redis server (port 6832): Enables caching of LLM responses to significantly reduce API costs during iterative hypothesis generation
- s2orc-doc2json: Required for processing literature PDFs in HypoRefine workflows
- GROBID: Required for PDF preprocessing (see Literature Processing section)
Clone example datasets:
# For HypoGeniC examples
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data
# For HypoRefine/Union examples
git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data
Dataset Format
Datasets must follow HuggingFace datasets format with specific naming conventions:
Required files:
<TASK>_train.json: Training data<TASK>_val.json: Validation data<TASK>_test.json: Test data
Required keys in JSON:
text_features_1throughtext_features_n: Lists of strings containing feature valueslabel: List of strings containing ground truth labels
Example (headline click prediction):
{
"headline_1": [
"What Up, Comet? You Just Got *PROBED*",
---
*Content truncated.*
When not to use it
- →For manual hypothesis formulation, use alterlab-hypothesis-gen.
- →For open-ended creative ideation, use alterlab-scientific-brainstorm.
Prerequisites
Limitations
- →It requires an LLM provider API key for hypothesis generation.
- →Optional dependencies like Redis server, s2orc-doc2json, and GROBID are needed for full functionality.
- →It is not designed for open-ended creative ideation.
How it compares
This skill automates the entire hypothesis generation and testing process, combining data-driven and literature-based approaches, which is more systematic and efficient than manual hypothesis formulation.
Compared to similar skills
alterlab-hypogenic side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| alterlab-hypogenic (this skill) | 0 | 4mo | Review | Intermediate |
| model-compare | 7 | 11mo | Review | Advanced |
| cellxgene-census | 8 | 11mo | Review | Advanced |
| tcga-bulk-data-preprocessing-with-omicverse | 1 | 8mo | No flags | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by AlterLab-IEU
View all by AlterLab-IEU →You might also like
model-compare
rawwerks
Compare 3D CAD models using boolean operations (IoU, Dice, precision/recall). Use when evaluating generated models against gold references, diffing CAD revisions, or computing similarity metrics for ML training. Triggers on: model diff, compare models, IoU, intersection over union, model similarity, CAD comparison, STEP diff, 3D evaluation, gold reference, generated model, precision recall 3D.
cellxgene-census
davila7
Query CZ CELLxGENE Census (61M+ cells). Filter by cell type/tissue/disease, retrieve expression data, integrate with scanpy/PyTorch, for population-scale single-cell analysis.
tcga-bulk-data-preprocessing-with-omicverse
Starlitnightly
Guide Claude through ingesting TCGA sample sheets, expression archives, and clinical carts into omicverse, initialising survival metadata, and exporting annotated AnnData files.
torchdrug
davila7
Graph-based drug discovery toolkit. Molecular property prediction (ADMET), protein modeling, knowledge graph reasoning, molecular generation, retrosynthesis, GNNs (GIN, GAT, SchNet), 40+ datasets, for PyTorch-based ML on molecules, proteins, and biomedical graphs.
string-database
davila7
Query STRING API for protein-protein interactions (59M proteins, 20B interactions). Network analysis, GO/KEGG enrichment, interaction discovery, 5000+ species, for systems biology.
transformer-lens-interpretability
davila7
Provides guidance for mechanistic interpretability research using TransformerLens to inspect and manipulate transformer internals via HookPoints and activation caching. Use when reverse-engineering model algorithms, studying attention patterns, or performing activation patching experiments.