Using a manually downloaded CIMIS CSV with TrackTrap

1. Prepare the daily report

Download daily maximum and minimum temperatures in Fahrenheit from CIMIS.

The CSV must contain columns that read.csv() reads as:

Date
Max.Air.Temp..F.
Min.Air.Temp..F.

Provide one weather observation for every day from the first through the last trap observation, including days without trap sampling. Missing dates, missing temperatures, duplicate daily dates, and minimum temperatures exceeding maxima cause an error.

2. Locate and inspect the example

The bundled example, example_cimis_synthetic_daily.csv, contains synthetic daily temperatures in CIMIS-compatible format for April 1–22, 2024. Daily maximum and minimum temperatures are fixed at 85°F and 55°F, respectively. These values demonstrate the software and do not represent observed station weather.

The file is stored in inst/extdata/example_cimis_synthetic_daily.csv in the package source.

library(TrackTrap)

example_path <- system.file(
  "extdata",
  "example_cimis_synthetic_daily.csv",
  package = "TrackTrap",
  mustWork = TRUE
)

example_weather <- read.csv(example_path)
names(example_weather)
#> [1] "Date"             "Max.Air.Temp..F." "Min.Air.Temp..F."

expected_dates <- seq(
  as.Date("2024-04-01"),
  as.Date("2024-04-22"),
  by = "day"
)

weather_dates <- as.Date(example_weather$Date, format = "%m/%d/%Y")

stopifnot(
  !anyNA(weather_dates),
  !anyDuplicated(weather_dates),
  all(expected_dates %in% weather_dates)
)

read.csv() normally converts a header such as Max Air Temp (F) to Max.Air.Temp..F.. Check the actual column names before calculation.

3. Date formats

TrackTrap accepts YYYY-MM-DD, M/D/YYYY, and MM/DD/YYYY character dates. Trap dates can also be R Date objects.

Invalid or missing dates cause an error.

4. Calculate degree-days

This example uses an illustrative lower threshold of 50°F and explicitly selects no upper cutoff. These settings demonstrate the software; they are not a recommended parameter set for any particular pest.

For a biological application, select documented parameters and a calculation method appropriate to the pest and developmental endpoint.

The bundled weather CSV must cover April 1–22, 2024, inclusive, for this example to run.

trap_df <- data.frame(
  date = as.Date(c(
    "2024-04-01",
    "2024-04-08",
    "2024-04-15",
    "2024-04-22"
  )),
  trap_counts = c(0, 0, 3, 9)
)

result <- calc_pest_phenology(
  trap_data = trap_df,
  pest = NULL,
  weather_source = "cimis_csv",
  cimis_csv_path = example_path,
  custom_lower = 50,
  upper_cutoff = "none",
  custom_pest_label = "Illustrative trap series",
  weather_provenance = list(
    data_type = "Synthetic demonstration data",
    temperature_units = "Fahrenheit",
    description = "Daily Tmax = 85 and Tmin = 55; not station observations."
  )
)
#> Configured simple-average DD analysis; biological model compatibility not established

Biofix is the first positive trap count: April 15 in this example. Accumulation begins on April 16. Values in cumulative_dd_from_biofix are NA before biofix and zero on the biofix date. The separate cumulative_dd column records accumulation from the first trap observation date. With these synthetic temperatures and a lower threshold of 50°F, daily accumulation is 20°F-days, giving 140°F-days from biofix on April 22.

When using database parameters, supply pest with the relevant code. A missing lower threshold requires custom_lower. A missing upper threshold requires either custom_upper or an explicit upper_cutoff = "none" choice.

To apply an upper threshold to the daily mean, use upper_cutoff = "horizontal" with a finite upper threshold greater than the lower threshold.

5. Station information

Station coordinates are not extracted from the CSV. Optional lat and lon arguments supplied to calc_pest_phenology() are retained for plot labelling; they do not change calculations using CSV weather.

Coordinates may also be supplied directly to plot_trap_phenology(). Use the actual station or monitoring-location coordinates and clearly identify which location they represent.

For observed CIMIS data, weather_provenance is optional but recommended. Supply the station identifier, download date, temperature units, and observation-day convention when available. The output also records the CSV filename and checksum. For this example, provenance identifies the temperatures as synthetic..

6. Plot the results

Plot trap catches against accumulated degree-days from first capture:

plot_trap_phenology(result)

No thermal reference markers are displayed unless a thermal requirement is supplied during calculation or plotting.

The following example adds an illustrative reference of 100°F-days. This value demonstrates marker placement only; it is not a published thermal requirement for a particular pest.

plot_trap_phenology(
  result,
  custom_thermal_requirement = 100,
  repeat_markers = TRUE
)

When a thermal reference is supplied, the plot automatically adds:

A subtitle showing its value in Fahrenheit degree-days.
The developmental endpoint when the value matches the database reference retained during calculation; otherwise, the subtitle states “developmental endpoint not specified.”
A caption explaining the thermal reference.

In this synthetic example, no pest database record was selected, so the developmental endpoint is unspecified.

Set repeat_markers = TRUE to display multiples of the reference value. The default, repeat_markers = FALSE, displays a single reference marker.

Database thermal requirements are not automatically selected as markers. Markers are positioned relative to first capture and do not independently establish flight or generation identities. Matching a database value does not establish that its original model is compatible with the selected calculation method or first-capture biofix.

7. Inspect the daily calculations

The returned rows correspond to trap observation dates. Complete daily weather and calculations are retained separately as attributes.

daily_calculations <- attr(result, "daily_weather")
calculation_metadata <- attr(result, "calculation_metadata")

head(daily_calculations)
#>         Date tmax tmin raw_avg_temp avg_temp DD cumulative_dd
#> 1 2024-04-01   85   55           70       70 20            20
#> 2 2024-04-02   85   55           70       70 20            40
#> 3 2024-04-03   85   55           70       70 20            60
#> 4 2024-04-04   85   55           70       70 20            80
#> 5 2024-04-05   85   55           70       70 20           100
#> 6 2024-04-06   85   55           70       70 20           120
#>   cumulative_dd_from_biofix
#> 1                        NA
#> 2                        NA
#> 3                        NA
#> 4                        NA
#> 5                        NA
#> 6                        NA
calculation_metadata$biofix_date
#> [1] "2024-04-15"
calculation_metadata$upper_cutoff
#> [1] "none"
calculation_metadata$accumulation_start
#> [1] "2024-04-16"
calculation_metadata$weather_provenance
#> $provider
#> [1] "User-supplied CIMIS report"
#> 
#> $filename
#> [1] "example_cimis_synthetic_daily.csv"
#> 
#> $file_md5
#> [1] "fbff2f921a32eb873f7643018790a7ec"
#> 
#> $station_and_time_convention
#> $station_and_time_convention$data_type
#> [1] "Synthetic demonstration data"
#> 
#> $station_and_time_convention$temperature_units
#> [1] "Fahrenheit"
#> 
#> $station_and_time_convention$description
#> [1] "Daily Tmax = 85 and Tmin = 55; not station observations."