# Time-at-Depth histogram generates daily or back-to-back (e.g. Day-vs-Night-) Time-at-Depth histograms from binned depth or depth 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-Depth (TaD) histograms, whereas hist_tad is the related function for Time-at-Temperature (TaT) data. ```r hist_tad(df, bin_breaks=NULL, bin_prefix="Bin", select_id, select_from='Ptt', aggregate_by='Ptt', date, min_perc, main, xlab='Time at Depth (%)', ylab="Depth (m)", labeling=TRUE, xlim=c(0, 100), adaptive.xlim=FALSE, split_by=NULL, split_levels, xlab2=split_levels, ylab.side=2, ylab.line, ylab.font=1, xlab.side=3, xlab.line=2.5, xlab.font=1, xlab2.side=1, xlab2.line=1, xlab2.font=2, main.side=3, main.line=3.8, main.font=1, col=c("darkgrey", "white"), xticks, ylabels, do_mid.ticks=TRUE, yaxis.pos=0, mars, space=0, plot_sd=TRUE, plot_se, plot_nrec=TRUE, plot_ntags=TRUE, cex=1.2, cex.main=cex, cex.lab=cex, cex.inf=cex.axis,cex.axis=1, return.sm=FALSE, subplot=FALSE, inside=FALSE,Type="TAD") ``` ## Arguments - `df`: dataframe that either contains depth time series data (as a vector "Depth") or several vectors of Time-at-Depth frequencies. In the latter case, column names composed of a common `bin_prefix` (default is "Bin.") hold the pre-binned Time-at-Depth frequencies whose depth limits are defined in `bin_breaks`. - `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 . - `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. - `min_perc`: optional number, defining the minimum data coverage (in percent) of histogram entries obtained from depth time series data. - `main, xlab, ylab, labeling`: The titles for the plot, x- and y-axes to be plotted if `labeling` is set `TRUE` (default). - `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, cex.axis`: font size of the title (`cex.main`), x- and y-axes labels (`cex.lab`), other labels, like the number of records (`cex.inf`) as well as of the tick marks. - `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_tad`. In case that `inside` is `TRUE`, no axis-labels and titels wil be plotted. - `Type`: The Type of data to be plotted (`TAD`: Time-at-Depth histograms; `TAT`: Time-at-Temperature histograms) ## See Also ts2histos , combine_histos , merge_histos , hist_tat ## 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_tad function