docs: updated for version 0.3.0

MazamaScience · Mar 8, 2024 · 0627bdc · 0627bdc
1 parent 3f313f1
commit 0627bdc
Show file tree

Hide file tree

Showing 96 changed files with 281 additions and 215 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Type: Package
 Package: MazamaTimeSeries
-Version: 0.2.16
+Version: 0.3.0
 Title: Core Functionality for Environmental Time Series
 Authors@R: c(
     person("Jonathan", "Callahan", email="[email protected]", role=c("aut","cre")),
@@ -18,7 +18,8 @@ Description: Utility functions for working with environmental time series data f
     Ephemerides calculations are based on code originally found in NOAA's
     "Solar Calculator" <https://gml.noaa.gov/grad/solcalc/>.
 License: GPL-3
-URL: https://github.com/MazamaScience/MazamaTimeSeries
+URL: https://github.com/MazamaScience/MazamaTimeSeries,
+     https://mazamascience.github.io/MazamaTimeSeries/
 BugReports: https://github.com/MazamaScience/MazamaTimeSeries/issues
 Depends:
     R (>= 4.0.0)
@@ -28,7 +29,7 @@ Imports:
     lubridate,
     magrittr,
     methods,
-    MazamaCoreUtils (>= 0.4.15),
+    MazamaCoreUtils (>= 0.5.2),
     MazamaRollUtils (>= 0.1.3),
     rlang,
     stringr

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,15 @@
+# MazamaTimeSeries 0.2.17
+
+Updated dependencies:
+
+* MazamaCoreUtils 0.4.15 => 0.5.2
+
+* All `mts_~()` functions that return an _mts_ object now return an empty _mts_
+when an empty _mts_ is used as input. This prevents breaks in the middle of 
+pipelines so that "emptiness" only needs to be checked at the end.
+* All `sts_~()` functions that return an _sts_ object now return an empty _sts_
+when an empty _sts_ is used as input.
+
 # MazamaTimeSeries 0.2.16
 
 * Added `mts_pull()` to get columns of data from `mts$meta` or `mts$data`.

diff --git a/R/MazamaTimeSeries.R b/R/MazamaTimeSeries.R
@@ -26,9 +26,9 @@ NULL
 #' \code{requiredMetaNames} and include:
 #'
 #' \itemize{
-#'   \item{\code{deviceDeploymentID} -- unique identifier (see \pkg{MazmaLocationUtils})}
+#'   \item{\code{deviceDeploymentID} -- unique identifier (see \href{https://mazamascience.github.io/MazamaLocationUtils/}{MazmaLocationUtils})}
 #'   \item{\code{deviceID} -- device identifier}
-#'   \item{\code{locationID} -- location identifier (see \pkg{MazmaLocationUtils})}
+#'   \item{\code{locationID} -- location identifier (see \href{https://mazamascience.github.io/MazamaLocationUtils/}{MazmaLocationUtils})}
 #'   \item{\code{locationName} -- English language name}
 #'   \item{\code{longitude} -- decimal degrees E}
 #'   \item{\code{latitude} -- decimal degrees N}

diff --git a/R/mts_arrange.R b/R/mts_arrange.R
@@ -48,6 +48,7 @@ mts_arrange <- function(
     }
   }
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
     return(mts)
 

diff --git a/R/mts_collapse.R b/R/mts_collapse.R
@@ -76,8 +76,9 @@ mts_collapse <- function(
     longitude <- latitude <- NULL
   }
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("'mts' has no data")
+    return(mts)
 
   # ----- Generate meta --------------------------------------------------------
 

diff --git a/R/mts_filterData.R b/R/mts_filterData.R
@@ -19,8 +19,6 @@
 #' @return A subset of the incoming \emph{mts} time series object.
 #' (A list with \code{meta} and \code{data} dataframes.)
 #'
-#' @seealso \link{mts_filterDate}
-#' @seealso \link{mts_filterDatetime}
 #' @seealso \link{mts_filterMeta}
 #'
 #' @examples
@@ -57,8 +55,9 @@ mts_filterData <- function(
     }
   }
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("'mts' has no data")
+    return(mts)
 
   # Remove any duplicate data records
   mts <- mts_distinct(mts)

diff --git a/R/mts_filterDate.R b/R/mts_filterDate.R
@@ -17,7 +17,7 @@
 #'
 #' @description Subsets an \emph{mts} object by date. This function
 #' always filters to day-boundaries. For sub-day filtering, use
-#' \code{mts_filterDatetime()}.
+#' \code{mts_setTimeAxis()}.
 #'
 #' Dates can be anything that is understood by \code{MazamaCoreUtils::parseDatetime()}
 #' including either of the following recommended formats:
