birdscanR (version 0.3.0)

filterData: filterData

Description

With the function filterData both the echo and protocol data can be filtered by several parameters. The function returns the filtered echo and protocol data.

Usage

filterData(
  echoData = NULL,
  protocolData = NULL,
  pulseTypeSelection = NULL,
  rotationSelection = NULL,
  timeRangeTargetTZ = NULL,
  targetTimeZone = "Etc/GMT0",
  classSelection = NULL,
  classProbCutOff = NULL,
  altitudeRange_AGL = NULL,
  manualBlindTimes = NULL,
  echoValidator = FALSE
)

Value

returns the filtered echo and protocol data in the same format as provided in the parameters echoData and protocolData.

Arguments

echoData

dataframe with the echo data from the data list created by the function extractDBData.

protocolData

dataframe with the protocol data from the data list created by the function extractDBData or a subset of it created by the function filterProtocolData. Echoes not detected during the listed protocols will be excluded.

pulseTypeSelection

character vector with the pulse types which should be included in the subset. Options: “S”, “M”, “L” (short-, medium-, long-pulse). Default is NULL: no filtering applied based on pulseType.

rotationSelection

numeric vector to select the operation modes with and/or without antenna rotation. Options: 0, 1. (0 = no rotation, 1 = rotation). Default is NULL: no filtering applied based on rotation mode.

timeRangeTargetTZ

Character vector of length 2, with start and end of time range, formatted as "%Y-%m-%d %H:%M". Echoes outside the time range will be excluded.

targetTimeZone

"Etc/GMT0" String specifying the target time zone. Default is "Etc/GMT0".

classSelection

character string vector with the classes that should be included.

classProbCutOff

numeric cutoff value for class probabilities. Echoes with a lower class probability will be excluded.

altitudeRange_AGL

numeric vector of length 2 with start and end of the altitude range. Echoes outside the altitude range will be excluded.

manualBlindTimes

dataframe with the manual blind times created by the function loadManualBlindTimes.

echoValidator

logical, if set to TRUE, echoes labelled by the echo validator as “non-bio scatterer” will be excluded. If set to FALSE, all echoes are included.

Author

Birgen Haest,

Examples

if (FALSE) {
# Set server, database, and other input settings for data extraction
# ===========================================================================
  dbServer       = "MACHINE\\SERVERNAME"     # Set the name of your SQL server
  dbName         = "db_Name"                   # Set the name of your database
  dbDriverChar   = "SQL Server"                # Set either "SQL Server" or "PostgreSQL"
  mainOutputDir  = file.path(".", "results")
  radarTimeZone  = "Etc/GMT0"
  targetTimeZone = "Etc/GMT0"
  listOfRfFeaturesToExtract = c(167, 168)
  siteLocation   = c(47.494427, 8.716432)
  sunOrCivil     = "civil"
 
# Get data
# ===========================================================================
  dbData = extractDbData(dbDriverChar                   = dbDriverChar,
                         dbServer                       = dbServer, 
                         dbName                         = dbName, 
                         saveDbToFile                   = TRUE,
                         dbDataDir                      = mainOutputDir,
                         radarTimeZone                  = radarTimeZone,
                         targetTimeZone                 = targetTimeZone,
                         listOfRfFeaturesToExtract      = listOfRfFeaturesToExtract,
                         siteLocation                   = siteLocation, 
                         sunOrCivil                     = sunOrCivil)
                         
# Set input settings for filtering of the data
# ===========================================================================
  pulseLengthSelection = "S"
  rotationSelection    = 1
  timeRangeData        = c("2021-01-15 00:00", "2021-01-31 00:00")
  classSelection       = c("passerine_type", "wader_type", "swift_type", 
                           "large_bird", "unid_bird", "bird_flock")
  classProbCutoff      = NULL
  altitudeRange        = c(50, 1000)
  data(manualBlindTimes)
  cManualBlindTimes    = manualBlindTimes
  useEchoValidator     = FALSE

# Filter the data
# ===========================================================================
  filteredData = filterData(echoData           = dbData$echoData,
                            protocolData       = dbData$protocolData, 
                            pulseTypeSelection = pulseLengthSelection, 
                            rotationSelection  = rotationSelection,
                            timeRangeTargetTZ  = timeRangeData,
                            targetTimeZone     = targetTimeZone,
                            classSelection     = classSelection, 
                            classProbCutOff    = classProbCutoff, 
                            altitudeRange_AGL  = altitudeRange, 
                            manualBlindTimes   = cManualBlindTimes, 
                            echoValidator      = useEchoValidator)   
}