Analysis Workflows

PumasAide provides guided workflows that help AI assistants conduct pharmacometric analyses systematically. When you request an analysis, the AI assistant follows a structured workflow that ensures proper methodology, quality control, and best practices.

How Workflows Work

Workflows provide step-by-step guidance to AI assistants, breaking complex analyses into manageable tasks. Each workflow specifies:

1. Required tools and their sequence for the analysis
2. Parameter guidance for tool calls
3. Best practices for data preparation and quality control
4. Common pitfalls to avoid
5. Visualization recommendations for results

Rather than memorizing tool sequences, you simply describe your analysis goal, and the AI assistant invokes the appropriate workflow to guide the process.

Using Workflows

Workflows are triggered automatically when you describe an analysis:

Perform an NCA analysis on my concentration-time data

This triggers the nca_analysis workflow, which guides the AI through data loading, population creation, parameter calculation, quality control, and visualization.

You can also explicitly request a workflow:

Follow the population PK analysis workflow for my dataset

This invokes the poppk_analysis workflow for model development, estimation, and diagnostics.

Built-in Workflows

PumasAide includes eight built-in workflows for common pharmacometric analyses:

adam_preparation

Prepares ADaM (Analysis Data Model) datasets from SDTM (Study Data Tabulation Model) source data. Guides domain mapping, variable derivation, and dataset merging for analysis-ready data.

Common use cases:

• Converting SDTM datasets (DM, EX, PC, PP) to ADaM format
• Creating ADPPK datasets for population PK analysis
• Deriving analysis variables from source data

Workflow steps:

1. Load SDTM domain datasets
2. Map domains to ADaM structure
3. Derive analysis variables
4. Merge domains into analysis dataset
5. Validate final dataset structure

consolidate_scripts

Combines multiple PumasAide-generated analysis scripts into a single, reproducible Julia file. Useful for archiving, sharing, or regulatory submissions after completing an analysis.

Common use cases:

• Archiving completed analyses in a single file
• Preparing scripts for regulatory submission
• Creating portable, self-contained analysis scripts

Workflow steps:

1. Identify scripts to consolidate from programs/ directory
2. Build dependency graph and determine execution order
3. Extract and deduplicate code (remove redundant includes)
4. Organize into sections (imports, data loading, analysis, results)
5. Preserve tool metadata as inline comments
6. Validate consolidated script runs successfully

create_workflow

Interactively creates custom workflows by gathering your specific requirements. Generates workflow documentation that can be reused for similar analyses.

Common use cases:

• Specialized analyses not covered by built-in workflows
• Organization-specific analysis standards
• Study-specific workflows for recurring analyses

Workflow steps:

1. Gather analysis requirements through questions
2. Identify required tools and their sequence
3. Document parameters and best practices
4. Generate custom workflow markdown
5. Save to .pumas/workflows/ for future use

data_explore

Explores datasets through visualizations and summary tables before formal analysis. Helps identify data quality issues, patterns, and distributions.

Common use cases:

• Initial data review before analysis
• Quality control checks for imported data
• Exploratory visualization to understand data structure

Workflow steps:

1. Load dataset
2. Generate overview tables showing column types and summaries
3. Create demographic summary tables
4. Build exploratory plots (distributions, time profiles, correlations)
5. Document data quality findings

generate_report

Generates Quarto analysis reports from workspace objects and generated code. Use this after completing an analysis to create formal documentation combining narrative text with executable code.

Common use cases:

• Creating reports after completing NCA, PopPK, or simulation workflows
• Documenting methods and results for regulatory submissions
• Generating reproducible documentation for publications

Report structure:

1. Executive Summary: High-level overview and key findings
2. Methods: Data sources, model specifications, estimation methods
3. Detailed Results: Parameter estimates, diagnostics, plots, tables
4. Supporting Information: Quality metrics, assumption checks

Rendering:

quarto render reports/analysis_report.qmd --to pdf

Reports recreate the analysis by including generated scripts from programs/, ensuring full reproducibility.

nca_analysis

Calculates pharmacokinetic parameters from concentration-time data using non-compartmental analysis methods.

Common use cases:

• Single and multiple dose PK studies
• Bioavailability and food effect studies
• First-in-human PK characterization

Workflow steps:

1. Load concentration-time data
2. Create NCA population with dosing information
3. Calculate NCA parameters (AUC, Cmax, half-life, clearance)
4. Assess parameter quality metrics
5. Generate summary tables and plots
6. Optional: dose linearity and bioequivalence analysis

poppk_analysis

Complete population pharmacokinetic model development workflow from data preparation through final model validation.

Common use cases:

• Developing population PK models for regulatory submissions
• Characterizing drug disposition in target populations
• Identifying clinically significant covariate effects

