MIRACLE API

MR Imaging Reference API for Cardiovascular Limits from Evidence

🫀 SCMR 2026 Open Source Innovation Submission

🌟 Introduction

MIRACLE is an open-source API that provides evidence-based reference values for cardiovascular magnetic resonance (CMR) measurements. It standardizes the interpretation of CMR studies by offering instant access to peer-reviewed normal ranges, z-scores, and percentiles across multiple clinical domains.

🔗 View and Test Full API Documentation: miracleapi.readme.io

🚀 Live Demos

• Pediatric CMR Reference Calculator: miracle-app.surge.sh

• Interactive Chatbot: miracle-chat.netlify.app

✨ Key Features

• 📊 Evidence-based reference values
• 🔓 Open-access API
• 🏥 Multiple clinical domains
• 🧮 Real-time z-score calculations
• 📈 Percentile computations
• 🤖 AI/LLM integration ready
• 📱 REST API with flexible endpoints

🛠️ Getting Started

Basic API Call

curl --request GET \
     --url 'https://script.google.com/macros/s/.../exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male' \
     --header 'accept: application/json'

Code Examples

Python

import requests

url = "https://script.google.com/macros/s/.../exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male"

headers = {"accept": "application/json"}

response = requests.get(url, headers=headers)

print(response.text)

JavaScript

const options = {method: 'GET', headers: {accept: 'application/json'}};

fetch('https://script.google.com/macros/s/.../exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

📚 API Endpoints

Adult Cardiac

Left Ventricle	Volumetric	Volumetric by Age	Functional and Geometric	Myocardial Thickness
	Global Strain	Fractal Dimension by BMI	Fractal Dimension by Ethnicity
Right Ventricle	Volumetric	Volumetric by Age
Left Atrium	Diameter & Area	Volume & Function
Right Atrium	Diameter & Area	Volume & Function
Other	Athletes	T1/ECV	T2 Relaxation	Myocardial Blood Flow

Adult Vascular

Aortic Root & Valve	Ascending Aorta	Thoracic Aorta	Aortic Elasticity	Pulmonary Artery
Aortic Root Diameter	Ascending Aortic Diameter	Thoracic Aorta Diameter	Aortic Distensibility by Age	Adult Pulmonary Artery Dimensions
Aortic Sinus Diameters and Area	Ascending Aorta Peak Velocity by Age	Thoracic Aorta Wall Thickness, Luminal Diameter	Aortic PWV by Age
Aortic Valve Peak Velocity

Pediatric Cardiac

Cardiac	Vascular
Atrial Volumes	Aortic CSA
Ventricular Parameters	Ascending Aorta Distensibility
	Pulse Wave Velocity
	Aortic Diameter
	Pulmonary Artery Diameters

Full documentation available at miracleapi.readme.io

🏥 For the SCMR Community

Ready-to-Use Applications

1. Pediatric CMR Z-score Calculator Web App

   • React-based frontend with Material-UI components
   • Real-time validation and calculation
   • RESTful API integration with error handling
   • Mobile-responsive design
   • Print support
   • Live Demo | Source Code

2. Virtual CMR Report Generator

   • Batch processing of multiple parameters
   • Customizable report templates using Handlebars
   • Export options: PDF, DOCX, JSON
   • Integration examples with clinical systems

   // Example report generation
   const report = await miracleAPI.generateReport({
     patient: { gender: "Male", height: 110, weight: 22 },
     measurements: {
       LVEDV: 62,
       LVEF: 60,
       LVM: 45
     },
     template: "pediatric_standard"
   });

3. LLM-Powered Chatbot

   • OpenAI/Groq function calling architecture
   • Natural language parsing with structured output
   • Context-aware conversation handling
   • Error boundary implementation
   • Live Demo | Source Code

   // Example function calling schema
   {
     "name": "getPediatricVentricleZScore",
     "parameters": {
       "type": "object",
       "properties": {
         "gender": { "type": "string", "enum": ["Male", "Female"] },
         "parameter": { "type": "string", "enum": ["LVEDV", "LVEF", "LVM"] },
         "measured": { "type": "number" },
         "ht_cm": { "type": "number" },
         "wt_kg": { "type": "number" }
       }
     }
   }

AI/LLM Integration

LLM-Ready Documentation

• Structured markdown format at /llms.txt
• Automated updates via GitHub Actions
• Endpoint schemas in OpenAPI 3.0

curl https://miracleapi.readme.io/llms.txt
# Returns markdown-formatted documentation

Model Context Protocol (MCP)

• OpenAPI specification at /mcp
• JSON Schema validation
• Rate limiting information
• Authentication requirements
• Read Documentation

curl https://miracleapi.readme.io/mcp
# Returns OpenAPI specification

Function Calling Support

• OpenAI-compatible function definitions
• Anthropic Claude-ready schemas
• Groq API integration examples
• Error handling patterns

# Example function registration with OpenAI
tools = [{
    "type": "function",
    "function": {
        "name": "getPediatricReferenceValues",
        "description": "Get z-scores for pediatric CMR measurements",
        "parameters": { ... }
    }
}]

Research Tools

Current Capabilities

# Example: Basic batch processing with current API
import pandas as pd
import requests

def process_cmr_data(data_df):
    base_url = "https://script.google.com/macros/s/.../exec"
    results = []
    
    for _, row in data_df.iterrows():
        params = {
            "domain": "Pediatric_Ventricle",
            "parameter": row["parameter"],
            "gender": row["gender"],
            "measured": row["value"],
            "ht_cm": row["height"],
            "wt_kg": row["weight"]
        }
        response = requests.get(base_url, params=params)
        results.append(response.json())
    
    return pd.DataFrame(results)

# Usage
df = pd.read_csv("measurements.csv")
results_df = process_cmr_data(df)
results_df.to_csv("results_with_zscores.csv")

🛣️ Future Roadmap (Planned Features)

1. Python Package Development

   • Dedicated miracle-py package
   • Easy-to-use batch processing
   • Statistical analysis utilities

   # Future API (not yet implemented)
   from miracle import MiracleBatch
   processor = MiracleBatch()
   results = processor.process_csv(...)

2. Research Integration Tools

   • DICOM SR templates
   • REDCap integration
   • Data validation suite

   # Planned feature
   from miracle.export import DicomSRExport  # Coming soon

3. Statistical Analysis Module

   • Advanced z-score calculations
   • Multiple BSA formulas
   • Automated outlier detection

   # Future enhancement
   from miracle.stats import calculate_zscore  # Planned

📖 Citation

@software{Ankush_MIRACLE_2025,
  author = {Ankush, Ankush},
  title = {MIRACLE: MR Imaging Reference API for Cardiovascular Limits from Evidence},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/drankush/MIRACLE-API}
}

📄 License

MIT License - See LICENSE for details

---

Made with ❤️ for the CMR community

Documentation • Web App • Chatbot