diff --git a/NEWS.md b/NEWS.md index f486f873..d5aeec91 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,8 @@ +# motus 6.1.0 +* Clean up helper functions `sunRiseSet()` and `timeToSunriset()` + * `sunRiseSet()` now required to run `timeToSunriset()` + * Changed function argument names for clarity + # motus 6.0.1 * Fix bug in `xxxRunsFilter()` functions resulting in the inability to correctly return the filter id diff --git a/R/aa_common_docs.R b/R/aa_common_docs.R index 52a606e6..34896ef5 100644 --- a/R/aa_common_docs.R +++ b/R/aa_common_docs.R @@ -1,10 +1,16 @@ # args ------------------ #' Common arguments #' -#' @param projRecv Numeric project code from motus.org, *or* character receiver +#' @param projRecv Numeric. Project code from motus.org, *or* character receiver #' serial number. -#' @param src SQLite connection (result of `tagme(XXX)` or -#' `DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")`) +#' @param src SQLite connection. Result of `tagme(XXX)` or +#' `DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")` +#' +#' @param df_src Data frame, SQLite connection, or SQLite table. An SQLite +#' connection would be the result of `tagme(XXX)` or +#' `DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")`; an SQlite table would be +#' the result of `dplyr::tbl(tags, "alltags")`; a data frame could be the +#' result of `dplyr::tbl(tags, "alltags") %>% dplyr::collect()`. #' #' @param resume Logical. Resume a download? Otherwise the table is #' removed and the download is started from the beginning. diff --git a/man/args.Rd b/man/args.Rd index c87b18ff..d039e80e 100644 --- a/man/args.Rd +++ b/man/args.Rd @@ -4,11 +4,17 @@ \alias{args} \title{Common arguments} \arguments{ -\item{projRecv}{Numeric project code from motus.org, \emph{or} character receiver +\item{projRecv}{Numeric. Project code from motus.org, \emph{or} character receiver serial number.} -\item{src}{SQLite connection (result of \code{tagme(XXX)} or -\code{DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")})} +\item{src}{SQLite connection. Result of \code{tagme(XXX)} or +\code{DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")}} + +\item{df_src}{Data frame, SQLite connection, or SQLite table. An SQLite +connection would be the result of \code{tagme(XXX)} or +\code{DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")}; an SQlite table would be +the result of \code{dplyr::tbl(tags, "alltags")}; a data frame could be the +result of \code{dplyr::tbl(tags, "alltags") \%>\% dplyr::collect()}.} \item{resume}{Logical. Resume a download? Otherwise the table is removed and the download is started from the beginning.} diff --git a/man/sunRiseSet.Rd b/man/sunRiseSet.Rd index e8c96df7..866d5371 100644 --- a/man/sunRiseSet.Rd +++ b/man/sunRiseSet.Rd @@ -4,63 +4,88 @@ \alias{sunRiseSet} \title{Obtain sunrise and sunset times} \usage{ -sunRiseSet(data, lat = "recvDeployLat", lon = "recvDeployLon", ts = "ts") +sunRiseSet( + df_src, + lat = "recvDeployLat", + lon = "recvDeployLon", + ts = "ts", + data +) } \arguments{ -\item{data}{a selected table from .motus detection data, eg. "alltags", or a -data.frame of detection data including at a minimum variables for -date/time, latitude, and longitude} +\item{df_src}{Data frame, SQLite connection, or SQLite table. An SQLite +connection would be the result of \code{tagme(XXX)} or +\code{DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")}; an SQlite table would be +the result of \code{dplyr::tbl(tags, "alltags")}; a data frame could be the +result of \code{dplyr::tbl(tags, "alltags") \%>\% dplyr::collect()}.} -\item{lat}{variable with latitude values, defaults to \code{recvDeployLat}} +\item{lat}{Character. Name of column with latitude values, defaults to +\code{recvDeployLat}} -\item{lon}{variable with longitude values, defaults to \code{recvDeployLon}} - -\item{ts}{variable with time in UTC as numeric or POSIXct, defaults to \code{ts}} +\item{lon}{Character. Name of column with longitude values, defaults to +\code{recvDeployLon}} } \value{ -the original dataframe provided, with the following additional +Original data (as a flat data frame), with the following additional columns: \itemize{ -\item sunrise: sunrise time for the date and location provided by \code{ts} and lat/lon -per row -\item sunset: sunset time for the date and location provided by \code{ts} and lat/lon -per row +\item \code{sunrise} - Time of sunrise in \strong{UTC} for that row's date and location +\item \code{sunset} - Time of sunset in \strong{UTC} for that row's date and location } } \description{ -Creates and adds a sunrise and sunset column to a data.frame containing -latitude, longitude, and a date/time as POSIXct or numeric. +Create and add sunrise and sunset columns to tag data. Can take a motus +database table, but will always return a collected data frame. Requires data +containing at least latitude, longitude, and time. +} +\details{ +Note that this will always return the sunrise and sunset of the \emph{local} date. +For example, 2023-01-01 04:00:00 in Central North America is 2023-01-01 in UTC, +but 2023-01-01 20:00:00 is actually the following date in UTC. Because the +timestamps are UTC, times are first converted to their local time zone time +before extracting the date. Thus: +\itemize{ +\item A UTC timestamp of 1672624800 for Winnipeg, Canada +is 2023-01-02 02:00:00 UTC and 2023-01-01 20:00:00 local time +\item Therefore \code{sunRiseSet()} calculates the sunrise/sunset times for 2023-01-01 +\item These sunrise/sunset times are returned in UTC: 2023-01-01 14:27:50 UTC and +2023-01-01 22:38:30 UTC +\item Note that the UTC timestamp 2023-01-02 02:00:00 is later than the sunset +time of 2023-01-01 22:38:30 UTC. +This makes sense, as we know that the timestamp is ~8pm local time, +well after sunset in the winter. +} } \examples{ -# You can use either a selected tbl from .motus eg. "alltags", or a -# data.frame, instructions to convert a .motus file to all formats are below. -# download and access data from project 176 in sql format -# usename and password are both "motus.sample" -\dontrun{sql.motus <- tagme(176, new = TRUE, update = TRUE)} +# For SQLite Data base----------------------------------------------- -# OR use example sql file included in `motus` -sql.motus <- tagme(176, update = FALSE, +# Download sample project 176 in SQL (user and password are both "motus.sample") +\dontrun{sql_motus <- tagme(176, new = TRUE, update = TRUE)} + +# OR Use example SQL file +sql_motus <- tagme(176, update = FALSE, dir = system.file("extdata", package = "motus")) -# Extract alltags, collect (flatten to data frame), add sunrise/sunset cols: -sun <- sunRiseSet(sql.motus) +# Add sunrise/sunset +sun <- sunRiseSet(sql_motus) -# For other views, extract them first: +# For specific SQLite table/view ------------------------------------ library(dplyr) -tbl.alltagsGPS <- tbl(sql.motus, "alltagsGPS") +tbl_alltagsGPS <- tbl(sql_motus, "alltagsGPS") -# Add sunrise/sunset (after flattening to data frame) -sun <- sunRiseSet(tbl.alltagsGPS) +# Add sunrise/sunset +sun <- sunRiseSet(tbl_alltagsGPS) -# Or, submit a flattened data frame: -df.alltagsGPS <- collect(tbl.alltagsGPS) +# For a flattened data frame ---------------------------------------- +df_alltagsGPS <- collect(tbl_alltagsGPS) # Add sunrise/sunset -sun <- sunRiseSet(df.alltagsGPS) +sun <- sunRiseSet(df_alltagsGPS) -# Get sunrise and sunset information from tbl.alltags using gps lat/lon -# Note this only works if there are non-NA values in gpsLat/gpsLon -\dontrun{sun <- sunRiseSet(tbl.alltagsGPS, lat = "gpsLat", lon = "gpsLon")} +# Using alternate lat/lons ------------------------------------------ +# Get sunrise and sunset information from tbl_alltags using gps lat/lon +# Note this will only work if there are non-NA values in gpsLat/gpsLon +\dontrun{sun <- sunRiseSet(tbl_alltagsGPS, lat = "gpsLat", lon = "gpsLon")} } diff --git a/man/timeToSunriset.Rd b/man/timeToSunriset.Rd index 67eef525..5d9985a6 100644 --- a/man/timeToSunriset.Rd +++ b/man/timeToSunriset.Rd @@ -5,75 +5,65 @@ \title{Obtain time to and from sunrise/sunset} \usage{ timeToSunriset( - data, + df_src, lat = "recvDeployLat", lon = "recvDeployLon", ts = "ts", - units = "hours" + units = "hours", + data ) } \arguments{ -\item{data}{a selected table from .motus data, eg. "alltagsGPS", or a -data.frame of detection data including at a minimum variables for -date/time, latitude, and longitude} +\item{df_src}{Data frame, SQLite connection, or SQLite table. An SQLite +connection would be the result of \code{tagme(XXX)} or +\code{DBI::dbConnect(RSQLite::SQLite(), "XXX.motus")}; an SQlite table would be +the result of \code{dplyr::tbl(tags, "alltags")}; a data frame could be the +result of \code{dplyr::tbl(tags, "alltags") \%>\% dplyr::collect()}.} -\item{lat}{variable with latitude values, defaults to \code{recvDeployLat}} +\item{lat}{Character. Name of column with latitude values, defaults to +\code{recvDeployLat}} -\item{lon}{variable with longitude values, defaults to \code{recvDeployLon}} +\item{lon}{Character. Name of column with longitude values, defaults to +\code{recvDeployLon}} -\item{ts}{variable with time in UTC as numeric or POSIXct, defaults to ts} +\item{ts}{Character. Name of column with time as numeric or POSIXct, defaults +to \code{ts}} -\item{units}{units to display time difference, defaults to "hours", options -include "secs", "mins", "hours", "days", "weeks"} +\item{units}{Character. Units to display time difference, defaults to +"hours", options include "secs", "mins", "hours", "days", "weeks".} } \value{ -the original dataframe provided, with the following additional columns: +Original data (as a flat data frame), with the following additional +columns: \itemize{ -\item sunrise: sunrise time for the date and location provided by ts and -\code{recvDeployLat}/\code{recvDeployLon} per row -\item sunset: sunset time for the date and location provided by ts and -\code{recvDeployLat}/\code{recvDeployLon} per row -\item ts_to_set: time to next sunset after "ts", units default to "hours" -\item ts_since_set: time to previous sunset since "ts", units default to "hours" -\item ts_to_rise: time to next sunrise after "ts", units default to "hours" -\item ts_since_rise: time to previous sunrise since "ts", units default to "hours" +\item \code{sunrise} - Time of sunrise in \strong{UTC} for that row's date and location +\item \code{sunset} - Time of sunset in \strong{UTC} for that row's date and location +\item \code{ts_to_set} - Time to next sunset, in \code{units} +\item \code{ts_since_set} - Time to previous sunset, in \code{units} +\item \code{ts_to_rise} - Time to next sunrise after, in \code{units} +\item \code{ts_since_rise} - Time to previous sunrise, in \code{units} } } \description{ -Creates and adds columns for time to, and time from sunrise/sunset based on a -column of POSIXct dates/times dataframe must contain latitude, longitude, and -a date/time variable +Create and add columns for time to and time since sunrise/sunset to tag data. +Can take a motus database table, but will always return a collected data +frame. Requires data containing at least latitude, longitude, and time. +} +\details{ +Uses \code{sunRiseSet()} to perform sunrise/sunset calculates, see \code{?sunRiseSet} +for details regarding how local dates are assessed from UTC timestamps. } \examples{ -# You can use either a selected tbl from .motus eg. "alltagsGPS", or a -# data.frame, instructions to convert a .motus file to all formats are below. - -# download and access data from project 176 in sql format -# usename and password are both "motus.sample" -\dontrun{sql.motus <- tagme(176, new = TRUE, update = TRUE)} -# OR use example sql file included in `motus` -sql.motus <- tagme(176, update = FALSE, - dir = system.file("extdata", package = "motus")) +# For SQLite Data base----------------------------------------------- -# convert sql file "sql.motus" to a tbl called "tbl.alltags" -library(dplyr) -tbl.alltags <- tbl(sql.motus, "alltagsGPS") +# Download sample project 176 in SQL (user and password are both "motus.sample") +\dontrun{sql_motus <- tagme(176, new = TRUE, update = TRUE)} -# convert the tbl "tbl.alltags" to a data.frame called "df.alltags" -# let's also filter down to one day -df.alltags <- tbl.alltags \%>\% - collect() \%>\% - mutate(time = lubridate::as_datetime(tsCorrected), - date = lubridate::as_date(time)) \%>\% - filter(date == "2015-10-31") \%>\% - as.data.frame() - -# Get sunrise and sunset information with units in minutse -sunrise <- timeToSunriset(df.alltags, units = "mins") +# OR Use example SQL file +sql_motus <- tagme(176, update = FALSE, + dir = system.file("extdata", package = "motus")) -# Get sunrise and sunset information with units in hours using gps lat/lon -# using data.frame df.alltags. NOTE: This only works if there are non-NA -# gpsLat/gpsLon -\dontrun{sunrise <- timeToSunriset(df.alltags, lat = "gpsLat", lon = "gpsLon")} +# Get sunrise and sunset information for alltags view with units in minutes +sunrise <- timeToSunriset(sql_motus, units = "mins") }