Raw Datasets

Processed Datasets

Saved to Disk

Unprocessed Datasets

Uploaded files awaiting processing. Click 'Process Data' to detect endpoints.

Processed Datasets

Datasets with detected endpoints. Review them or generate reports.

Saved Datasets

Datasets saved to disk (data/processed/ directory). RDS files contain full data for Review Endpoints. CSV/Excel files are for report generation only.

Generated Reports

Reports generated during this session. Use the search box to filter reports. Click 'Open Reports Folder' to view all report files.

Dataset Information
Select Metrics
Select metrics to calculate for non-excluded samples.
Generate Report

ThermogramForge User Guide

Complete documentation for thermal liquid biopsy analysis

Contents
Quick Start Guide Preparing Your Data Data Overview Tab Review Endpoints Tab Report Builder Tab Saving & Loading Troubleshooting About

Quick Start Guide

Get up and running with ThermogramForge in 5 minutes.

The ThermogramForge Workflow
1
Upload

Upload your CSV or Excel thermogram data

2
Process

Automatic baseline detection and signal analysis

3
Review

Review and manually adjust endpoints if needed

4
Export

Generate metric reports for analysis

Quick Steps
  1. Go to Data Overview tab and click Upload New Raw Thermogram Data
  2. Select your data file (CSV or Excel) and review the preview
  3. Click Process on your uploaded dataset to run baseline detection
  4. Go to Review Endpoints tab to inspect results and make adjustments
  5. Go to Report Builder tab to select metrics and generate reports
  6. Save your work using Save to Disk on Data Overview
Tip: Save your processed data in RDS format to preserve all adjustments. You can reload it later to continue your work.

Preparing Your Data

ThermogramForge accepts thermogram data in CSV or Excel format. Your data must follow one of three supported structures.

File Requirements
  • Formats: CSV (.csv), Excel (.xlsx, .xls)
  • Maximum file size: 150 MB
  • Maximum samples: 1,000 per file
  • Temperature units: Degrees Celsius ( o C)
  • Typical range: 45-90 o C for plasma DSC
  • Encoding: UTF-8 recommended
Supported Data Formats
Format 1: Single Sample

For files containing one thermogram:

Temperature dCp
45.0 0.0012
45.5 0.0015
46.0 0.0018
... ...

Column names can be variations like 'Temp', 'T', 'temperature' or 'Cp', 'dcp', 'cp_excess'

Format 2: Multi-Sample Long Format

Multiple samples stacked vertically with a sample identifier:

Sample_ID Temperature dCp
Sample_001 45.0 0.0012
Sample_001 45.5 0.0015
Sample_002 45.0 0.0008
Sample_002 45.5 0.0011
... ... ...

Sample ID column can be named 'Sample_ID', 'SampleID', 'Sample', 'ID', etc.

Format 3: Multi-Sample Wide Format

Paired temperature and dCp columns for each sample:

T1a 1a T1b 1b T2a 2a ...
45.0 0.0012 45.0 0.0008 45.0 0.0015 ...
45.5 0.0015 45.5 0.0011 45.5 0.0018 ...

Temperature column starts with 'T' followed by sample ID (e.g., T1a). dCp column is just the sample ID (e.g., 1a).

Important: Ensure your data has no missing temperature values. Missing dCp values are handled but may affect analysis quality.

Data Overview Tab

The Data Overview tab is your central hub for managing datasets. Upload, process, save, and load your thermogram data here.

Uploading Data
  1. Click the Upload New Raw Thermogram Data button
  2. Select your CSV or Excel file
  3. For Excel files with multiple sheets: A dropdown will appear to select the specific sheet
  4. Review the data preview to ensure it looks correct
  5. Optional: Adjust temperature range filter if needed (e.g., 45-90 o C)
  6. Click Confirm Upload
Understanding Dataset Statuses
Unprocessed Raw Data

Data has been uploaded but not yet processed.

Available actions: Process, Delete

Processed Analysis Ready

Baseline detection complete. Ready for review and reports.

Available actions: Review Endpoints, Reports, Save, Download, Delete

Loaded From Saved File

Previously saved dataset loaded from disk.

Available actions: Review Endpoints, Reports, Download, Delete

