tools-only Research Pipeline API Reference
Core Classes
Denario
The main class for orchestrating research workflows.
Initialization
from denario import Denario
den = Denario(project_dir="path/to/project")
Parameters:
project_dir(str): Path to the research project directory where all outputs will be stored
Methods
set_data_description()
Define the research context by describing available data and analytical tools.
den.set_data_description(description: str)
Parameters:
description(str): Text describing the dataset, available tools, research domain, and any relevant context
Example:
den.set_data_description("""
Available data: Time-series temperature measurements from 2010-2023
Tools: pandas, scipy, sklearn, matplotlib
Domain: Climate science
Research interest: Identifying seasonal patterns and long-term trends
""")
Purpose: This establishes the foundation for automated idea generation by providing context about what data is available and what analyses are feasible.
get_idea()
Generate research hypotheses based on the data description.
den.get_idea()
Returns: Research idea/hypothesis (stored internally in project directory)
Output: Creates a file containing the generated research question or hypothesis
Example:
den.get_idea()
# Generates ideas like: "Investigate the correlation between seasonal temperature
# variations and long-term warming trends using time-series decomposition"
set_idea()
Manually specify a research idea instead of generating one.
den.set_idea(idea: str)
Parameters:
idea(str): The research hypothesis or question to investigate
Example:
den.set_idea("Analyze the impact of El Niño events on regional temperature anomalies")
Use case: When you have a specific research direction and want to skip automated idea generation.
get_method()
Develop a research methodology based on the idea and data description.
den.get_method()
Returns: Methodology document (stored internally in project directory)
Output: Creates a structured methodology including:
- Analytical approach
- Statistical methods to apply
- Validation strategies
- Expected outputs
Example:
den.get_method()
# Generates methodology: "Apply seasonal decomposition, compute correlation coefficients,
# perform statistical significance tests, generate visualization plots..."
set_method()
Provide a custom methodology instead of generating one.
den.set_method(method: str)
den.set_method(method: Path) # Can also accept file paths
Parameters:
method(str or Path): Methodology description or path to markdown file containing methodology
Example:
# From string
den.set_method("""
1. Apply seasonal decomposition using STL
2. Compute Pearson correlation coefficients
3. Perform Mann-Kendall trend test
4. Generate time-series plots with confidence intervals
""")
# From file
den.set_method("methodology.md")
get_results()
Execute the methodology, perform computations, and generate results.
den.get_results()
Returns: Results document with analysis outputs (stored internally in project directory)
Output: Creates results including:
- Computed statistics
- Generated figures and visualizations
- Data tables
- Analysis findings
Example:
den.get_results()
# Executes the methodology, runs analyses, creates plots, compiles findings
Note: This is where the actual computational work happens. The agent executes code to perform the analyses specified in the methodology.
set_results()
Provide pre-computed results instead of generating them.
den.set_results(results: str)
den.set_results(results: Path) # Can also accept file paths
Parameters:
results(str or Path): Results description or path to markdown file containing results
Example:
# From string
den.set_results("""
Analysis Results:
- Correlation coefficient: 0.78 (p < 0.001)
- Seasonal amplitude: 5.2°C
- Long-term trend: +0.15°C per decade
- Figure 1: Seasonal decomposition (see attached)
""")
# From file
den.set_results("results.md")
Use case: When analyses were performed externally or when iterating on paper writing without re-running computations.
get_paper()
Generate a publication-ready LaTeX paper with the research findings.
den.get_paper(journal: Journal = None)
Parameters:
journal(Journal, optional): Target journal for formatting. Defaults to generic format.
Returns: LaTeX paper with proper formatting (stored in project directory)
Output: Creates:
- Complete LaTeX source file
- Compiled PDF (if LaTeX is available)
- Integrated figures and tables
- Properly formatted bibliography
Example:
from denario import Journal
den.get_paper(journal=Journal.APS)
# Generates paper.tex and paper.pdf formatted for APS journals
Journal Enum
Enumeration of supported journal formats.
from denario import Journal
Available Journals
Journal.APS- American Physical Society format- Suitable for Physical Review, Physical Review Letters, etc.
- Uses RevTeX document class
Additional journal formats may be available. Check the latest denario documentation for the complete list.
Usage
from denario import Denario, Journal
den = Denario(project_dir="./research")
# ... complete workflow ...
den.get_paper(journal=Journal.APS)
Workflow Patterns
Fully Automated Pipeline
Let denario handle every stage:
from denario import Denario, Journal
den = Denario(project_dir="./automated_research")
# Define context
den.set_data_description("""
Dataset: Sensor readings from IoT devices
Tools: pandas, numpy, sklearn, matplotlib
Goal: Anomaly detection in sensor networks
""")
# Automate entire pipeline
den.get_idea() # Generate research idea
den.get_method() # Develop methodology
den.get_results() # Execute analysis
den.get_paper(journal=Journal.APS) # Create paper
Custom Idea, Automated Execution
Provide your research question, automate the rest:
den = Denario(project_dir="./custom_idea")
den.set_data_description("Dataset: Financial time-series data...")
# Manual idea
den.set_idea("Investigate predictive models for stock market volatility using LSTM networks")
# Automated execution
den.get_method()
den.get_results()
den.get_paper(journal=Journal.APS)
Fully Manual with Template Generation
Use denario only for paper formatting:
den = Denario(project_dir="./manual_research")
# Provide everything manually
den.set_data_description("Pre-existing dataset description...")
den.set_idea("Pre-defined research hypothesis")
den.set_method("methodology.md") # Load from file
den.set_results("results.md") # Load from file
# Generate formatted paper
den.get_paper(journal=Journal.APS)
Iterative Refinement
Refine specific stages without re-running everything:
den = Denario(project_dir="./iterative")
# Initial run
den.set_data_description("Dataset description...")
den.get_idea()
den.get_method()
den.get_results()
# Refine methodology after reviewing results
den.set_method("""
Revised methodology:
- Use different statistical test
- Add sensitivity analysis
- Include cross-validation
""")
# Re-run only downstream stages
den.get_results() # Re-execute with new method
den.get_paper(journal=Journal.APS)
Project Directory Structure
After running a complete workflow, the project directory contains:
project_dir/
├── data_description.txt # Input: data context
├── idea.md # Generated or provided research idea
├── methodology.md # Generated or provided methodology
├── results.md # Generated or provided results
├── figures/ # Generated visualizations
│ ├── figure_1.png
│ ├── figure_2.png
│ └── ...
├── paper.tex # Generated LaTeX source
├── paper.pdf # Compiled PDF (if LaTeX available)
└── logs/ # Agent execution logs
└── ...
Advanced Features
Multiagent Orchestration
Denario uses AG2 and LangGraph frameworks to coordinate multiple specialized agents:
- Idea Agent: Generates research hypotheses from data descriptions
- Method Agent: Develops analytical methodologies
- Execution Agent: Runs computations and creates visualizations
- Writing Agent: Produces publication-ready manuscripts
These agents collaborate automatically, with each stage building on previous outputs.
Integration with Scientific Tools
Denario integrates with common scientific Python libraries:
- pandas: Data manipulation and analysis
- scikit-learn: Machine learning algorithms
- scipy: Scientific computing and statistics
- matplotlib/seaborn: Visualization
- numpy: Numerical operations
When generating results, denario can automatically write and execute code using these libraries.
Reproducibility
All stages produce structured outputs saved to the project directory:
- Version control friendly (markdown and LaTeX)
- Auditable (logs of agent decisions and code execution)
- Reproducible (saved methodologies can be re-run)
Literature Search
Denario includes capabilities for literature searches to provide context for research ideas and methodology development. See examples.md for literature search workflows.
Error Handling
Common Issues
Missing data description:
den = Denario(project_dir="./project")
den.get_idea() # Error: must call set_data_description() first
Solution: Always set data description before generating ideas.
Missing prerequisite stages:
den = Denario(project_dir="./project")
den.get_results() # Error: must have idea and method first
Solution: Follow the workflow order or manually set prerequisite stages.
LaTeX compilation errors:
den.get_paper() # May fail if LaTeX not installed
Solution: Install LaTeX distribution or use Docker image with pre-installed LaTeX.
Best Practices
Data Description Quality
Provide detailed context for better idea generation:
# Good: Detailed and specific
den.set_data_description("""
Dataset: 10 years of daily temperature readings from 50 weather stations
Format: CSV with columns [date, station_id, temperature, humidity]
Tools available: pandas, scipy, sklearn, matplotlib, seaborn
Domain: Climatology
Research interests: Climate change, seasonal patterns, regional variations
Known challenges: Missing data in 2015, station 23 has calibration issues
""")
# Bad: Too vague
den.set_data_description("Temperature data from weather stations")
Methodology Validation
Review generated methodologies before executing:
den.get_method()
# Review the methodology.md file in project_dir
# If needed, refine with set_method()
Incremental Development
Build the research pipeline incrementally:
# Stage 1: Validate idea generation
den.set_data_description("...")
den.get_idea()
# Review idea.md, adjust if needed
# Stage 2: Validate methodology
den.get_method()
# Review methodology.md, adjust if needed
# Stage 3: Execute and validate results
den.get_results()
# Review results.md and figures/
# Stage 4: Generate paper
den.get_paper(journal=Journal.APS)
Version Control Integration
Initialize git in project directory for tracking:
cd project_dir
git init
git add .
git commit -m "Initial research workflow"
Commit after each stage to track the evolution of your research.