RchivalTag (version 0.1.9)

read_histos: reads a TAD/TAT-histogram file from archival tags

Description

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.

Usage

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)

Value

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.frames 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) and standard deviation (SD) of depth and temperature values that are estimated internally from the TAD and TAT data sets (not measured!). The accuracy of these estimates thus depends on the number and selection 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

...

Arguments

hist_file

character string indicating the name of a standard Wildlife Computers 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).

Author

Robert K. Bauer

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.

See Also

ts2histos, combine_histos, merge_histos, hist_tad, hist_tat

Examples

## 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)