Processing Data

When you click Process on an unprocessed dataset:

  1. Baseline Detection: The algorithm identifies stable pre- and post-transition regions
  2. Endpoint Selection: Lower and upper baseline endpoints are automatically determined
  3. Baseline Subtraction: A spline-fitted baseline is subtracted from raw data
  4. Signal Detection: ARIMA-based analysis determines if a thermal signature is present
Tip: Processing may take a few seconds per sample.
Managing Datasets
Action Description
Review Endpoints Navigate to Review Endpoints tab with this dataset loaded
Reports Navigate to Report Builder tab with this dataset selected
Save to Disk Save processed data to the server's file system (RDS/CSV/Excel)
Download Download data directly to your computer
Delete Remove dataset from the current session
Saved Datasets Section

The bottom of the Data Overview tab shows datasets saved to disk. From here you can:

  • Load: Load a saved dataset back into your session
  • Download: Download the saved file to your computer
  • Delete: Permanently remove the saved file from disk
Note: Only RDS files can be fully reloaded with all adjustments intact. CSV and Excel files contain only the baseline-subtracted data.

Review Endpoints Tab

The Review Endpoints tab allows you to inspect each sample's baseline detection results and make manual adjustments if needed.

Sample Grid

The sample grid shows all samples in your dataset with key information:

Column Description
Sample Sample identifier from your data file
Status Signal = thermal signature detected; No Signal = no clear signature
Lower / Upper Baseline endpoint temperatures in o C
Reviewed indicates you have reviewed this sample
Exclude indicates sample is excluded from reports

Click any row to select that sample and view its thermogram.

Plot Views
Raw Thermogram View

Shows the original thermogram data with the fitted baseline curve. Useful for understanding how the baseline was determined.

  • Gray dashed lines mark endpoint positions
  • Red line shows the fitted baseline
  • Click here to set endpoints on raw data scale
Baseline Subtracted View

Shows the thermogram after baseline subtraction. This is the data used for metric calculations.

  • Should show thermal transition peaks clearly
  • Flat regions at endpoints indicate good baseline fit
  • Default view for quality assessment
Manual Endpoint Adjustment

If the automatic baseline detection needs correction:

  1. Click Set Lower Endpoint or Set Upper Endpoint
  2. A notification will confirm you're in adjustment mode
  3. Click directly on the plot at the desired temperature position
  4. The baseline will automatically recalculate with the new endpoint
Tip: Look for flat, stable regions in the thermogram for optimal endpoint placement. The pre-transition region is typically 45-55 o C and post-transition is typically 82-90 o C for plasma samples.
Review Controls
Control Purpose
Reviewed Mark a sample as reviewed. Helps track your progress through the dataset.
Exclude Exclude a sample from report generation. Use for poor quality or failed samples.
/ Prev/Next Navigate to previous or next sample in the grid.
/ Undo/Redo Revert or restore changes to endpoints, reviewed status, or exclusions.
Undo/Redo System

ThermogramForge maintains a complete history of your changes:

  • Every endpoint adjustment is tracked
  • Checkbox changes (Reviewed, Exclude) are tracked
  • Use Undo to revert the last change
  • Use Redo to restore an undone change
  • History is preserved until you leave the tab or switch datasets
Best Practice: Review all samples with 'No Signal' status carefully. Consider excluding samples with poor quality or no discernible thermal transition.

Report Builder Tab

The Report Builder generates comprehensive metric reports using the tlbparam package for thermogram analysis.

Dataset Selection

Use the dropdown at the top to select which processed dataset to analyze. The display shows the filename and number of samples.

Only samples not marked as Excluded will be included in the report.
Available Metrics

