# convert depth and temperature time series data to discrete Time-at-Depth and Time-at-Temperature data (histogram data) convert depth and temperature time series data to discrete Time-at-Depth (TaD) and Time-at-Temperature (TaT) data (histogram data) at user-defined breakpoints ## Details Time-at-Depth and Time-at-Temperature fequencies (histograms) 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. It can be likewise generated from transmitted or recovered time series data sets, which is the purpose of this function. However, different depth and temperature bin breaks are often used during different deployment programs, which makes a later comparitive analysis of TaT and TaD data difficult. For such cases, the functions combine_histos and merge_histos can be applied to merge TaT and TaD frequencies based on common bin breaks of different tags. To visualize Time-at-Temperature (TaT) and Time-at-Depth (TaD) data, please see hist_tat and hist_tad , respectively. ```r ts2histos(ts_df, tad_breaks=NULL, tat_breaks=NULL, split_by=NULL, aggregate_by="Ptt",min_perc, omit_negatives=TRUE) ``` ## Arguments - `ts_df`: dataframe of depth time series data. Obligatory columns are the numeric vector "Depth", "date" (of class Date ) and "Serial". `split.by` defines an optional vector to consider (e.g. `day.period`). - `tad_breaks, tat_breaks`: a numeric vector, defining the depth and/or temperature breakpoints of the histogram cells. - `split_by`: Name of the column with logical entries by which TaD/TaT data shall be splitted (e.g. daytime; see classify_DayTime .). - `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. - `min_perc`: optional number, defining the minimum data coverage (in percent) of histogram entries obtained from depth time series data. - `omit_negatives`: treat negative depth and temperature records as 0 (default is `TRUE`). ## Returns A list-of-lists containing the loaded histogram data. Lists of TaD and TaT data are distinguished at the first nesting level. Further sublists include the `bin_breaks` and data.frame s of the generated histogram data. The data.frames of the histogram data thereby also contain average(avg) and standard deviation (SD) of depth and temperature values thatare likewise directly estimated from time series data , unlike read_histos -generated values that are estimated from the histogram data. The accuracy of latter estimates thus depends on the number and selection of bin breaks (see statistics-example in read_histos ). $ TaD:List ..$ merged : List of 2 .. ..$ bin_breaks: num .. ..$ df : data.frame .. .. ..$ DeployID .. .. ..$ Ptt .. .. ..$ datetime .. .. ..$ date .. .. ..$ Bin1 .. .. .. ..$ Bin? (up to number of bin breaks) .. .. ..$ avg (average depth estimated!! from histogram data) .. .. ..$ SD (average depth estimated!! from histogram data) $ TaT:List ..$ merged : List of 2 .. ..$ bin_breaks: num .. ..$ df : data.frame (with columns as above) ## See Also read_histos , hist_tad , merge_histos ## Author(s) Robert K. Bauer ## Examples ```r ### load sample depth and temperature time series data from miniPAT: 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: histos <- ts2histos(ts_df, tad_breaks = tad_breaks, tat_breaks = tat_breaks) histos$TAD$merged$df$nperc ## check completeness of TAD data sets histos$TAT$merged$df$nperc ## check completeness of TAT data sets # histos <- ts2histos(ts_df, tad_breaks = tad_breaks, tat_breaks = tat_breaks,min_perc = 90) ## 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 ```

ts2histos function