added fix dep interval and filter dep

NAMESPACE

@@ -31,7 +31,9 @@ export(drop_na_cols)
 export(dttmColNames)
 export(duplicateNames)
 export(effort_table)
+export(fill_na_interval)
 export(filter_apply)
+export(filter_deployments)
 export(filter_station)
 export(filter_timerange)
 export(filter_void)
@@ -64,6 +66,7 @@ export(primary_keys)
 export(printTimeZones)
 export(read_ctdp)
 export(removeEmptyCols)
+export(rm_empty_deployments)
 export(sequences)
 export(setCodedColNames)
 export(set_GMT_offset)

R/ctdp_periods.r

 #' @title Slice deployments with periods
 #' @description Slice deployments with periods
 #' @param x an object of class \code{\link{ctdp}}
-#' @param y a \code{tibble} with columns "name" and "interval": the result of function \code{\link{set_periods}}
+#' @param y a \code{tibble} with columns "name" and "interval": (e.g. the result of function \code{\link{set_periods}})
 #' @return an object of class \code{\link{ctdp}}
 #' @author Henjo de Knegt
 #' @seealso \code{\link{set_periods}}
 #' @examples \dontrun{
-#' ctdp_periods()
+#' # get overall time range of data
+#' time_range(camsample)
+#' plot_time_coverage(camsample)
+#' 
+#' # Set period intervals
+#' periods <- set_periods(start = c("4-21 08:00", "6-21 08:00"),
+#'                        end   = c("5-19 18:00", "7-19 18:00"), 
+#'                        orders = "md HM",
+#'                        years = 2017,
+#'                        tz = "Etc/GMT+5")
+#' 
+#' # Slice the ctdp object
+#' y <- ctdp_periods(camsample, periods)
+#' y
+#' y$deployments
+#' y$deployments %>% count(periodName)
+#' plot_time_coverage(y)
+#' 
+#' # Process further
+#' y <- filter_deployments(y, !is.na(periodName))
+#' y
+#' plot_time_coverage(y)
 #' }
 #' @export
 ctdp_periods <- function(x, y) {

R/fill_na_interval.r

+#' @title Fill the NAs in deployment interval using sequence info
+#' @description Fill the NAs in deployment interval using sequence info
+#' @details NULL
+#' @param x a \code{ctdp} object
+#' @return a \code{ctdp} object
+#' @author Henjo de Knegt
+#' @seealso NULL
+#' @examples NULL
+#' @export
+fill_na_interval <- function(x) {
+  # input checks
+  if(is_ctdp(x) == FALSE) { stop("x should be of class ctdp")}
+
+  # Check whether there are NAs in any of the deployment intervals
+  if(is.na(as.numeric(diff(time_range(x, based_on = "deployments"))))){
+    # At least 1 NA somewhere
+    dep_length <- map_dbl(x$deployments$deployment_interval, int_length)
+    
+    # Which deployment NA?
+    dep_na <- which(is.na(dep_length))
+    dep_naID <- x$deployments$deploymentID[dep_na]
+    
+    # Infer from sequences
+    for(i in seq_along(dep_na)){
+      # Get focal deployment
+      iID <- dep_naID[i]
+      
+      # filter sequence info
+      iSeq <- x$sequences %>% 
+        select(deploymentID, sequence_interval) %>% 
+        filter(deploymentID == iID)
+      
+      # time range sequences
+      tmin <- min(int_start(iSeq$sequence_interval))
+      tmax <- max(int_end(iSeq$sequence_interval))
+      
+      # Set as interval
+      x$deployments$deployment_interval[dep_na[i]] <- interval(start = tmin, end = tmax)
+    }
+  }else{
+    # No NAs
+  }
+  
+  # Return
+  return(x)
+}
\ No newline at end of file

R/filter_deployments.r

+#' Filter a ctdp object based on deployment properties
+#' @param x an object of class \code{\link{ctdp}}
+#' @param subset arguments used for filtering
+#' @return x an object of class \code{\link{ctdp}}
+#' @author Henjo de Knegt
+#' @seealso \code{\link{ctdp}}
+#' @examples \dontrun{
+#' # Just to plug in some dummy data
+#' y <- camsample
+#' y$habitat <- 1:42
+#' deployments(y)
+#' filter_deployments(y, habitat > 10)
+#' }
+#' @export
+filter_deployments <- function(x, subset = NULL) {
+  # Get deployment table
+  xdep <- x$deployments
+  
+  # Perform the filtering on it
+  dofilter <- match.call(expand.dots = FALSE)$subset
+  r <- eval(dofilter, xdep, parent.frame(1L))
+  xsub <- xdep[r,]
+  
+  # Filter the rest of object x accordingly
+  x$deployments <- xsub
+  x$locations <- x$locations %>%
+    filter(locationID %in% xsub$locationID)
+  x$sequences <- x$sequences %>%
+    filter(deploymentID %in% x$deployments$deploymentID)
+  x$observations <- x$observations %>%
+    filter(sequenceID %in% x$sequences$sequenceID)
+  x$media <- x$media %>%
+    filter(sequenceID %in% x$sequences$sequenceID)
+  
+  # Return x
+  return(x)
+}
\ No newline at end of file

R/rm_empty_deployments.r

+#' @title Remove deployments with insufficient (meta)data
+#' @description Remove deployments with insufficient (meta)data
+#' @details This function removes deployments when there either is no depoloyment identifier, or there is an identifyer but no correct deployment interval (NA for start and/or end) _and_ not sufficient sequence data (\code{< minNrSeqs} records)
+#' @param x a \code{ctdp} object
+#' @param minNrSeqs minimum \code{integer} number of sequences (deployment is removed if there are \code{< minNrSeqs} records)
+#' @return a \code{ctdp} object
+#' @author Henjo de Knegt
+#' @seealso NULL
+#' @examples NULL
+#' @export
+rm_empty_deployments <- function(x, minNrSeqs = 2) {
+  # input checks
+  if(is_ctdp(x) == FALSE) { stop("x should be of class ctdp")}
+
+  # Remove records in the $deployment table if there is NA in deploymentID
+  x$deployments <- x$deployment %>% 
+    drop_na(deploymentID)
+  
+  # Check whether there are NAs in any of the deployment intervals
+  if(is.na(as.numeric(diff(time_range(x, based_on = "deployments"))))){
+    # At least 1 NA somewhere
+    dep_length <- map_dbl(x$deployments$deployment_interval, int_length)
+    
+    # Which deployment NA?
+    dep_na <- which(is.na(dep_length))
+    dep_naID <- x$deployments$deploymentID[dep_na]
+    
+    # list of deploymentIDs to remove
+    rmDepIDs <- list()
+    ii <- 1
+    
+    # Infer from sequences
+    for(i in seq_along(dep_na)){
+      # Get focal deployment
+      iID <- dep_naID[i]
+      
+      # filter sequence info
+      iSeq <- x$sequences %>% 
+        select(deploymentID, sequence_interval) %>% 
+        filter(deploymentID == iID)
+      
+      # IS there sequence data for this depoloyment?
+      if(nrow(iSeq) < minNrSeqs) {
+        rmDepIDs[[ii]] <- iID
+        ii <- ii + 1L
+      }
+    }
+    
+    # Process if there are deployments to remove
+    if(length(rmDepIDs) > 0) {
+      # unlist
+      rmDepIDs <- unlist(rmDepIDs)
+      
+      # Remove 
+      x$deployments <- x$deployments %>% 
+        filter(! deploymentID %in% rmDepIDs)
+      x$sequences <- x$sequences %>% 
+        filter(! deploymentID %in% rmDepIDs)
+      
+      # Also rest
+      keepSeqIDs <- x$sequences$sequenceID
+      x$observations <- x$observations %>% 
+        filter(sequenceID %in% keepSeqIDs)
+      x$media <- x$media %>% 
+        filter(sequenceID %in% keepSeqIDs)
+    }
+  }
+
+  # Return
+  return(x)
+}
\ No newline at end of file

R/set_periods.r

@@ -5,22 +5,72 @@
 #' @seealso NULL
 #' @return xxx still to write
 #' @examples \dontrun{
+#' # Either using start/end timestamps (in format POSIXct)
 #' start <- seq(from = ISOdatetime(2022,11,1,0,0,0,tz="Etc/GMT-2"), 
 #'              to = ISOdatetime(2022,12,7,0,0,0,tz="Etc/GMT-2"),
 #'              by = "2 weeks")
 #' set_periods(start = start, 
 #'             end = start + period(2, units = "weeks"),
 #'             name = paste0("p", seq_along(start)))
+#'             
+#' # OR: using vector of years, and start/ends are character vectors (recurrent within each year)       
+#' set_periods(start = c("4-21 08:00", "6-21 08:00"),
+#'             end = c("5-19 18:00", "7-19 18:00"), 
+#'             orders = "md HM",
+#'             years = 2017:2020,
+#'             tz = "Etc/GMT+5")
 #' }
 #' @export
-set_periods <- function(start, end, name = NULL) {
+set_periods <- function(start, end,
+                        name = NULL,
+                        years = NULL,
+                        orders = "md HM", 
+                        tz = NULL) {
   # Checks
-  warning("still to implement checks")
+  if(missing(start)){stop("supply start")}
+  if(missing(end)){stop("supply end")}
+  n <- length(start)
+  if(length(end) != n){stop("length of start and end should be equal")}
+  if(!is.null(name)){
+    if(length(name) != n){stop("when supplying name, it should equal the length of start and end")}
+  }
   
   # Overwrite name (if NULL)
   if(is.null(name)){
     name <- paste0("p", seq_along(start))
   }
+
+  # Supplying years, thus start and end are character (with orders and tz), then expand grid
+  if(!is.null(years)){
+    # start and end are posixct
+    if(!is.character(start)){stop("start should be of class character (when input to years is supplied")}
+    if(!is.character(end)){stop("end should be of class character (when input to years is supplied")}
+    if(missing(tz)){stop("supply tz")}
+    if(str_detect(tolower(orders), pattern = "y")){stop("orders (and thus also start and end) should not include a year identifier (y or Y)")}
+    ordersFull <- str_c("Y", orders, sep = " ")
+    
+    # expand grid
+    ints <- tibble(year = rep(years, each = length(start)), 
+                   start = rep(start, times = length(years)),
+                   end = rep(end, times = length(years)),
+                   name = rep(name, times = length(years))) %>% 
+      as_tibble() %>% 
+      mutate(start = str_c(year, start, sep = "-"),
+             end = str_c(year, end, sep = "-"),
+             start = parse_date_time(start, orders = ordersFull, tz = tz),
+             end = parse_date_time(end, orders = ordersFull, tz = tz),
+             interval = interval(start = start, end = end),
+             name = str_c(year, name, sep = "_"))
+    
+    # Overwrite
+    start <- ints$start
+    end <- ints$end
+    name <- ints$name
+  }else{
+    # start and end are POSIXct
+    if(!is.POSIXct(start)){stop("start should be of class POSIXct (when no input to years is supplied")}
+    if(!is.POSIXct(end)){stop("end should be of class POSIXct (when no input to years is supplied")}
+  }
   
   # merge into tibble
   prds <- tibble(name = name,

inst/extdata/ctdp_tutorial - Copy.Rmd

+---
+params:
+  path: NA
+  data: NA
+  title: NA
+  focalSpecies: NA
+  start : NA
+  end: NA
+output:
+  html_document:
+    toc: yes
+    toc_float: yes
+---
+
+```{r, include=FALSE}
+# load libraries
+library(ctdp)
+
+# set knitr options
+knitr::opts_chunk$set(echo = TRUE,
+                      eval = TRUE,
+                      warning = FALSE,
+                      message = FALSE)
+
+# options for width
+options(width = 100)
+
+# get elements from params
+title <- params$title
+dat <- params$data
+path <- params$path
+focalSpecies <- params$focalSpecies
+start <- params$start
+end <- params$end
+
+# Checks on inputs
+if(is.na(path) & is.na(dat)) { stop("supply either path or dat") }
+if(!is.na(dat) & is.na(path)) {
+  path <- dat$settings$path
+}
+if(is.na(dat)) {
+  dat <- read_ctdp(path)
+}
+```
+
+---
+title: `r title`
+subtitle: `r paste0("Project ", pathProperties(path)$fileFolder)`
+date: `r Sys.Date()`
+---
+
+<!-- ######################################################################################## -->
+# Installing the package
+
+The `ctdp` package is an R package to load and process camera-trap data stored in  [camtrap-dp](https://tdwg.github.io/camtrap-dp/) format. The package builds upon the [frictionless](https://docs.ropensci.org/frictionless/) and [camtraptor](https://inbo.github.io/camtraptor/) packages, which first need to be installed (using the `devtools` package, which may need installation first) from github:
+
+```{r, echo=TRUE, eval=FALSE}
+devtools::install_github("frictionlessdata/frictionless-r")
+devtools::install_github("inbo/camtraptor")
+```
+
+Then, install the `ctdp` package from the WUR gitlab repo:
+
+```{r, echo=TRUE, eval=FALSE}
+devtools::install_gitlab(repo = "camtrap/ctdp", host = "git.wur.nl")
+```
+
+<!-- ######################################################################################## -->
+# The ctdp package and data structure
+
+The main data structure of the `ctdp` package is an object of class `ctdp`, which essentially is a named `list` with a "settings" slot (a list with settings), and 6 `tibbles`, which together form a relational database: 
+
+![](`r system.file("extdata", "ctdp-structure.png", package = "ctdp")`)
+
+<!-- ######################################################################################## -->
+# Loading data {.tabset .tabset-fade}
+
+## Example dataset
+
+The `ctdp` package contains an example dataset: `camsample`:
+
+```{r}
+camsample
+```
+
+## Loading a camtrap-dp export
+
+A camtrap-dp export can be loaded Via the function `read_ctdp`
+
+single file (.zip)
+
+unzipped folder
+
+see function `set_GMT_offset`
+
+```{r}
+set_GMT_offset(-5)
+```
+
+<pre class="r"><code class="hljs">dat &lt;- read_ctdp("`r path`",
+                 tz = "`r time_zone(dat)`")</code></pre>
+
+```{r}
+dat
+```
+
+## Camtraptor conversion
+
+Using function `as_ctdp` you can convert an object read via the `read_camtrap_dp` of the `camptraptor` package into an object of class `ctdp`:
+
+```{r, eval = FALSE, echo = TRUE}
+x <- read_camtrap_dp("C:/data/ctdp/bcnm-mammal-monitoring-team-20230223112118/datapackage.json",
+                     tz = "Etc/GMT+5")
+dat <- as_ctdp(x)
+```
+               
+## Loading multiple exports
+
+Todo: function `read_ctdp_list` to load a series of exports into a single `ctdp` object.
+
+<!-- ######################################################################################## -->
+# Integrity checks {.tabset .tabset-fade}
+
+## Overview
+
+function `check_integrity` function will become available which will be a wrapper function perfoming various checks, see "Specifics" tab
+
+## Specifics
+
+```{r}
+check_annotations(dat)
+
+test <- check_deployments(dat)
+test %>% filter(nr_false != 0) %>% slice_head(n=1) %>% str()
+
+check_duplicates(dat)
+
+check_joins(dat)
+```
+
+<!-- ######################################################################################## -->
+# Retrieving information {.tabset .tabset-fade}
+
+## General elements
+
+Several functions allow you to retrieve general information from an object of class `ctdp`:
+
+```{r}
+is_ctdp(dat)
+is.na(dat)
+time_zone(dat)
+time_range(dat)
+primary_keys(dat)
+has_media(dat)
+column_names(dat)
+```
+
+## Locations
+
+Information on camera trap locations can be retrieved in different, equivalent, ways:
+
+```{r, eval = FALSE}
+locations(dat)
+get_table(dat, "locations")
+dat$locations
+```
+
+For example:
+
+```{r}
+locations(dat)
+```
+
+Retrieving the locations information without the `longitude` and `latitude` columns:
+
+```{r}
+locations(dat, addLonlat = FALSE)
+```
+
+## Deployments
+
+Information on camera trap deployments can be retrieved in different, equivalent, ways:
+
+```{r, eval = FALSE}
+deployments(dat)
+get_table(dat, "deployments")
+dat$deployments
+```
+
+For example:
+
+```{r}
+deployments(dat)
+```
+
+## Sequences
+
+Information on sequences can be retrieved in different, equivalent, ways:
+
+```{r, eval = FALSE}
+sequences(dat)
+get_table(dat, "sequences")
+dat$sequences
+```
+
+For example:
+
+```{r}
+sequences(dat)
+```
+
+## Observations
+Information on observations can be retrieved in different, equivalent, ways:
+
+```{r, eval = FALSE}
+observations(dat)
+get_table(dat, "observations")
+dat$observations
+```
+
+For example:
+
+```{r}
+observations(dat)
+```
+
+## Taxonomy
+
+Information on the used taxonomy can be retrieved in different, equivalent, ways:
+
+```{r, eval = FALSE}
+taxonomy(dat)
+get_table(dat, "taxonomy")
+dat$taxonomy
+```
+
+For example:
+
+```{r}
+taxonomy(dat)
+```
+
+To retrieve the classes, orders, species names, and taxon identifiers:
+
+```{r}
+taxon_classes(dat)
+taxon_orders(dat)
+taxon_species(dat)
+taxon_id(dat)
+```
+
+To get the taxon identifiers (column "taxonID") of specific species:
+
+```{r}
+taxon_id(dat, spp = "lowland paca")
+```
+
+The function also works with variations in writing:
+
+```{r}
+taxon_id(dat, spp = "lowland paca")
+taxon_id(dat, spp = "LowlandPaca")
+taxon_id(dat, spp = "_LowLand_ PaCa")
+```
+
+## Media
+
+Whether or not the object has media data included can be checked with the `has_media` function:
+
+```{r}
+has_media(dat)
+```
+
+Information on media can be retrieved in different, equivalent, ways:
+
+```{r, eval = FALSE}
+media(dat)
+get_table(dat, "media")
+dat$media
+```
+
+For example:
+
+```{r}
+media(dat)
+```
+
+<!-- ######################################################################################## -->
+# Basic manipulations {.tabset .tabset-fade}
+
+## General
+
+some functions
+
+distinct
+
+ctdp_interval
+
+drop_na_columns
+
+drop_media
+
+can be linked in pipeline via `%>%`
+
+```{r}
+dat %>% 
+  ctdp_interval() %>% 
+  distinct() %>% 
+  drop_na_cols() %>% 
+  drop_media()
+```
+
+`drop_columns` removes all columns except those listed in data `ctdp_mainCols`
+
+## Adding location information
+
+The `add_location_info` function allows adding information to the `locations` table (automatically matched by the identifier and other matching columns:
+
+```{r}
+datInfo <- locations(dat)
+datInfo <- datInfo %>% 
+  mutate(group = str_sub(locationName, 1, 5))
+dat <- add_location_info(dat, datInfo)
+locations(dat)
+```
+
+<!-- ######################################################################################## -->
+# Filters and selectors {.tabset .tabset-fade}
+
+## Based on station properties
+
+The `filter_station` allows to filter an object of class `ctdp` by the properties of a camera station:
+
+```{r}
+filter_station(dat, transect == 1)
+```
+
+## filter based on time range
+
+The `filter_timerange` allows to truncate an object of class `ctdp` by specifying start and end points in time (see the `orders` argument for how to specify these):
+
+```{r}
+filter_timerange(dat, start = "2017/4/1", end = "2017/8/1")
+```
+
+## Strip columns
+
+Columns that are not part of the main columns as specified in the dataset `ctdp_mainCols` can be removed using `drop_columns`:
+
+```{r}
+drop_columns(dat)
+```
+
+<!-- ######################################################################################## -->
+# Exploration {.tabset .tabset-fade}
+
+## Locations
+
+Locations can be plotted on a leaflet map using function `plot_locations`:
+
+```{r, eval = FALSE}
+plot_locations(dat)
+```
+
+```{r, echo = FALSE, out.width = '100%'}
+p <- plot_locations(dat, doPlot = FALSE)
+p
+```
+
+## Time coverage
+
+The `plot_time_coverage` plot the time coverage of the deployments:
+
+```{r, echo = TRUE, eval = FALSE}
+plot_time_coverage(dat)
+```
+```{r, echo = FALSE, eval = TRUE}
+p <- plot_time_coverage(dat, doPlot = FALSE)
+print(p)
+```
+
+or, when grouping by some column (y-axis ordering and colour):
+
+```{r}
+plot_time_coverage(dat, grouping = "transect")
+```
+
+```{r, echo = TRUE, eval = FALSE}
+plot_time_coverage(dat, grouping = "transect")
+```
+```{r, echo = FALSE, eval = TRUE}
+p <- plot_time_coverage(dat, grouping = "transect", doPlot = FALSE)
+print(p)
+```
+
+## Annotation status
+
+Some functions allow you to explore the annotation status: `plot_status`, `summarise_deployments` and `fraction_annotated`:
+```{r, echo = TRUE, eval = FALSE}
+plot_status(dat)
+```
+```{r, echo = FALSE, eval = TRUE}
+p <- plot_status(dat, doPlot = FALSE)
+p
+```
+
+or, when grouping by some column (y-axis ordering and colour):
+
+```{r, echo = TRUE, eval = FALSE}
+plot_status(dat, grouping = "transect")
+```
+```{r, echo = FALSE, eval = TRUE}
+p <- plot_status(dat, grouping = "transect", doPlot = FALSE)
+p
+```
+
+The status of deployments (or other groupings) can also be obtained in table form, using the `summarise_deployments` function:
+
+```{r}
+summarise_deployments(dat)
+```
+
+The `datatable` argument specifies whether or not to view the table in an interactive datatable in the viewer:
+
+```{r, echo = TRUE, eval = FALSE}
+summarise_deployments(dat, datatable = TRUE)
+```
+
+```{r, echo = FALSE, eval = TRUE}
+p <- summarise_deployments(dat, datatable = FALSE)
+p %>% 
+      mutate(effort = round(effort, 3),
+             fracAnnotated = round(fracAnnotated, 3)) %>% 
+      datatable(caption = "Deployment summary",
+                style = "auto")
+```
+
+Function `summarise_deployment` calls other function `fraction_annotated`:
+
+```{r}
+fraction_annotated(dat)
+```
+
+<!-- ######################################################################################## -->
+# Analyses {.tabset .tabset-fade}
+
+## Effort
+
+To plot the effort over time (defaults to a dynamic plot):
+
+```{r, out.width = '100%'}
+plot_effort(dat)
+```
+
+or, static ggplot plot, pass argument `dynamic = FALSE`, i.e. `plot_effort(dat, dynamic = FALSE)`.
+
+To get a point estimate: the number of active camera stations at a given time:
+
+```{r}
+point_effort(dat, "2017/6/21 12:00:00")
+```
+
+Tthe `calc_effort` function is the main function computing effort (total number of camera-trap days), which optionally takes arguments:
+
+* `by`: column name(s) of the station/deployment tables by which to group the effort computation
+* `start`,`end`: start and end timepoints to truncate the data, see function `filter_timerange`
+* `subset`: an expression to filter the camera station locations, see function `filter_station`
+
+Total effort:
+
+```{r}
+calc_effort(dat)
+```
+
+Total effort computer for each station identified by column "locationName":
+```{r}
+calc_effort(dat, by = "locationName")
+```
+
+Idem, but now for specified time range and transect:
+
+```{r}
+calc_effort(dat,
+            by = "locationName",
+            start = "2017/4/1",
+            end = "2017/8/1",
+            subset = transect == 3)
+```
+
+Another option to compute the total effort (total number of active camera-trap-days) is via the function `integrate_effort`:
+
+```{r}
+integrate_effort(dat)
+```
+
+Or, between 2 time points, integrate effort, thus compute total number of active camera-trap-days between these two points in time:
+
+```{r}
+integrate_effort(dat, start = "2017/4/1", end = "2017/8/1")
+```
+
+## Catpure rates
+
+The `captures` function is the main function to compute captures and capture rates:
+
+```{r}
+captures(dat)
+```
+
+Optionally, you can specify a taxonomic class to focus on:
+
+```{r}
+captures(dat, class = "Mammalia")
+```
+
+Or, focus on specific species (access via function `taxon_id`):
+
+```{r}
+captures(dat, species = c("Central American agouti","CollaredPeccary"))
+```
+
+Like in the computation of effort, capture rates can be computed using the arguments `by`, `start/end`, `subset` in order to group analyses by some identifier column, compute for a subset of the locations or truncate in time, e.g.:
+
+```{r}
+captures(dat,
+         species = c("Central American agouti","CollaredPeccary"),
+         by = "locationName",
+         start = "2017/4/1",
+         end = "2017/8/1",
+         subset = transect == 3)
+```
+
+## Activity patterns
+
+Activity patterns can be fitted and plotted using the `activity_ctdp` function, in a similar veign as the `captures` and `calc_effort` functions do:
+
+```{r}
+activity_ctdp(dat)
+```
+
+focussing on taxonomic class:
+
+```{r}
+activity_ctdp(dat, class = "Mammalia")
+```
+
+Or, for some specific species in a subset of the stations
+
+```{r}
+activity_ctdp(dat,
+         species = c("Central American agouti","CollaredPeccary"),
+         by = "locationName",
+         start = "2017/4/1",
+         end = "2017/8/1",
+         subset = transect == 3)
+```
+
+The function returns the data silently:
+
+```{r}
+test <- activity_ctdp(dat,
+                      species = c("Central American agouti","CollaredPeccary"),
+                      by = "locationName",
+                      start = "2017/4/1",
+                      end = "2017/8/1",
+                      subset = transect == 3)
+test
+```
+
+<!-- ######################################################################################## -->
+# Merges
+
+The `merge_tibbles` and `nest_tibbles` join all the tibbles of the relational database into 1 bit tibble, where the `merge_tibbles` results in 1 record (i.e. row) being a single _observation_, whereas when using the `nest_tibbles` function, 1 row equals to 1 _sequence_ where the observations and other information are stored as _list columns_.
+
+```{r}
+merge_tibbles(dat) # 1 row = 1 observation
+```
+
+```{r}
+nest_tibbles(dat) # 1 row = 1 sequence
+```
+
+To unnest a list-column, e.g. here the "locations" column:
+
+```{r}
+nest_tibbles(dat) %>% 
+  unnest(locations)
+```
+
+<!-- ######################################################################################## -->
+# Exports {.tabset .tabset-fade}
+
+## Tutorial
+
+this tutorial was generated using the command:
+
+```{r, echo=TRUE, eval=FALSE}
+write_tutorial(dat)
+```
+
+
+## Excel sheets
+
+todo
+
+<!-- ######################################################################################## -->
+

inst/extdata/ctdp_tutorial.Rmd

@@ -118,6 +118,22 @@ dat <- as_ctdp(x)
 
 Todo: function `read_ctdp_list` to load a series of exports into a single `ctdp` object.
 
+## Fixing deployment info
+
+sometimes: NA in deployment interval, or even entire row of deployment info missing (apart from deployment identifier).
+
+Function `fill_na_interval` imputes the missing start/end points of a deployment interval by retrieving the timestamp of the first/last sequence for that deployment:
+
+```{r, eval = FALSE, echo = TRUE}
+dat <- fill_na_interval(dat)
+```
+
+If, however, there are no sequences for that deployment, AND the deployment interval contains NA (either start or end or both), then that record can be removed from the deployments table using the `rm_empty_deployments` function:
+
+```{r, eval = FALSE, echo = TRUE}
+dat <- rm_empty_deployments(dat, minNrSeqs = 2)
+```
+
 <!-- ######################################################################################## -->
 # Integrity checks {.tabset .tabset-fade}
 
@@ -335,6 +351,14 @@ The `filter_station` allows to filter an object of class `ctdp` by the propertie
 filter_station(dat, transect == 1)
 ```
 
+## Based on deployment properties
+
+The `filter_deployments` allows to filter an object of class `ctdp` by the properties of the deployments table, here e.g. all deployments that started in the first 6 month of the year:
+
+```{r, echo = TRUE, eval = FALSE}
+filter_deployments(dat, month(int_start(deployment_interval)) <= 6)
+```
+
 ## filter based on time range
 
 The `filter_timerange` allows to truncate an object of class `ctdp` by specifying start and end points in time (see the `orders` argument for how to specify these):

man/ctdp_periods.Rd

@@ -9,7 +9,7 @@ ctdp_periods(x, y)
 \arguments{
 \item{x}{an object of class \code{\link{ctdp}}}
 
-\item{y}{a \code{tibble} with columns "name" and "interval": the result of function \code{\link{set_periods}}}
+\item{y}{a \code{tibble} with columns "name" and "interval": (e.g. the result of function \code{\link{set_periods}})}
 }
 \value{
 an object of class \code{\link{ctdp}}
@@ -19,7 +19,28 @@ Slice deployments with periods
 }
 \examples{
 \dontrun{
-ctdp_periods()
+# get overall time range of data
+time_range(camsample)
+plot_time_coverage(camsample)
+
+# Set period intervals
+periods <- set_periods(start = c("4-21 08:00", "6-21 08:00"),
+                       end   = c("5-19 18:00", "7-19 18:00"), 
+                       orders = "md HM",
+                       years = 2017,
+                       tz = "Etc/GMT+5")
+
+# Slice the ctdp object
+y <- ctdp_periods(camsample, periods)
+y
+y$deployments
+y$deployments \%>\% count(periodName)
+plot_time_coverage(y)
+
+# Process further
+y <- filter_deployments(y, !is.na(periodName))
+y
+plot_time_coverage(y)
 }
 }
 \seealso{

man/fill_na_interval.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fill_na_interval.r
+\name{fill_na_interval}
+\alias{fill_na_interval}
+\title{Fill the NAs in deployment interval using sequence info}
+\usage{
+fill_na_interval(x)
+}
+\arguments{
+\item{x}{a \code{ctdp} object}
+}
+\value{
+a \code{ctdp} object
+}
+\description{
+Fill the NAs in deployment interval using sequence info
+}
+\examples{
+NULL
+}
+\author{
+Henjo de Knegt
+}

man/filter_deployments.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/filter_deployments.r
+\name{filter_deployments}
+\alias{filter_deployments}
+\title{Filter a ctdp object based on deployment properties}
+\usage{
+filter_deployments(x, subset = NULL)
+}
+\arguments{
+\item{x}{an object of class \code{\link{ctdp}}}
+
+\item{subset}{arguments used for filtering}
+}
+\value{
+x an object of class \code{\link{ctdp}}
+}
+\description{
+Filter a ctdp object based on deployment properties
+}
+\examples{
+\dontrun{
+# Just to plug in some dummy data
+y <- camsample
+y$habitat <- 1:42
+deployments(y)
+filter_deployments(y, habitat > 10)
+}
+}
+\seealso{
+\code{\link{ctdp}}
+}
+\author{
+Henjo de Knegt
+}

man/rm_empty_deployments.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/rm_empty_deployments.r
+\name{rm_empty_deployments}
+\alias{rm_empty_deployments}
+\title{Remove deployments with insufficient (meta)data}
+\usage{
+rm_empty_deployments(x, minNrSeqs = 2)
+}
+\arguments{
+\item{x}{a \code{ctdp} object}
+
+\item{minNrSeqs}{minimum \code{integer} number of sequences (deployment is removed if there are \code{< minNrSeqs} records)}
+}
+\value{
+a \code{ctdp} object
+}
+\description{
+Remove deployments with insufficient (meta)data
+}
+\details{
+This function removes deployments when there either is no depoloyment identifier, or there is an identifyer but no correct deployment interval (NA for start and/or end) _and_ not sufficient sequence data (\code{< minNrSeqs} records)
+}
+\examples{
+NULL
+}
+\author{
+Henjo de Knegt
+}

man/set_periods.Rd

@@ -4,7 +4,7 @@
 \alias{set_periods}
 \title{Specify time periods}
 \usage{
-set_periods(start, end, name = NULL)
+set_periods(start, end, name = NULL, years = NULL, orders = "md HM", tz = NULL)
 }
 \arguments{
 \item{xxx}{still to write}
@@ -17,12 +17,20 @@ Specify time periods
 }
 \examples{
 \dontrun{
+# Either using start/end timestamps (in format POSIXct)
 start <- seq(from = ISOdatetime(2022,11,1,0,0,0,tz="Etc/GMT-2"), 
              to = ISOdatetime(2022,12,7,0,0,0,tz="Etc/GMT-2"),
              by = "2 weeks")
 set_periods(start = start, 
             end = start + period(2, units = "weeks"),
             name = paste0("p", seq_along(start)))
+            
+# OR: using vector of years, and start/ends are character vectors (recurrent within each year)       
+set_periods(start = c("4-21 08:00", "6-21 08:00"),
+            end = c("5-19 18:00", "7-19 18:00"), 
+            orders = "md HM",
+            years = 2017:2020,
+            tz = "Etc/GMT+5")
 }
 }
 \author{