ThermogramForge calculates 24 metrics across 6 categories:

  • Peak 1: Height of peak in region 60-66 o C
  • Peak 2: Height of peak in region 67-73 o C
  • Peak 3: Height of peak in region 73-81 o C
  • Peak F (Fibrinogen): Height in fibrinogen region 47-60 o C

  • T Peak 1-3: Temperature at each peak maximum ( o C)
  • T Peak F: Temperature of fibrinogen peak ( o C)

  • Peak 1/Peak 2: Ratio of Peak 1 to Peak 2 heights
  • Peak 1/Peak 3: Ratio of Peak 1 to Peak 3 heights
  • Peak 2/Peak 3: Ratio of Peak 2 to Peak 3 heights

  • V1.2: Valley (minimum) between Peak 1 and Peak 2
  • TV1.2: Temperature of the valley ( o C)
  • V1.2/Peak ratios: Valley height relative to each peak

  • Max: Maximum observed excess heat capacity
  • TMax: Temperature at maximum height ( o C)
  • TFM: Temperature of first moment (center of mass)
  • Width: Full width at half maximum (FWHM)
  • Area: Total area under the thermogram signature

  • Min: Minimum observed excess heat capacity
  • TMin: Temperature at minimum ( o C)
  • Median: Median excess heat capacity value
Generating Reports
  1. Select desired metrics using checkboxes (or use All/None buttons)
  2. Click Generate Report
  3. Preview the results in the table
  4. Export using Download buttons or Save to reports/ folder
Export Options
Direct Download

Downloads directly to your computer via browser:

  • Download CSV: Simple tabular format
  • Download Excel: Includes metadata sheet
Save to Reports Folder

Saves to server's reports/ directory:

  • Files appear in Data Overview's saved section
  • Good for batch processing workflows
  • Enter custom report name before saving

Saving & Loading

Understanding the different save formats helps you choose the right one for your needs.

File Format Comparison
Format Contents Can Reload? Best For
RDS Complete data: raw thermograms, baseline-subtracted data, endpoints, adjustments, review status, exclusions Yes - Full reload Saving work in progress, collaboration, archival
CSV Baseline-subtracted data only in wide format (temperature columns + sample columns) Report data only External analysis in R, Python, Excel, etc.
Excel Baseline-subtracted data + metadata sheet with processing parameters Report data only Sharing with collaborators, documentation
File Locations
  • processed_data/ - Saved processed datasets (RDS, CSV, Excel)
  • reports/ - Generated metric reports from Report Builder
Recommendation: Always save an RDS copy of your work before exporting to CSV or Excel. This preserves all your manual adjustments and allows you to make changes later.

Troubleshooting

Common Issues

  • Check file size is under 150 MB
  • Ensure file extension is .csv, .xlsx, or .xls
  • Verify the file isn't corrupted by opening in Excel
  • For Excel files, ensure the sheet contains data starting from row 1

  • Ensure you have Temperature and dCp columns (or equivalent names)
  • For wide format, column names must follow T[id] and [id] pattern
  • Remove any extra header rows above the column names
  • Check for hidden characters in column names

  • Check temperature range - ensure it covers full transition (45-90 o C typical)
  • Look for data quality issues (noise, artifacts, missing values)
  • Use manual endpoint adjustment for problematic samples
  • Consider excluding very noisy samples from analysis

  • Make sure you clicked 'Set Lower Endpoint' or 'Set Upper Endpoint' first
  • Wait for the notification confirming adjustment mode
  • Click directly on the plot area (not the axes or legend)
  • If stuck, click 'Cancel' and try again

  • Check if all samples are marked as Excluded
  • Ensure a dataset is selected in the dropdown
  • Verify the dataset has been processed (not just uploaded)
  • Check that at least one metric is selected

CSV and Excel exports contain only the baseline-subtracted data, not the full processing state.

  • These formats are for external analysis, not for reloading into ThermogramForge
  • Always save an RDS file if you want to continue working later
  • RDS files preserve all endpoints, adjustments, and exclusions

About ThermogramForge

Application Overview

ThermogramForge is an R Shiny application for analyzing differential scanning calorimetry (DSC) data from thermal liquid biopsy (TLB) experiments. It provides automated baseline detection, interactive review capabilities, and comprehensive metric calculation.

Core Dependencies
  • shiny / bslib - Web application framework
  • plotly - Interactive visualizations
  • DT - Interactive data tables
Credits

Developed by Chris Reger at Northern Arizona University.

The baseline detection algorithm and validation are described in:

Reger et al. (2025). Automated baseline-correction and signal detection algorithms with web-based implementation for Thermal Liquid Biopsy data analysis. Manuscript in preparation.

Version

ThermogramForge v1.0.0 (December 2025)

Back to Top