# Quickstart

Welcome to BioThermR! BioThermR helps you process thermal images for biological research. This guide covers the core loop: Import -> Segment -> Measure -> Visualize.

First, load the package:

    library(BioThermR)
    library(ggplot2)

## 1. Import Thermal Data

BioThermR includes example data to help you get started quickly. We will load a sample `.raw` thermal file provided with the package.

    # 1. Locate the example file provided with BioThermR
    raw_path <- system.file("extdata", "C05.raw", package = "BioThermR")

    # 2. Read the thermal data using read_thermal_raw
    obj <- read_thermal_raw(raw_path)

    # 3. Quick sanity check
    # This confirms the data is loaded and has the correct dimensions
    print(paste("Filename:", obj$meta$filename))
    #> [1] "Filename: C05.raw"
    print(paste("Dimensions:", obj$meta$dims[1], "x", obj$meta$dims[2]))
    #> [1] "Dimensions: 120 x 160"

## 2. Visualize Raw Data

Let’s look at the raw image. Notice the background is around 28°C (purple/black) and the subject is >32°C (yellow/red).

    plot_thermal_heatmap(obj, use_processed = FALSE) +
      ggtitle("Raw Thermal Image")

## 3. Automated Segmentation

Instead of manually guessing a temperature threshold, BioThermR can automatically separate the subject from the background using Otsu’s method and morphological operations.

This is particularly useful for batch processing where lighting or background temperatures might vary slightly.

    # Apply automated segmentation
    # method = "otsu": Automatically calculates the best threshold
    # keep_largest = TRUE: Removes small noise artifacts, keeping only the animal
    obj <- roi_segment_ebimage(obj, method = "otsu", keep_largest = TRUE)
    #> Auto-Segmentation: Kept largest object ( 401 pixels )

    # Visualize the result (Processed Data)
    # Note how the background is now clean (NA)
    plot_thermal_heatmap(obj, use_processed = TRUE) +
      ggtitle("Auto-Segmented Image")

## 4. Calculate Statistics

Now that the background is gone (set to NA), we can calculate accurate body temperature metrics.

    # Compute Min, Max, Mean, Median, etc.
    obj <- analyze_thermal_stats(obj)

    # Show the results
    print(obj$stats)
    #>          Metric        Value
    #> 1        Pixels 401.00000000
    #> 2           Min  29.10121918
    #> 3           Max  35.88959503
    #> 4          Mean  31.59486416
    #> 5        Median  31.46377563
    #> 6            SD   1.28356576
    #> 7           Q25  31.00030899
    #> 8           Q75  31.72277069
    #> 9           IQR   0.72246170
    #> 10           CV   0.04062577
    #> 11 Peak_Density  31.52773844

## 5. Batch Processing & Montage

