real_sensor_values.Rd 4 KB
Newer Older
 Chris Holbrook committed Feb 14, 2018 1 2 3 4 5 6 7 8 9 10 % Generated by roxygen2: do not edit by hand % Please edit documentation in R/proc-real_sensor_values.r \name{real_sensor_values} \alias{real_sensor_values} \title{Add 'real'-scale sensor values to glatos detetections} \usage{ real_sensor_values(det, tag_specs) } \arguments{ \item{det}{A \code{glatos_detections} object (e.g., produced by  Chris Holbrook committed Feb 22, 2018 11 12 13 \link{read_glatos_detections}). \emph{OR} A data frame containing detection  Chris Holbrook committed Feb 15, 2018 14 15 16 17 18 19 20 21 22 23 24 data with the following columns: \describe{ \item{transmitter_codespace}{A character string with transmitter code space (e.g., "A69-1061" for Vemco PPM coding").} \item{transmitter_id}{A character string with transmitter ID code (e.g., "1363" for Vemco PPM coding").} \item{sensor_value}{A numeric sensor measurement (e.g., an integer for 'raw' Vemco sensor tags).} \item{sensor_unit}{A character string with \code{sensor_value} units (e.g., "ADC" for 'raw' Vemco sensor tag detections). } }}  Chris Holbrook committed Feb 14, 2018 25   Chris Holbrook committed Feb 22, 2018 26 \item{tag_specs}{An object produced by \link{read_vemco_tag_specs}.  Chris Holbrook committed Feb 14, 2018 27   Chris Holbrook committed Feb 22, 2018 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58  \emph{OR} A data frame containing transmitter specification data with the following columns: \describe{ \item{code_space}{A character string with transmitter code space (e.g., "A69-1061" for Vemco PPM coding").} \item{id_code}{A character string with transmitter ID code (e.g., "1363" for Vemco PPM coding").} \item{sensor_type}{A numeric sensor measurement (e.g., an integer for 'raw' Vemco sensor tags).} \item{sensor_range}{A numeric with max. range of the sensor in 'real' units (e.g., "Meters" for Vemco depth tags). } \item{sensor_units}{A character string with 'real'-scale units (e.g., "Meters" for 'raw' Vemco pressure tags). } } The following columns are also required for \strong{depth} and \strong{temperature} sensors: \describe{ \item{sensor_slope}{Slope parameter, for converting 'raw' (ADC) to 'real' measurements. } \item{sensor_intercept}{Intercept parameter, for converting 'raw' (ADC) to 'real' measurements. } } The following columns are also required for \strong{acceleration} sensors: \describe{ \item{accel_algorithm}{The algorithm used, accelerometers only. } \item{accel_sample_rate}{Sample rate used, accelerometers only. } \item{sensor_transmit_ratio}{Sensor transmit rate used, accelerometers only. } }}  Chris Holbrook committed Feb 14, 2018 59 60 } \value{  Chris Holbrook committed Feb 19, 2019 61 62 The input data frame, data.table, or tibble with the following columns added (see column descriptions above):  Chris Holbrook committed Feb 14, 2018 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108  \itemize{ \item sensor_range \item sensor_units \item sensor_slope \item sensor_intercept \item accel_algorithm \item accel_sample_rate \item sensor_transmit_ratio \item sensor_value_real } } \description{ Get transmitter sensor (e.g., depth, temperature) conversion parameters (e.g., intercept, slope) from a Vemco transmitter specification object (e.g., from \link{read_vemco_tag_specs}, calculate 'real'-scale values (e.g., depth in meters), and add real values to detection data in a new column. } \details{ Tag spec data are joined to detection data and then raw-scale sensor measurements are converted to real-scale using \eqn{sensor_value_real = sensor_intercept + (sensor_value * sensor_slope)}, where \eqn{sensor_value} is in raw scale. It is possible that \code{transmitter_codespace} and \code{transmitter_id} are not unique among transmitters, so users must ensure that the each combination of those columns occurs only once in \code{tag_specs} and is the correct record for the corresponding tags in \code{det}. } \examples{ #get path to example detection file det_file <- system.file("extdata", "lamprey_detections.csv", package="glatos") lamprey_detections <- read_glatos_detections(det_file) #get path to example Vemco tag spec file spec_file <- system.file("extdata", "lamprey_tag_specs.xls", package="glatos") lamprey_tags <- read_vemco_tag_specs(spec_file, file_format = "vemco_xls") #note use of '$specs' in tag_specs argument  Chris Holbrook committed Feb 15, 2018 109 110 111 112 dtc <- real_sensor_values(lamprey_detections, lamprey_tags$specs) #now view records with sensor measurements dtc[!is.na(dtc\$sensor_value_real),]  Chris Holbrook committed Feb 14, 2018 113 114 115 116 117  } \author{ Chris Holbrook, \email{cholbrook@usgs.gov} }