# Time-at-Temperature histogram generates daily or back-to-back (e.g. Day-vs-Night-) Time-at-Temperature histograms from binned Temperature or Temperature time series data ## Details Time-at-Temperature (Tat) and Time-at-Depth (TaD) fequencies are a standard data product of archival tags (incl. tag models TDR-Mk9, PAT-Mk10 and miniPAT by [Wildlife Computers](https://wildlifecomputers.com/)) that allow to assess habitat preferences of tagged animals (see function read_histos ). It can be likewise generated from transmitted or recovered time series data sets using function ts2histos . However, different depth and temperature bin breaks are often used during different deployment programs, which makes a later comparitive analysis of TaT and TaT data difficult. For such cases, the function combine_histos and merge_histos can be applied to merge TaT and TaD frequencies based on common bin breaks of different tags. The purpose of this function is the visualization of Time-at-Temperature (TaT) histograms, whereas hist_tad is the related function for Time-at-Depth (TaD) data. ```r hist_tat(df, bin_breaks=NULL, bin_prefix="Bin", main, xlab="Time at Temperature (%)", ylab=expression(paste("Temperature (",degree,"C)")), labeling=TRUE, Type="TAT", ...) ``` ## Arguments - `df`: dataframe that either contains Temperature time series data (as a vector "Temperature") or several vectors of Time-at-Temperature frequencies. In the latter case, vector names are composed of a common `bin_prefix` (default is "tad."), followed by the upper Temperature limit (bin break). - `bin_breaks, bin_prefix`: `bin_breaks` is a numeric vector of depth bin breaks for the histogram data. In case of binned data (e.g. from standard wildlife computer histogram files), column names with a `bin_prefix` are expected to contain the preprossesed data (by default: Bin1, Bin2, Bin3, etc.). Alternatively, depth time series data will be directly converted using function ts2histos . - `main, xlab, ylab, labeling`: The titles for the plot, x- and y-axes to be plotted if `labeling` is set `TRUE` (default). - `Type`: The Type of data to be plotted (`TAD`: Time-at-Depth histograms; `TAT`: Time-at-Temperature histograms) - ``...``: additional arguments to be passed: - **select_id, select_from**: these arguments allow to take a direct subset of the input dataframe. `select_from` defines the vector whereas `select_id` defines the identification key(s) that should be selected. - **aggregate_by**: character vector defining the columns by which the tagging data should be aggregated. Should contain columns that identify tags (e.g. Serial, Ptt, DeployID) the date and/or day time period (to seperate records from night, day, dawn and dusk see classify_DayTime ). Default values are: date, Day and Ptt. - **date**: An optional vector to select depth data of a specified date/-range. - **xlim, adaptive.xlim**: a vector defining the limits (x1,x2) of the x-axis, by default c(0,100). However, if `adaptive.xlim` is set `TRUE`, these limits will be overwritten, and the maximum value (xlim[2]) will be chosen from the histogram data. - **split_by**: Name of the logical vector by which TaD data should be splitted (e.g. daytime; see classify_DayTime ). - **split_levels, xlab2**: Character vector defining the name and order of the levels of the split_by vector (e.g. c("Night", "Day") for split_by vector 'day.time'. The same groups are plotted as a second x-axis label if not defined otherwise (`xlab2`=`split_levels`). - **ylab.side, ylab.line, ylab.font**: side, line and font of second y-axis label. - **xlab.side, xlab.line, xlab.font**: side, line and font of first x-axis label. - **xlab2.side, xlab2.line, xlab2.font**: side, line and font of second x-axis labels. - **main.side, main.line, main.font**: side, line and font of plot title. - **col**: colours to be used for the TaD-histogram, by default 'grey' and 'white' (corresponding to the values of split_by/split_levels). - **xticks, ylabels**: tick labels of the x-axis and ylabels of the y-axis to show in the plot. - **do_mid.ticks**: whether centered tick-labels, indicating the depth range of histogram cells, shall be plotted (by default `FALSE`). Alternatively, tick labels will be indicated at the breakpoints of the histrogram cells. - **yaxis.pos**: x-axis coordinate at which the y-axis should be plotted (by default xlim[1], and thus 0). - **mars**: a numerical vector of the form `c(bottom, left, top, right)`, decribing the number of margin lines to be specified on the each side of the plot. The default is `c(2.1, 4.1, 6.1, 2.1)`. In case that `do_mid.ticks` is `TRUE` margins are: `c(2.1, 8, 6.1, 2.1)`. - **space**: the space between the histogram bars. - **plot_sd, plot_se, plot_nrec , plot_ntags**: whether standard deviation or standard error bars, the number of records and tags shall be plotted (default is `TRUE`) inside the TaD/TaT histogram. (if plot_se is `TRUE`, plot_sd will be overwritten!). - **cex, cex.main, cex.lab, cex.inf**: font size of the title (`cex.main`), x- and y-axes labels (`cex.lab`), and other labels, like the number of records (`cex.inf`). - **return.sm**: whether summary information of the TaD histograms, including the number of records per summary period, the relative frequencies per bin and corresponding standard deviation, should be plotted (default is `TRUE`). - **subplot, inside**: whether the TaD histogram is a subplot or an inner plot of a figure (default is `FALSE`). If `subplot` or `inside` are set `TRUE`, graphic margins will not be set by `hist_tat`. In case that `inside` is `TRUE`, no axis-labels and titels wil be plotted. ## See Also ts2histos , combine_histos , merge_histos , hist_tad ## Author(s) Robert K. Bauer ## Examples ```r ts_file <- system.file("example_files/104659-Series.csv",package="RchivalTag") ts_df <- read_TS(ts_file) head(ts_df) tad_breaks <- c(0, 2, 5, 10, 20, 50, 100, 200, 300, 400, 600, 2000) tat_breaks <- c(10,12,15,17,18,19,20,21,22,23,24,27) ## example 1a) convert only DepthTS data to daily TAD frequencies: ts2histos(ts_df, tad_breaks = tad_breaks) # hist_tad(ts_df, bin_breaks = tad_breaks) hist_tad(ts_df, bin_breaks = tad_breaks, do_mid.ticks = FALSE) ## convert 1b) only TemperatureTS data to daily TAT frequencies: tat <- ts2histos(ts_df, tat_breaks = tat_breaks) hist_tat(ts_df, bin_breaks = tat_breaks, do_mid.ticks = FALSE) hist_tat(tat$TAT$merged, do_mid.ticks = FALSE) ## convert 1c) DepthTS & TemperatureTS data to daily TAD & TAT frequencies: ts2histos(ts_df, tad_breaks = tad_breaks, tat_breaks = tat_breaks) ## convert 1d) back-to-back histogram showing day vs night TAD frequencies: ts_df$Lat <- 4; ts_df$Lon=42.5 ## required geolocations to estimate daytime head(ts_df) ts_df2 <- classify_DayTime(get_DayTimeLimits(ts_df)) # estimate daytime head(ts_df2) ts2histos(ts_df2, tad_breaks = tad_breaks,split_by = "daytime") hist_tad(ts_df2, bin_breaks = tad_breaks,split_by = "daytime", do_mid.ticks = FALSE) ## example 2) rebin daily TAD frequencies: tad <- ts2histos(ts_df, tad_breaks = tad_breaks) tad2 <- rebin_histos(hist_list = tad, tad_breaks = tad_breaks[c(1:3,6:12)]) par(mfrow=c(2,2)) hist_tad(tad, do_mid.ticks = FALSE) ## example for multiple individuals hist_tad(tad$TAD$merged, do_mid.ticks = FALSE) hist_tad(tad$TAD$merged, bin_breaks = tad_breaks[c(1:3,6:12)]) ## from inside hist_tad ## example 3) read, merge and plot TAD frequency data from several files: ## part I - read histogram data from two files: hist_dat_1 <- read_histos(system.file("example_files/104659-Histos.csv",package="RchivalTag")) hist_dat_2 <- read_histos(system.file("example_files/104659b-Histos.csv",package="RchivalTag")) ## note the second list is based on the same data (tag), but on different bin_breaks ## part II - combine TAD/TAT frecuency data from seperate files in one list: hist_dat_combined <- combine_histos(hist_dat_1, hist_dat_2) par(mfrow=c(2,1)) hist_tad(hist_dat_combined) hist_tat(hist_dat_combined) ## part III - force merge TAD/TAT frecuency data from seperate files # in one list, by applying common bin_breaks: hist_dat_merged <- merge_histos(hist_dat_combined,force_merge = TRUE) hist_tad(hist_dat_merged) hist_tat(hist_dat_merged) ## part IV - plot merged data: hist_tad(hist_dat_merged) # of all tags unique(hist_dat_merged$TAD$merged$df$DeployID) ## list unique tags in merged list hist_tad(hist_dat_merged, select_id = "15P1019b", select_from = 'DeployID') # of one tag ## part V - unmerge data: unmerge_histos(hist_dat_merged) ```

hist_tat function