Skip to contents

Filter camera trap data

Source: R/fct_data_wrangling.R
filter_data.Rd

Filter camera trap data observations and cameras metadata based on species, cameras and dates. Values will be filtered out by default, but if filter_out is FALSE they will be kept instead.

Usage

filter_data(
  dat,
  spp_filter = NULL,
  spp_col = NULL,
  obstype_filter = NULL,
  obstype_col = NULL,
  cam_filter = NULL,
  cam_col_rec = NULL,
  cam_col_cam = cam_col_rec,
  daterange = NULL,
  datetime_col = NULL,
  time_col = NULL,
  date_col = NULL,
  custom_filter = NULL,
  custom_col = NULL,
  tz = NULL,
  cam_as_factor = FALSE,
  filter_out = TRUE
)

Arguments

dat

The data to filter. It can be either a list with one component $data or a datapackage object (inheriting list). Either way, the data are in the $data slot with two components:

  • $deployments (cameras table)

  • $observations (records table)

spp_filter

Species to filter from the data

spp_col

Name of the species column (required if spp_filter is not NULL)

obstype_filter

Observation types to filter from the data

obstype_col

Name of the observation column (required if obstype_filter is not NULL)

cam_filter

Cameras to filter from the data

cam_col_rec

Name of the cameras column in records table (dat$data$observations). Required if cam_filter is not NULL.

cam_col_cam

Name of the cameras column in cameras table (dat$data$deployments). Defaults to the same value as cam_col_rec, and is required if cam_filter is not NULL.

daterange

Date range to filter on for the data (will filter observations' times so that times >= daterange[1] and times <= daterange[2]). Can be either a Date or a POSIX.

datetime_col

Name of the datetime column (must be coercible to POSIX). It is not needed if date_col and time_col are provided, but else it is required if daterange is not NULL.

time_col

Name of the time column. It is not needed if datetime_col is provided, but else it is required if daterange is not NULL.

date_col

Name of the date column. It is not needed if datetime_col is provided, but else it is required if daterange is not NULL.

custom_filter

values to filter out in the custom column custom_col.

custom_col

name of a custom column in to filter values in dat$data$observations (required if custom_filter is not NULL).

tz

Timezone for the data bounds. If not provided, will try to find the timezone in daterange (if it is a POSIX), then in datetime_col (if provided), and finally if no timezone is present it will default to UTC (Etc/GMT). For the filtering step, if needed datetimes in datetime_col can be converted to tz but the output data will not be affected.

cam_as_factor

Transform cameras as factors?

filter_out

Filter out (TRUE) or keep values?

Value

The filtered data. Species and dates remove data only in dat$data$observations, but cameras also remove cameras from dat$data$deployments.

Details

For the spp_filter, cam_filter, daterange and custom_col values: if they are NULL, data are not filtered on that condition. Also note that e.g. if all species are in spp_filter, then all species will be filtered out.

See also

vignette("filter-data", package = "camtrapviz"), filter_cameras_in_both_tables()

Examples

data("recordTableSample", package = "camtrapR")
recordTableSample$DateTimeOriginal <- as.POSIXct(recordTableSample$DateTimeOriginal)
data("camtraps", package = "camtrapR")
dat <- list(data = list(observations = recordTableSample,
                        deployments = camtraps))
# Filter out data for species PBE and VTA, camera Station A and keep
# only data from 2009-05-01 to 2009-05-15.
filter_data(dat, 
            spp_col = "Species", 
            spp_filter = c("PBE", "VTA"),
            cam_col_rec = "Station", 
            cam_filter = "StationA",
            daterange = as.Date(c("2009-05-01", "2009-05-15")),
            datetime_col = "DateTimeOriginal")
#> $data
#> $data$observations
#>     Station Species    DateTimeOriginal       Date     Time delta.time.secs
#> 8  StationC     EGY 2009-05-02 03:35:00 2009-05-02 03:35:00          443880
#> 14 StationC     TRA 2009-05-01 20:10:00 2009-05-01 20:10:00          417000
#> 15 StationC     TRA 2009-05-02 00:10:00 2009-05-02 00:10:00           14280
#> 16 StationC     TRA 2009-05-12 02:32:00 2009-05-12 02:32:00          872460
#>    delta.time.mins delta.time.hours delta.time.days
#> 8             7398            123.3             5.1
#> 14            6950            115.8             4.8
#> 15             238              4.0             0.2
#> 16           14541            242.3            10.1
#>                                                                                      Directory
#> 8  C:/Users/niedballa/Documents/R/win-library/3.1/camtrapR/pictures/sample_images/StationC/EGY
#> 14 C:/Users/niedballa/Documents/R/win-library/3.1/camtrapR/pictures/sample_images/StationC/TRA
#> 15 C:/Users/niedballa/Documents/R/win-library/3.1/camtrapR/pictures/sample_images/StationC/TRA
#> 16 C:/Users/niedballa/Documents/R/win-library/3.1/camtrapR/pictures/sample_images/StationC/TRA
#>                                 FileName
#> 8  StationC__2009-05-02__03-35-00(1).JPG
#> 14 StationC__2009-05-01__20-10-00(1).JPG
#> 15 StationC__2009-05-02__00-10-00(1).JPG
#> 16 StationC__2009-05-12__02-32-00(1).JPG
#> 
#> $data$deployments
#>    Station  utm_y  utm_x Setup_date Retrieval_date Problem1_from Problem1_to
#> 1 StationB 606000 523000 03/04/2009     16/05/2009                          
#> 2 StationC 607050 525000 04/04/2009     17/05/2009    12/05/2009  17/05/2009
#> 
#>