@@ -45,9 +45,7 @@
 #' @return A subset of the incoming \emph{mts} time series object.
 #' (A list with \code{meta} and \code{data} dataframes.)
 #'
-#' @seealso \link{mts_filterData}
-#' @seealso \link{mts_filterDatetime}
-#' @seealso \link{mts_filterMeta}
+#' @seealso \link{mts_setTimeAxis}
 #'
 #' @examples
 #' library(MazamaTimeSeries)
@@ -88,8 +86,9 @@ mts_filterDate <- function(
     }
   }
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("'mts' has no data")
+    return(mts)
 
   # Remove any duplicate data records
   mts <- mts_distinct(mts)

diff --git a/R/mts_filterDatetime.R b/R/mts_filterDatetime.R
@@ -37,7 +37,7 @@
 #' \item{get timezone from \code{mts}}
 #' }
 #'
-#' @note This function is deprecated as of \pkg{MazamaTimeSeris 0.2.15}.
+#' @note This function is deprecated as of \strong{MazamaTimeSeries 0.2.15}.
 #' Please use \link{mts_setTimeAxis} to shorten or lengthen the time axis
 #' of an \emph{mts} object.
 #'
@@ -87,8 +87,9 @@ mts_filterDatetime <- function(
   if ( !mts_isValid(mts) )
     stop("'mts' is not a valid 'mts' object")
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("'mts' has no data")
+    return(mts)
 
   # Remove any duplicate data records
   mts <- mts_distinct(mts)

diff --git a/R/mts_filterMeta.R b/R/mts_filterMeta.R
@@ -10,8 +10,8 @@
 #' @description A generalized metadata filter for \emph{mts} objects to
 #' choose rows/cases where conditions are true.  Multiple conditions are
 #' combined with \code{&} or separated by a comma. Only rows where the condition
-#' evaluates to TRUE are kept. Rows where the condition evaluates to \code{NA}
-#' are dropped.
+#' evaluates to TRUE are kept. Rows where the condition evaluates to FALSE or
+#' \code{NA} are dropped.
 #'
 #' If an empty \emph{mts} object is passed in, it is immediately returned,
 #' allowing for multiple filtering steps to be piped together and only checking
@@ -22,10 +22,8 @@
 #' @return A subset of the incoming \emph{mts} time series object.
 #' (A list with \code{meta} and \code{data} dataframes.)
 #'
-#'
 #' @seealso \link{mts_filterData}
-#' @seealso \link{mts_filterDate}
-#' @seealso \link{mts_filterDatetime}
+#'
 #' @examples
 #' library(MazamaTimeSeries)
 #'
@@ -60,6 +58,7 @@ mts_filterMeta <- function(
     }
   }
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
     return(mts)
 

diff --git a/R/mts_getDistance.R b/R/mts_getDistance.R
@@ -9,7 +9,7 @@
 #' @param measure One of "geodesic", "haversine", "vincenty" or "cheap"
 #'
 #' @description
-#' This function uses the \pkg{geodist} package to return the distances (meters)
+#' This function uses the [geodist] package to return the distances (meters)
 #' between \code{mts} locations
 #' and a location of interest. These distances can be used to create a
 #' mask identifying monitors within a certain radius of the location of interest.

diff --git a/R/mts_pull.R b/R/mts_pull.R
@@ -8,7 +8,7 @@
 #' dataframe of the incoming \emph{mts} time series object.
 #'
 #' @description
-#' This function acts similarly to \code{\link[dplyr]{pull}} working on
+#' This function acts similarly to \code{dplyr::pull()} working on
 #' \code{mts$meta} or \code{mts$data}. Data are returned as a simple array.
 #' Data are pulled from whichever dataframe contains \code{var}.
 #'

diff --git a/R/mts_sample.R b/R/mts_sample.R
@@ -48,7 +48,7 @@
 #' encouraged to experiment with these two parameters along with
 #' \code{sampleSize} and review the results visually.
 #'
