tican vignettes

Using tic_analyse to analyse time-intensity curve data

Using the tic_analyse requires a dataframe with a column indicating time values and at least one column with intensity values. Passing only the dataframe and name of these two columns will generate a time-intensity plot and return a dataframe with peak intensity, time to peak, and area under the curve (AUC). If selected, time to peak proportion, wash in rate (WiR) and wash out rate (WoR) are also returned. This analysis is performed by fitting a LOESS curve to the raw data, using the loess() function. WiR is the maximum upslope before the peak value. WoR (wash out rate) is the absolute value of the maximum downslope following the peak value (with larger values representing higher wash out rate). AUC is calculated using the trapezium method for integration.

Generated plots display the raw data as black dots, loess curve in red, with blue dashed lines showing calculated peak intensity and time to peak, and solid purple lines showing WiR and WoR.


# Showing structure of example dataframe

head(example_data,5)
#>   time regionA_intensity regionB_intensity
#> 1  0.0        -1.4011891        0.25688371
#> 2  0.5        -0.5754437       -0.24669188
#> 3  1.0         3.8967708       -0.34754260
#> 4  1.5         0.1762710       -0.95161857
#> 5  2.0         0.3232193       -0.04502772


# Analysing using defaults

result <- tic_analyse(example_data,"time","regionA_intensity")


print(result)
#>           data Peak_intensity Time_to_peak      AUC
#> 1 example_data       95.40612           11 1091.161

Time to peak proportion and adjusting area under the curve analysis

Time to peak proportion (for example time to 90 percent of peak) can be calculated using the peakproportion argument. This will be added to the plot as a dashed green line.

For area under the curve analysis a maximum time can be specified, for example AUC up to 30 seconds.

result <- tic_analyse(example_data,"time","regionA_intensity",
                           peakproportion = 0.9, #to calculate time to 90 percent peak
                           AUCmax = 30)


print(result)
#>           data Peak_intensity Time_to_peak      AUC Time_to_peak_proportion
#> 1 example_data       95.40612           11 1072.077                     9.5

Wash in rate (WiR) and wash out rate (WoR)

These are added by setting the calc_wir and/or calc_wir arguments to TRUE. WiR is the maximum upslope before the peak value. WoR (wash out rate) is the absolute value of the maximum downslope following the peak value (with larger values representing higher wash out rate). These will be plotted with solid purple lines.

Note WiR and WoR can be sensitive to noise in the data, and are therefore calculated from the LOESS smoothed curve, and not the raw data. They are therefore sensitive to the degree of LOESS smoothing. The degree of smoothing can be changed by altering loess.span as described in the next section.


result <- tic_analyse(example_data,"time","regionA_intensity",
                           calc_wir = TRUE,
                           calc_wor = TRUE
                      )


print(result)
#>           data Peak_intensity Time_to_peak      AUC      WiR      WoR
#> 1 example_data       95.40612           11 1091.161 27.33003 9.696657

Adjusting the LOESS curve

The loess.span argument can be adjusted to a number between 0 and 1, with larger values representing a greater degree of smoothing. In addition, any argument which can be passed into the loess() function can be passed into tic_analyse().


result <- tic_analyse(example_data,"time","regionA_intensity",
                           loess.span = 0.15, # altering from default of 0.1
                           degree = 1) # adding a loess() argument


print(result)
#>           data Peak_intensity Time_to_peak      AUC
#> 1 example_data       91.26745         11.5 1091.161

Analysing multiple regions

For loops can be used to analyse multiple regions and output a single result dataframe.

results <- data.frame() #making empty dataframe to hold results

for(region in c("regionA_intensity","regionB_intensity")){
  resulttemp <- tic_analyse(example_data,"time",region) #storing results
  resulttemp$Region <- region # adding column for region
  results <- rbind(results, resulttemp) # combining results for different regions
}


print(results)
#>           data Peak_intensity Time_to_peak       AUC            Region
#> 1 example_data       95.40612           11 1091.1610 regionA_intensity
#> 2 example_data       28.80367            6  184.2169 regionB_intensity

Analysing multiple dataframes

For loops can be used to analyse multiple dataframes and output a single result dataframe.


example_data2 <- example_data #creating a second dataframe

results <- data.frame() #making empty dataframe to hold results

for(df in c("example_data","example_data2")){
  resulttemp <- tic_analyse(get(df), # get() to get the dataframe object
                                 "time","regionA_intensity") 
  
  resulttemp$data <- df # adding column for which dataframe results are from
  results <- rbind(results, resulttemp) # combining results for different dataframes
}


print(results)
#>            data Peak_intensity Time_to_peak      AUC
#> 1  example_data       95.40612           11 1091.161
#> 2 example_data2       95.40612           11 1091.161