# reads a TAD/TAT-histogram file from archival tags reads or posttreats a manually loaded standard histogram data file, containing Time-at-Depth (TAD) and Time-at-Temperature (TAT) frequency data, from archival tags by [Wildlife Computers](https://wildlifecomputers.com/). ```r read_histos(hist_file, date_format, lang_format="en", tz="UTC", dep.end, Serial, force_24h=TRUE, min_perc, omit_negatives=TRUE, right_truncate=TRUE) ``` ## Arguments - `hist_file`: character string indicating the name of a standard [Wildlife Computers](https://wildlifecomputers.com/) file to read or the data.frame of a manually loaded histogram data file. The combination of the columns `DeployID`, `Ptt` and `Serial` is assumed to provide an unique key to distinguish data from indiviudal tags. - `force_24h`: whether histogram data with a time step of less than 24h should be merged to 24h (default is `TRUE`). Note that the current version of hist_tad and hist_tat was written for 24h data! - `date_format, lang_format, tz`: character strings indicating the date format, language format and the corresponding time zone, defined by the vectors Date and Time (by default: date_format="%H:%M:%S %d-%b-%Y", lang_format="en", tz='UTC') If formatting fails, please check as well the input language format, defined by `lang_format` (and use abbrviations such as "en" for English,"es" for Spanish, "fr" for French, etc.) as well. - `dep.end`: Date specifying the deployment end of the tag. - `Serial`: character-string indicating the Serial number of the tag to be selected. (in case of multi-tag histogram files.) - `min_perc`: optional number, defining the minimum data coverage (in percent) of histogram entries obtained from depth time series data. - `omit_negatives`: merge negative depth and temperature bins with next positive bin (>= 0; default is `TRUE`). - `right_truncate`: truncate the values of the last tat- and tad-bin to 45 degrees and 2000 m, respectively (default is `TRUE`). ## Details This function reads or posttreats a manually loaded standard Wildlife Computers histogram file including Time-at-Depth (TAD) and Time-at-Temperature (TAT) frequency data. In the post-treatment, the histogram data is split in lists of TAD and TAT per individual (see below). Thus processed data from several histogram files (or similarly processed time series data) can be combined using the function combine_histos . Merging of histogram data from several tags, based on similar or user-specified TAD and TAT-`bin_breaks`, can be done by applying function merge_histos . To generate TAD/TAT histogram data from depth and temperature time series data, see ts2histos . ## 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 histogram data per tag (ID). Tag IDs are constructed based on the columns `DeployID`, `Ptt` and `Serial` keys (e.g. DeployID.101_Ptt.102525). The data.frames of the histogram data also contain average (avg) andstandard deviation (SD) of depth and temperature values that areestimated internally from the TAD and TAT data sets (not measured!).The accuracy of these estimates thus depends on the number andselection of bin breaks , unlike ts2histos -generated values that are directly estimated from time series data. See statistics-example below. $ TAD:List ..$ ID1 : 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 ..$ ID1 : List of 2 .. ..$ bin_breaks: num .. ..$ df : data.frame (with columns as above) ..$ ID2 : List of 2 ... ## See Also ts2histos , combine_histos , merge_histos , hist_tad , hist_tat ## Author(s) Robert K. Bauer ## Examples ```r ## read and merge 12h histogram data: # 12h_hist_file <- system.file("example_files/67851-12h-Histos.csv",package="RchivalTag") # hist_dat_0 <- read_histos(12h_hist_file,min_perc=100) # omit incomplete days # hist_tad(hist_dat_0) #hist_tat(hist_dat_0) ## example 1) 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) ## part VI - statistics: # get histogram data with histogram-derived average depth and temperature values hist_dat_1 <- read_histos(system.file("example_files/104659-Histos.csv",package="RchivalTag")) avg1 <- hist_dat_1$TAD$DeployID.15P1019_Ptt.104659$df$avg # infered from the histogram data # generate histogram data and average/sd-estimates from depth time series data of the same tag. # attention! unlike for histogram files, the average/sd-estimates are calculated # directly from depth time series data and not from the binned histogram data ts_file <- system.file("example_files/104659-Series.csv",package="RchivalTag") ts_df <- read_TS(ts_file) tad_breaks <- c(0, 2, 5, 10, 20, 50, 100, 200, 300, 400, 600, 2000) hist_dat_2 <- ts2histos(ts_df, tad_breaks = tad_breaks) avg2 <- hist_dat_2$TAD$merged$df$avg # directly estimated from the depth time series data # check accuracy of average depth values: plot(avg1, avg2) avg1-avg2 abline(0,b = 1,lty="dotted") ## crosscheck! # library(plyr) # ts_stats <- ddply(ts_df,c("date"),function(x) c(avg=mean(x$Depth,na.rm=T),SD=sd(x$Depth,na.rm=T))) # avg2==ts_stats$avg # path <- system.file("example_files",package="RchivalTag") # PDT <- read_PDT("104659-PDTs.csv",folder=path) # head(PDT) # image_TempDepthProfiles(interpolate_PDTs(PDT)[[1]]) ## add information # lines(ts_stats$date+.5,ts_stats$avg) # add <- hist_dat_2$TAD$merged$df # lines(add$date+.5,add$avg) # axis(2,at=50,las=1) # abline(h=20,lty="dashed",col="violet",lwd=3) ```

read_histos function