Use Case YAML Configuration Methodology¶

Overview¶

BioRemPP employs a declarative YAML-based configuration system to define analytical use cases. This approach separates visualization logic from business rules, enabling reproducible, auditable, and maintainable analytical configurations.

Each use case is fully described through YAML files that specify:

• What data to process
• How to transform the data
• How to visualize the results
• What validation rules to apply
• How to handle errors

This methodology supports the scientific requirement of traceability: analytical outputs can be linked to a specific, versioned configuration state.

Design Principles¶

Declarative Over Imperative¶

Configuration files describe the desired outcome, not the procedural steps to achieve it. The system interprets these declarations and executes the appropriate logic.

# Declarative: WHAT to do
processing:
  steps:
    - name: "group_and_count"
      params:
        group_by: "Sample"
        agg_function: "nunique"

Separation of Concerns¶

Reproducibility¶

Given identical: - Input data - Configuration version - Database snapshot

The system produces identical outputs.

File Structure¶

Each analytical module contains use case configurations organized by module number:

src/infrastructure/plot_configs/
├── module1/
│   ├── uc_1_1_config.yaml
│   ├── uc_1_1_panel.yaml
│   ├── uc_1_2_config.yaml
│   └── ...
├── module2/
├── module3/
└── ...

Naming Convention¶

Where X = module number, Y = use case number within module.

Data Flow¶

┌─────────────────┐
│   YAML Config   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Data Loading   │ ← Store ID from config
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Validation    │ ← Rules from config
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Processing    │ ← Steps from config
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Visualization  │ ← Strategy from config
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Plotly Figure │
└─────────────────┘

Configuration Schema¶

Plot Configuration (*_config.yaml)¶

A complete plot configuration contains the following sections:

1. Metadata Section¶

Identifies the use case and provides context.

2. Data Section¶

Specifies data source and processing pipeline.

Processing Steps:

3. Visualization Section¶

Controls chart rendering.

Available Strategies¶

Total strategies: 19

4. Interactivity Section¶

Defines UI component interactions.

Trigger Types:

• accordion_open — Render when accordion expands
• button_click — Render on button click
• dropdown_selection — Render on dropdown change
• filter_change — Update on filter modification

5. Validation Section¶

Ensures data meets requirements before rendering.

6. Performance Section¶

Controls caching and logging.

7. Error Handling Section¶

Defines error responses.

Panel Configuration (*_panel.yaml)¶

Provides scientific context for users.

Aggregation Functions Reference¶

Color Scales Reference¶

Layout Templates Reference¶

Best Practices¶

1. Version all configurations: Include version field and track changes in version control

2. Use descriptive identifiers: Use case IDs should follow UC-X.Y pattern

3. Document scientific context: Panel files should explain interpretation to users

4. Set appropriate cache TTL: Balance freshness vs. performance

5. Define comprehensive validation: Catch data issues before rendering

6. Use consistent naming: Follow established patterns across modules

Related Pages¶

• YAML Configuration Overview — Quick configuration guide for deployment
• Methods Overview — High-level methodological framework
• Data Sources — Database inventory and provenance
• Mapping Strategy — Technical mapping pipeline and join logic
• Limitations and Scope Boundaries — Interpretation constraints and usage restrictions
• Use Cases Index — Analytical use case catalog
• Environment Variables — Runtime configuration for YAML processing