BioThermR shines when processing large datasets. The package includes 30 sample raw images in the `extdata` folder. We will load, segment, and visualize all of them in a few lines of code.

    # 1. Get the path to the folder containing the 30 raw files
    data_folder <- system.file("extdata", package = "BioThermR")

    print(paste("Reading batch from:", data_folder))
    #> [1] "Reading batch from: /private/var/folders/_b/gx4lc14d5ssf7pl9qlkl32r80000gn/T/RtmptjUxIR/Rinste3622b26beb3/BioThermR/extdata"

    # 2. Read the entire batch
    # Note: We use pattern = ".raw" to ensure we only load the raw thermal files
    batch_list <- read_thermal_batch(data_folder, pattern = "\\.raw$")
    #> Reading 29 files...
    #> Batch read completed. Imported 29 files.

    # 3. Batch Segmentation (Automated)
    # We use lapply to apply the 'roi_segment_ebimage' function to every image in the list
    # This automatically removes the background for all 30 mice
    batch_list_clean <- lapply(batch_list, roi_segment_ebimage)
    #> Auto-Segmentation: Kept largest object ( 401 pixels )
    #> Auto-Segmentation: Kept largest object ( 388 pixels )
    #> Auto-Segmentation: Kept largest object ( 419 pixels )
    #> Auto-Segmentation: Kept largest object ( 342 pixels )
    #> Auto-Segmentation: Kept largest object ( 356 pixels )
    #> Auto-Segmentation: Kept largest object ( 327 pixels )
    #> Auto-Segmentation: Kept largest object ( 390 pixels )
    #> Auto-Segmentation: Kept largest object ( 455 pixels )
    #> Auto-Segmentation: Kept largest object ( 409 pixels )
    #> Auto-Segmentation: Kept largest object ( 330 pixels )
    #> Auto-Segmentation: Kept largest object ( 325 pixels )
    #> Auto-Segmentation: Kept largest object ( 320 pixels )
    #> Auto-Segmentation: Kept largest object ( 388 pixels )
    #> Auto-Segmentation: Kept largest object ( 419 pixels )
    #> Auto-Segmentation: Kept largest object ( 414 pixels )
    #> Auto-Segmentation: Kept largest object ( 366 pixels )
    #> Auto-Segmentation: Kept largest object ( 353 pixels )
    #> Auto-Segmentation: Kept largest object ( 347 pixels )
    #> Auto-Segmentation: Kept largest object ( 399 pixels )
    #> Auto-Segmentation: Kept largest object ( 407 pixels )
    #> Auto-Segmentation: Kept largest object ( 382 pixels )
    #> Auto-Segmentation: Kept largest object ( 298 pixels )
    #> Auto-Segmentation: Kept largest object ( 349 pixels )
    #> Auto-Segmentation: Kept largest object ( 362 pixels )
    #> Auto-Segmentation: Kept largest object ( 412 pixels )
    #> Auto-Segmentation: Kept largest object ( 393 pixels )
    #> Auto-Segmentation: Kept largest object ( 371 pixels )
    #> Auto-Segmentation: Kept largest object ( 387 pixels )
    #> Auto-Segmentation: Kept largest object ( 389 pixels )

    # 4. Visualization A: Gap-Free Montage
    p1 <- plot_thermal_montage(batch_list_clean, ncol = 5, padding = 2, text_size = 3) +
      ggtitle("Montage View: 30 Mice")
    #> Scanning objects for bounding box dimensions...
    #> Montage Layout: 6 x 5 | Cell Size: 41 x 37
    print(p1)

    # 5. Visualization B: Thermal Cloud
    p2 <- plot_thermal_cloud(batch_list_clean, spread_factor = 1.5, jitter_factor = 0.5, show_labels = TRUE) +
      ggtitle("Thermal Cloud: Population Overview")
    #> Processing objects...
    #> Generating layout for 29 objects...
    print(p2)

## 6. Compile Statistics to Data Frame

Finally, we extract the temperature metrics (Mean, Max, Min, etc.) from all 30 segmented images and compile them into a single table. This data frame is ready for statistical analysis (ANOVA, t-test) or export to CSV.

    # 1. Calculate stats for each image in the list
    # This adds a 'stats' slot to each BioThermR object
    batch_list_stats <- lapply(batch_list_clean, analyze_thermal_stats)

    # 2. Compile into a tidy data frame
    # Rows = Images, Columns = Metrics
    df_results <- compile_batch_stats(batch_list_stats)
    #> Compiling statistics for 29 images...

    # 3. View the first few rows
    head(df_results)
    #>   Filename Pixels      Min      Max     Mean   Median       SD      Q25
    #> 1  C05.raw    401 29.10122 35.88960 31.59486 31.46378 1.283566 31.00031
    #> 2  C06.raw    388 29.58407 35.84299 31.68077 31.51830 1.262623 31.08210
    #> 3  C07.raw    419 29.41834 35.88261 31.84558 31.68188 1.387581 31.13662
    #> 4  C08.raw    342 28.86848 35.89514 32.67292 31.73745 2.031803 31.21300
    #> 5  C09.raw    356 29.84530 36.06936 32.94407 31.96381 2.038136 31.40044
    #> 6  C10.raw    327 28.88244 35.82200 32.44315 31.83065 1.841554 31.26412
    #>        Q75       IQR         CV Peak_Density
    #> 1 31.72277 0.7224617 0.04062577     31.52774
    #> 2 31.87953 0.7974343 0.03985456     31.55971
    #> 3 32.00221 0.8655910 0.04357217     31.77638
    #> 4 35.56901 4.3560166 0.06218614     31.43158
    #> 5 35.59897 4.1985264 0.06186655     31.59204
    #> 6 32.59012 1.3260002 0.05676249     31.43307