Workflow steps:

1. Load and prepare population PK data
2. Exploratory data analysis
3. Build base structural model
4. Progressive model fitting (FO → FOCE)
5. Covariate model development
6. Final model diagnostics and validation
7. Visual predictive check (VPC)

Model building strategy:

• Start simple (one-compartment)
• Add complexity based on data support
• Use progressive estimation (FO for initial, FOCE for final)
• Validate with VPC and other diagnostics

simulation

Model-based simulation for dose selection, trial design, or exposure predictions.

Common use cases:

• Dose selection for clinical trials
• Trial design simulations
• Exposure predictions for special populations
• What-if scenario analyses

Workflow steps:

1. Build or select Pumas model
2. Define model parameters
3. Create dosing regimens
4. Generate simulation population with covariates
5. Run simulations
6. Visualize concentration-time profiles and exposure metrics

Simulation types:

• Deterministic: Fixed parameter values, no variability
• Stochastic: Include between-subject and residual variability
• Virtual populations: Generate subjects with realistic covariate distributions

Custom Workflows

You can create custom workflows tailored to your specific analysis needs or organizational standards.

Creating a Custom Workflow

1. Create the workflow directory at .pumas/workflows/ in your project root.

2. Write the workflow markdown:

Create a file like .pumas/workflows/custom_pk_analysis.md:

# Custom PK Analysis Workflow

## Overview

This workflow performs a standardized PK analysis for our
organization's early phase studies.

## Steps

1. **Load Data**
   - Use `load_dataset` to import concentration-time data
   - Validate required columns: ID, TIME, DV, AMT, DOSE

2. **Data Cleaning**
   - Use `data_wrangler` to filter pre-dose samples
   - Remove BLQ values after Cmax
   - Derive dose-normalized concentrations

3. **NCA Analysis**
   - Use `build_nca_population` with dose and period grouping
   - Calculate standard PK parameters with quality metrics
   - Use `run_nca_analysis` with required parameters list

4. **Visualization**
   - Individual concentration-time profiles (linear and log scale)
   - Mean profiles by dose with error bands
   - Box plots of Cmax and AUC by dose

5. **Dose Proportionality**
   - Use `run_dose_linearity` for power model assessment
   - Evaluate 90% CI for dose proportionality

6. **Report Generation**
   - Generate summary tables
   - Create combined figure with key plots
   - Document any protocol deviations

1. Use the custom workflow:

Follow my custom PK analysis workflow for this dataset

The AI assistant will discover and follow your custom workflow.

Workflow Organization

Organize workflows in subdirectories for better management:

.pumas/workflows/
├── nca/
│   ├── single_dose_nca.md
│   ├── multiple_dose_nca.md
│   └── food_effect_nca.md
├── poppk/
│   ├── standard_poppk.md
│   ├── pediatric_poppk.md
│   └── oncology_poppk.md
└── simulation/
    ├── dose_finding.md
    └── trial_design.md

Reference nested workflows: "Use the nca/food_effect_nca workflow"

Workflow Overriding

Workflows are searched in this order:

1. .pumas/workflows/ in current directory
2. .pumas/workflows/ in parent directories
3. Built-in workflows

You can override built-in workflows by creating a file with the same name in your .pumas/workflows/ directory. This allows customizing standard workflows for organizational needs.

Reusable Components with Partials

Create reusable workflow components using .partial.md files:

.pumas/workflows/common_steps.partial.md:

- Validate data structure and types
- Check for missing values
- Document data source and version
- Generate overview table for quality control

Use in workflows with {{partial_name}} syntax:

# My Custom Workflow

1. Load dataset
2. **Data Quality Checks:**
   {{common_steps}}
3. Perform analysis
4. Generate reports

Partials help maintain consistency across related workflows and reduce duplication.

Best Practices

Workflow Selection

• Start simple: Use basic workflows like data_explore before complex analyses
• Follow progressions: Go from NCA → PopPK → Simulation as model complexity increases
• Use domain expertise: Workflows encode best practices, but scientific judgment remains essential

Customization Guidelines

• Document clearly: Explain why each step is necessary
• Specify parameters: Give guidance on tool parameters and options
• Include quality checks: Build in validation steps
• Provide examples: Show expected inputs and outputs

Project Continuity

Analyses often span multiple sessions. The AI assistant maintains context through project notes in the notes/ directory, enabling iterative development over days or weeks.

Version Control

Custom workflows are part of your analysis code:

• Commit workflows to git with your analysis
• Document workflow changes in commit messages
• Share workflows across projects via git repositories

Related Topics

• Tools Reference for detailed tool documentation
• NCA Analysis Walkthrough and Population PK Walkthrough for complete analysis demonstrations
• Getting Started for PumasAide setup