-#' See \code{\link[MazamaRollUtils]{findOutliers}}.
+#' See \code{MazamaRollUtils::findOutliers()}.
 #'
 
 mts_sample <- function(
@@ -64,6 +64,7 @@ mts_sample <- function(
 
   MazamaCoreUtils::stopIfNull(mts)
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
     return(mts)
 

diff --git a/R/mts_select.R b/R/mts_select.R
@@ -12,8 +12,10 @@
 #' time series identified by \code{deviceDeploymentID} in the order specified.
 #'
 #' This can be used the specify a preferred order and is helpful when using
-#' faceted plot functions based on \pkg{ggplot}
-#' such as those found in the \pkg{AirMonitorPlots} package.
+#' faceted plot functions based on
+#' \href{https://ggplot2.tidyverse.org}{ggplot}
+#' such as those found in the
+#' \href{https://mazamascience.github.io/AirMonitorPlots/}{AirMonitorPlots} package.
 #'
 #' @return A reordered (subset) of the incoming \emph{mts} time series object.
 #' (A list with \code{meta} and \code{data} dataframes.)

diff --git a/R/mts_selectWhere.R b/R/mts_selectWhere.R
@@ -60,8 +60,9 @@ mts_selectWhere <- function(
   # Remove any duplicate data records
   mts <- mts_distinct(mts)
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("Parameter 'mts' has no data.")
+    return(mts)
 
   if ( !is.function(FUN) )
     stop("'FUN' is not a function.")

diff --git a/R/mts_setTimeAxis.R b/R/mts_setTimeAxis.R
@@ -13,16 +13,28 @@
 #' steps with missing values. The resulting time axis is guaranteed to be
 #' a regular, hourly axis with no gaps using the same timezone as the incoming
 #' \emph{mts} object. This is useful when you want to place separate \emph{mts}
-#' objects on the same time axis for platting.
+#' objects on the same time axis for plotting.
+#'
+#' Dates can be anything that is understood by \code{MazamaCoreUtils::parseDatetime()}
+#' including either of the following recommended formats:
+#'
+#' \itemize{
+#' \item{\code{"YYYYmmdd"}}
+#' \item{\code{"YYYY-mm-dd"}}
+#' }
+#'
+#' Timezone determination precedence assumes that if you are passing in
+#' \code{POSIXct} values then you know what you are doing:
+#'
+#' \enumerate{
+#' \item{get timezone from \code{startdate} if it is \code{POSIXct}}
+#' \item{use passed in \code{timezone}}
+#' \item{get timezone from \code{mts}}
+#' }
 #'
 #' If either \code{startdate} or \code{enddate} is missing, the start or end of
 #' the timeseries in \code{mts} will be used.
 #'
-#' @note If \code{startdate} or \code{enddate} is a \code{POSIXct} value, then
-#' \code{timezone} will be set to the timezone associated with \code{startdate}
-#' or \code{enddate}.
-#' In this common case, you don't need to specify \code{timezone} explicitly.
-#'
 #' If neither \code{startdate} nor \code{enddate} is a \code{POSIXct} value
 #' AND no \code{timezone} is supplied, the timezone will be inferred from
 #' the most common timezone found in \code{mts}.

diff --git a/R/mts_slice.R b/R/mts_slice.R
@@ -65,6 +65,7 @@ mts_slice_head <- function(
     }
   }
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
     return(mts)
 

diff --git a/R/mts_summarize.R b/R/mts_summarize.R
@@ -68,8 +68,9 @@ mts_summarize <- function(
   MazamaCoreUtils::stopIfNull(FUN)
   MazamaCoreUtils::stopIfNull(minCount)
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("'mts' has no data")
+    return(mts)
 
   if ( length(unique(mts$meta$timezone)) > 1 )
     stop("'mts' has muliple timezones")

diff --git a/R/mts_trim.R b/R/mts_trim.R
@@ -35,8 +35,9 @@ mts_trim <- function(
   if ( !mts_isValid(mts) )
     stop("Parameter 'mts' is not a valid 'mts' object.")
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("Parameter 'mts' has no data.")
+    return(mts)
 
   # Remove any duplicate data records
   mts <- mts_distinct(mts)

diff --git a/R/mts_trimDate.R b/R/mts_trimDate.R
@@ -57,8 +57,9 @@ mts_trimDate <- function(
   if ( !mts_isValid(mts) )
     stop("Parameter 'mts' is not a valid 'mts' object.")
 
+  # Return the mts if it is empty so pipelines don't break
   if ( mts_isEmpty(mts) )
-    stop("Parameter 'mts' has no data.")
+    return(mts)
 
   # Remove any duplicate data records
   mts <- mts_distinct(mts)

diff --git a/R/sts_filter.R b/R/sts_filter.R
@@ -53,6 +53,7 @@ sts_filter <- function(
     }
   }
 
+  # Return the sts if it is empty so pipelines don't break
   if ( sts_isEmpty(sts) )
     return(sts)
 

diff --git a/R/sts_filterDate.R b/R/sts_filterDate.R
@@ -73,8 +73,9 @@ sts_filterDate <- function(
   if ( !sts_isValid(sts) )
     stop("Parameter 'sts' is not a valid 'sts' object.")
 
+  # Return the sts if it is empty so pipelines don't break
   if ( sts_isEmpty(sts) )
-    stop("Parameter 'sts' has no data.")
+    return(sts)
 
   # Remove any duplicate data records
   sts <- sts_distinct(sts)

diff --git a/R/sts_filterDatetime.R b/R/sts_filterDatetime.R
@@ -78,8 +78,9 @@ sts_filterDatetime <- function(
   if ( !sts_isValid(sts) )
     stop("Parameter 'sts' is not a valid 'sts' object.")
 
+  # Return the sts if it is empty so pipelines don't break
   if ( sts_isEmpty(sts) )
-    stop("Parameter 'sts' has no data.")
+    return(sts)
 
   # Remove any duplicate data records
   sts <- sts_distinct(sts)

diff --git a/R/sts_summarize.R b/R/sts_summarize.R
@@ -48,8 +48,9 @@ sts_summarize <- function(
   MazamaCoreUtils::stopIfNull(FUN)
   MazamaCoreUtils::stopIfNull(minCount)
 
-  if ( MazamaTimeSeries::sts_isEmpty(sts) )
-    stop("'sts' has no data")
+  # Return the sts if it is empty so pipelines don't break
+  if ( sts_isEmpty(sts) )
+    return(sts)
 
   if ( length(unique(sts$meta$timezone)) > 1 )
     stop("'sts' has muliple timezones")

diff --git a/R/sts_trimDate.R b/R/sts_trimDate.R
@@ -47,8 +47,9 @@ sts_trimDate <- function(
   if ( !sts_isValid(sts) )
     stop("'sts' is not a valid 'sts' object")
 
+  # Return the sts if it is empty so pipelines don't break
   if ( sts_isEmpty(sts) )
-    stop("'sts' has no data")
+    return(sts)
 
   # Remove any duplicate data records
   sts <- sts_distinct(sts)

diff --git a/R/timeInfo.R b/R/timeInfo.R
@@ -48,7 +48,7 @@
 #'
 #' @section Attribution:
 #' Internal functions used for ephemerides calculations were copied verbatim
-#' from the now deprecated \pkg{maptools} package source
+#' from the now deprecated \strong{maptools} package source
 #' code in an effort to reduce the number of package dependencies.
 #'
 #' @section Warning:
@@ -70,9 +70,9 @@
 #' \url{https://ecology.wa.gov/Research-Data/Data-resources/Models-spreadsheets/Modeling-the-environment/Models-tools-for-TMDLs}), who in turn
 #' translated it from original Javascript code by NOAA (see Details).
 #' Roger Bivand \email{[email protected]} adapted the code to work with
-#' \pkg{sp} classes. Jonathan Callahan \email{[email protected]}
-#' adapted the source code from the \pkg{maptools} package to work with
-#' \pkg{MazamaTimeSeries} classes.
+#' \strong{sp} classes. Jonathan Callahan \email{[email protected]}
+#' adapted the source code from the \strong{maptools} package to work with
+#' \href{https://mazamascience.github.io/MazamaTimeSeries/}{MazmaTimeSeries} classes.
 #'
 #' @section References:
 #' Meeus, J. (1991) Astronomical Algorithms. Willmann-Bell, Inc.

diff --git a/R/utils-mts.R b/R/utils-mts.R
@@ -49,9 +49,9 @@ mts_check <- function(mts) {
 #' Core \code{meta} columns include:
 #'
 #' \itemize{
-#'   \item{\code{deviceDeploymentID} -- unique identifier (see \pkg{MazmaLocationUtils})}
+#'   \item{\code{deviceDeploymentID} -- unique identifier (see \href{https://mazamascience.github.io/MazamaLocationUtils/}{MazmaLocationUtils})}
 #'   \item{\code{deviceID} -- device identifier}
-#'   \item{\code{locationID} -- location identifier (see \pkg{MazmaLocationUtils})}
+#'   \item{\code{locationID} -- location identifier (see \href{https://mazamascience.github.io/MazamaLocationUtils/}{MazmaLocationUtils})}
 #'   \item{\code{locationName} -- English language name}
 #'   \item{\code{longitude} -- decimal degrees E}
 #'   \item{\code{latitude} -- decimal degrees N}
-Original file line number
+Diff line change
@@ Expand Up / @@ -48,6 +48,7 @@ mts_arrange <- function( @@
         }
       }
+      # Return the mts if it is empty so pipelines don't break
       if ( mts_isEmpty(mts) )
         return(mts)
@@ Expand Down @@