real_sensor_values.Rd 4 KB
Newer Older
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
11 12 13
\link{read_glatos_detections}). 

\emph{OR} A data frame containing detection
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). }
}}
25

26
\item{tag_specs}{An object produced by \link{read_vemco_tag_specs}.
27

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. }
 }}
59 60
}
\value{
61 62
The input data frame, data.table, or tibble with the following
  columns added (see column descriptions above):
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
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),]
113 114 115 116 117

}
\author{
Chris Holbrook, \email{cholbrook@usgs.gov}
}