Package 'birdscanR'

Description

addDayNightInfoPerEcho() adds three columns ‘dayOrNight’, ”dayOrCrepOrNight' and ‘dateSunset’ to the echo data. This allows the user to filter echo data easily by “day” and “night”, or "day", "crepuscular", and "night".

Usage

addDayNightInfoPerEcho(
  echoData,
  sunriseSunset,
  sunOrCivil = "civil",
  crepuscule = "nauticalSolar"
)

Arguments

Value

data frame with thre columns added, i.e. 'dayOrNight', 'dayOrCrepOrNight', and 'dateSunset'.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other manipulation functions: computeDensity(), computeMTR(), convertTimeZone(), createVPTS(), filterSpeedFeature37(), mergeVisibilityAndManualBlindTimes(), reclassToBats(), twilight()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Add day/night info to echo data
# ===========================================================================
echoData = addDayNightInfoPerEcho(
  echoData      = dbData$echoData,
  sunriseSunset = dbData$sunriseSunset,
  sunOrCivil    = "civil"
)

Description

A complete data extract from a Birdscan MR1 weather radar, as returned by extractDbData(). Collected at Sempach, Switzerland (47.13°N, 8.19°E) on September 24–25, 2024. Load with: readRDS(system.file("extdata", "CH_Sempach_2024_SEP24_25_DataExtract.rds", package = "birdscanR"))

Format

A named list as returned by extractDbData(), with components:

echoData

data.frame with one row per detected echo

protocolData

data.frame with protocol/collection intervals

siteData

data.frame with radar site metadata

visibilityData

data.frame with automatic visibility/blind times

timeBinData

data.frame with raw time-bin table from the database

availableClasses

character vector of classification labels

availableBatClasses

character vector of bat classification labels

rfFeatures

data.frame with RF feature metadata

TimeZone

data.frame with radarTimeZone and targetTimeZone

classProbabilitiesAndMtrFactors

data.frame with class probabilities

batProbabilitiesAndMtrFactors

data.frame with bat class probabilities

sunriseSunset

data.frame with sunrise/sunset and civil twilight times

See Also

Other sample data: classAbbreviations, loadManualBlindTimes(), manualBlindTimes

Examples

dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

Description

Table to allow for easy abbreviations of the standard classes of the Birdscan MR1.

Usage

data(classAbbreviations)

Format

An object of class data.frame.

See Also

Other sample data: CH_Sempach_2024_SEP24_25_DataExtract, loadManualBlindTimes(), manualBlindTimes

Examples

data(classAbbreviations)

Description

compileData() filters database-extracts and save metadata used to compute MTR computeMTR(). It takes the output from extractDbData() and trunks the needed dataset to the restricted settings, e.g. time frame, pulse type.

Usage

compileData(
  echoData = NULL,
  protocolData = NULL,
  blindTimesData = NULL,
  sunriseSunsetData = NULL,
  radarSiteData = NULL,
  dbName = NULL,
  pulseTypeSelection = NULL,
  rotationSelection = NULL,
  timeRangeTargetTZ = NULL,
  targetTimeZone = "Etc/GMT0",
  classSelection = NULL,
  classProbCutOff = NULL,
  altitudeRange_AGL = NULL,
  echoValidator = FALSE,
  filePath = NULL,
  tagOutputFile = c(NULL, NULL),
  saveCSV = FALSE
)

Arguments

Value

Returns filtered data table - echo, protocol, blindTimes, sunriseSunset, radarSite - and necessary parameters as input for computeMTR().

Author(s)

Baptiste Schmid, Fabian Hertner, Birgen Haest

See Also

Other write file functions: saveMTR(), savePlotToFile()

Description

This function will estimate the density (expressed as #objects / km3) based on the observations in your database. Note that this function only works properly on Birdscan MR1 database versions >= 1.7.0.4 as the variable feature37.speed is required for the density calculation.

Usage

computeDensity(
  dbName,
  echoes,
  classSelection,
  altitudeRange,
  altitudeBinSize,
  timeRange,
  timeBinDuration_sec,
  timeZone,
  sunriseSunset,
  sunOrCivil = "civil",
  crepuscule = "nauticalSolar",
  protocolData,
  visibilityData,
  manualBlindTimes = NULL,
  saveBlindTimes = FALSE,
  blindTimesOutputDir = getwd(),
  blindTimeAsMtrZero = NULL,
  propObsTimeCutoff = 0,
  computePerDayNight = FALSE,
  computePerDayCrepusculeNight = FALSE,
  computeAltitudeDistribution = TRUE
)

Arguments

Value

Density

Author(s)

Birgen Haest, Fabian Hertner, Baptiste Schmid

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeMTR(), convertTimeZone(), createVPTS(), filterSpeedFeature37(), mergeVisibilityAndManualBlindTimes(), reclassToBats(), twilight()

Examples

# Load example data
# ===========================================================================
  dbData         = readRDS(system.file("extdata",
    "CH_Sempach_2024_SEP24_25_DataExtract.rds",
    package = "birdscanR"))
  dbName         = "CH_Sempach_2024_SEP24_25"
  targetTimeZone = "Etc/GMT0"
  timeRangeData  = c("2024-09-24 00:00", "2024-09-25 23:59")

# Set manual blind times to NULL (no manual blind times)
# ===========================================================================
  cManualBlindTimes = NULL

# Compute density
# ===========================================================================
  classSelection.density = c("passerine_type")
  densityData = computeDensity(dbName                       = dbName,
                               echoes                       = dbData$echoData,
                               classSelection               = classSelection.density,
                               altitudeRange                = c(25, 1025),
                               altitudeBinSize              = 50,
                               timeRange                    = timeRangeData,
                               timeBinDuration_sec          = 1800,
                               timeZone                     = targetTimeZone,
                               sunriseSunset                = dbData$sunriseSunset,
                               sunOrCivil                   = "civil",
                               crepuscule                   = "nauticalSolar",
                               protocolData                 = dbData$protocolData,
                               visibilityData               = dbData$visibilityData,
                               manualBlindTimes             = cManualBlindTimes,
                               saveBlindTimes               = FALSE,
                               blindTimesOutputDir          = getwd(),
                               blindTimeAsMtrZero           = NULL,
                               propObsTimeCutoff            = 0,
                               computePerDayNight           = FALSE,
                               computePerDayCrepusculeNight = FALSE,
                               computeAltitudeDistribution  = TRUE)

Description

This function will estimate the Activity / Migration Traffic Rates (MTR, expressed as #objects / km / hour) based on the observations in your database.

Usage

computeMTR(
  dbName,
  echoes,
  classSelection,
  altitudeRange,
  altitudeBinSize,
  timeRange,
  timeBinDuration_sec,
  timeZone,
  sunriseSunset,
  sunOrCivil = "civil",
  crepuscule = "nauticalSolar",
  protocolData,
  visibilityData,
  manualBlindTimes = NULL,
  saveBlindTimes = FALSE,
  blindTimesOutputDir = getwd(),
  blindTimeAsMtrZero = NULL,
  propObsTimeCutoff = 0,
  computePerDayNight = FALSE,
  computePerDayCrepusculeNight = FALSE,
  computeAltitudeDistribution = TRUE
)

Arguments

Value

Migration Traffic Rates

Author(s)

Fabian Hertner, Baptiste Schmid, Birgen Haest

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeDensity(), convertTimeZone(), createVPTS(), filterSpeedFeature37(), mergeVisibilityAndManualBlindTimes(), reclassToBats(), twilight()

Examples

# Load example data
# ===========================================================================
  dbData         = readRDS(system.file("extdata",
    "CH_Sempach_2024_SEP24_25_DataExtract.rds",
    package = "birdscanR"))
  dbName         = "CH_Sempach_2024_SEP24_25"
  targetTimeZone = "Etc/GMT0"
  timeRangeData  = c("2024-09-24 00:00", "2024-09-25 23:59")

# Set manual blind times to NULL (no manual blind times)
# ===========================================================================
  cManualBlindTimes = NULL

# Compute migration traffic rate
# ===========================================================================
  classSelection.mtr = c("passerine_type")
  mtrData = computeMTR(dbName                       = dbName,
                       echoes                       = dbData$echoData,
                       classSelection               = classSelection.mtr,
                       altitudeRange                = c(25, 1025),
                       altitudeBinSize              = 50,
                       timeRange                    = timeRangeData,
                       timeBinDuration_sec          = 1800,
                       timeZone                     = targetTimeZone,
                       sunriseSunset                = dbData$sunriseSunset,
                       sunOrCivil                   = "civil",
                       crepuscule                   = "nauticalSolar",
                       protocolData                 = dbData$protocolData,
                       visibilityData               = dbData$visibilityData,
                       manualBlindTimes             = cManualBlindTimes,
                       saveBlindTimes               = FALSE,
                       blindTimesOutputDir          = getwd(),
                       blindTimeAsMtrZero           = NULL,
                       propObsTimeCutoff            = 0,
                       computePerDayNight           = FALSE,
                       computePerDayCrepusculeNight = FALSE,
                       computeAltitudeDistribution  = TRUE)

Description

Converts timestamps from radar time zone to an user-defined time zone

Usage

convertTimeZone(
  data = NULL,
  colNames = "",
  originTZ = "Etc/GMT0",
  targetTZ = "Etc/GMT0"
)

Arguments

Value

a data frame identical to data, any columns declared in colNames will have their name changed with a suffix (⁠_originTZ⁠ or ⁠_targetTZ⁠) added.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeDensity(), computeMTR(), createVPTS(), filterSpeedFeature37(), mergeVisibilityAndManualBlindTimes(), reclassToBats(), twilight()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Add day/night info to echo data
# ===========================================================================
echoData = convertTimeZone(
  data     = dbData$echoData,
  colNames = c("time_stamp"),
  originTZ = "Etc/GMT0",
  targetTZ = "Etc/GMT-2"
)

Description

Create a list by segmenting the input time range into regular periods for plots.

Usage

createTimeRangeForPlot(
  startDate = NULL,
  endDate = NULL,
  periodLength = 7,
  returnAsList = TRUE
)

Arguments

Value

A list of time periods

Author(s)

Baptiste Schmid, Birgen Haest

See Also

Other plot functions: plotExploration(), plotLongitudinalMTR()

Examples

## Not run: 
# Set server, database, and other input settings
# ===========================================================================
# Example with seven days time window
timeRangeData <- c("2024-01-01", "2024-02-15")
timeRangePlot <- createTimeRangePlot(timeRangeData[1], timeRangeData[2], 7)
print(timeRangePlot)

## End(Not run)

Description

This function creates VPTS CSV output files in line with the ALOFT data standard, described here. Note that this function only works on Birdscan MR1 database versions >= 1.7.0.4 as the variable feature37.speed is required for the density calculation.

Usage

createVPTS(
  dbName,
  outputDir,
  echoes,
  classSelection = c("passerine_type", "wader_type", "swift_type", "large_bird",
    "unid_bird", "bird_flock"),
  altitudeRange = c(50, 1500),
  altitudeBinSize = 50,
  timeRange,
  timeBinDuration_sec = 900,
  timeZone = "Etc/GMT0",
  protocolData,
  visibilityData,
  siteData,
  sunriseSunset,
  manualBlindTimes = NULL,
  saveBlindTimes = FALSE,
  blindTimesOutputDir = getwd(),
  blindTimeAsMtrZero = NULL,
  propObsTimeCutoff = 0.2
)

Arguments

Value

File path to the created VPTS CSV file.

Author(s)

Birgen Haest

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeDensity(), computeMTR(), convertTimeZone(), filterSpeedFeature37(), mergeVisibilityAndManualBlindTimes(), reclassToBats(), twilight()

Examples

# Load example data
# ===========================================================================
  dbData         = readRDS(system.file("extdata",
    "CH_Sempach_2024_SEP24_25_DataExtract.rds",
    package = "birdscanR"))
  dbName         = "CH_Sempach_2024_SEP24_25"
  mainOutputDir  = file.path(".", "results")
  targetTimeZone = "Etc/GMT0"
  timeRangeData  = c("2024-09-24 00:00", "2024-09-25 23:59")

# Set manual blind times to NULL (no manual blind times)
# ===========================================================================
  cManualBlindTimes = NULL

# Create vpts files
# ===========================================================================
  vptsDir = createVPTS(dbName                       = dbName,
                       outputDir                    = mainOutputDir,
                       echoes                       = dbData$echoData,
                       altitudeRange                = c(25, 1025),
                       altitudeBinSize              = 50,
                       timeRange                    = timeRangeData,
                       timeBinDuration_sec          = 1800,
                       timeZone                     = targetTimeZone,
                       protocolData                 = dbData$protocolData,
                       visibilityData               = dbData$visibilityData,
                       siteData                     = dbData$siteData,
                       sunriseSunset                = dbData$sunriseSunset,
                       manualBlindTimes             = cManualBlindTimes,
                       saveBlindTimes               = FALSE,
                       blindTimesOutputDir          = mainOutputDir,
                       blindTimeAsMtrZero           = NULL,
                       propObsTimeCutoff            = 0.2)

Description

Connects to a Birdscan SQL database, be it a Microsoft SQL or postgreSQL database3

Usage

dbConnectBirdscanSQL(
  dbDriverChar = "SQL Server",
  dbServer = NULL,
  dbName = NULL,
  dbUser = NULL,
  dbPwd = NULL,
  dbPort = 5432
)

Arguments

Value

A database connection to your target database

Author(s)

Birgen Haest

See Also

Other read SQL database functions: QUERY(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

## End(Not run)

Description

Load the data from the database or file and save it to file

Usage

extractDbData(
  dbDriverChar = "SQL Server",
  dbServer = NULL,
  dbName = NULL,
  dbUser = NULL,
  dbPwd = NULL,
  dbPort = 5432,
  saveDbToFile = FALSE,
  dbDataDir = NULL,
  radarTimeZone = NULL,
  targetTimeZone = "Etc/GMT0",
  timeInterval = NULL,
  listOfRfFeaturesToExtract = NULL,
  siteLocation = NULL,
  sunOrCivil = "civil",
  crepuscule = "nauticalSolar"
)

Arguments

Value

a list of R objects with data extracted from the Database: 'echoData', 'protocolData', 'siteData', 'visibilityData', 'timeBinData', 'rfFeatures', 'availableClasses', 'availableBatClasses', 'classProbabilitiesAndMtrFactors', 'batProbabilitiesAndMtrFactors'

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server, database, and other input settings
# ===========================================================================
dbDriverChar = "SQL Server" # Set either "SQL Server" or "PostgreSQL"
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
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,
  crepuscule = "nauticalSolar"
)

## End(Not run)

Description

With filterData() both the echo and protocol data can be filtered based on 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
)

Arguments

Value

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

Author(s)

Birgen Haest

See Also

Other filter functions: filterEchoData(), filterProtocolData()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Set input settings for filtering of the data
# ===========================================================================
pulseLengthSelection = "S"
rotationSelection    = 1
timeRangeData        = c("2024-09-24 00:00", "2024-09-25 23:59")
targetTimeZone       = "Etc/GMT0"
classSelection = c(
  "passerine_type", "wader_type", "swift_type",
  "large_bird", "unid_bird", "bird_flock"
)
classProbCutoff  = NULL
altitudeRange    = c(50, 1000)
cManualBlindTimes = NULL
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
)

Description

With filterEchoData() the echo data can be filtered by several parameters. The function returns the filtered echo data.

Usage

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

Arguments

Value

returns the filtered echo data in the same format as provided in the parameter echoData.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other filter functions: filterData(), filterProtocolData()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Set input settings for filtering of the data
# ===========================================================================
timeRangeData  = c("2024-09-24 00:00", "2024-09-25 23:59")
targetTimeZone = "Etc/GMT0"
classSelection = c(
  "passerine_type", "wader_type", "swift_type",
  "large_bird", "unid_bird", "bird_flock"
)
classProbCutoff  = NULL
altitudeRange    = c(50, 1000)
cManualBlindTimes = NULL
useEchoValidator = FALSE

# Filter the echo data
# ===========================================================================
filteredEchoData = filterEchoData(
  echoData          = dbData$echoData,
  timeRangeTargetTZ = timeRangeData,
  targetTimeZone    = targetTimeZone,
  protocolData      = dbData$protocolData,
  classSelection    = classSelection,
  classProbCutOff   = classProbCutoff,
  altitudeRange_AGL = altitudeRange,
  manualBlindTimes  = cManualBlindTimes,
  echoValidator     = useEchoValidator
)

Description

With filterProtocolData() the protocol data can be filtered by the operation mode (pulse-type and antenna rotation). The function returns the filtered subset of the protocol data which can later be used to filter the echoes based on the operation mode/protocol

Usage

filterProtocolData(
  protocolData = NULL,
  pulseTypeSelection = NULL,
  rotationSelection = NULL
)

Arguments

Value

returns the filtered protocol data in the same format as provided in the parameter protocolData.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other filter functions: filterData(), filterEchoData()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Set input settings for filtering of the data
# ===========================================================================
pulseLengthSelection = "S"
rotationSelection = 1

# Filter the protocol data
# ===========================================================================
filteredProtocolData = filterProtocolData(
  protocolData      = dbData$protocolData,
  pulseTypeSelection = pulseLengthSelection,
  rotationSelection  = rotationSelection
)

Description

Filter outliers in Speed feature (collection.feature37)

Usage

filterSpeedFeature37(echoData = NULL, minEchoDuration = 5)

Arguments

Value

echoData with the filtered speed feature 37

Author(s)

Fabian Hertner, [email protected]; Birgen Haest, [email protected]

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeDensity(), computeMTR(), convertTimeZone(), createVPTS(), mergeVisibilityAndManualBlindTimes(), reclassToBats(), twilight()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Filter speed feature 37
# ===========================================================================
minEchoDuration = 5
dbData$echoData = filterSpeedFeature37(
  echoData        = dbData$echoData,
  minEchoDuration = minEchoDuration
)

Description

Gets the 'rfClasses' table from a 'Birdscan MR1' 'SQL' database

Usage

getBatClassification(dbConnection, dbDriverChar)

Arguments

Value

A list containing three variables: (1) batClassificationTable: The 'batClassification' database table; (2) classProbabilitiesAndMtrFactors: A dataframe containing the classification probabilities for all classes for each object; and (3) availableClasses: the classes used for the classification of the objects.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

batClassification = getBatClassification(dbConnection)

## End(Not run)

Description

Load collection from 'Birdscan MR1' 'SQL' database.

Usage

getCollectionTable(dbConnection, dbDriverChar, timeInterval = NULL)

Arguments

Value

A dataframe with the collection table

Author(s)

Fabian Hertner, Birgen Haest, Bart Kranstauber

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

collectionTable = getCollectionTable(dbConnection)

## End(Not run)

Description

Load echo rffeature map from 'Birdscan MR1' 'SQL' database.

Usage

getEchoFeatures(
  dbConnection,
  dbDriverChar,
  listOfRfFeaturesToExtract,
  echoIDRange = NULL
)

Arguments

Value

A list of the features extracted

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

# Set list of Rf features you also want to extract
# Vector with RF features to extract. Feature IDs can be found in the
# 'rfFeatures' table in the sql database.
# Example: Get wing beat frequency and credibility: c(167, 168)
# Set to NULL to not extract any.
# Set to "all" to extract all features.
# ===========================================================================
listOfRfFeaturesToExtract = c(167, 168)

echoFeatures = getEchoFeatures(
  dbConnection,
  listOfRfFeaturesToExtract
)

## End(Not run)

Description

Gets the echoValidationTable from an already connected database.

Usage

getEchoValidationTable(dbConnection, dbDriverChar)

Arguments

Value

A dataframe called echovalidationTable

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

echovalidationTable = getEchoValidationTable(dbConnection)

## End(Not run)

Description

Load visibility table from an already connected 'Birdscan MR1' 'SQL' database.

Usage

getManualVisibilityTable(dbConnection, dbDriverChar)

Arguments

Value

A data.frame with the manual visibility table.

Author(s)

Baptiste Schmid, Birgen Haest

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

manualVisibilityTable = getManualVisibilityTable(dbConnection)

## End(Not run)

Description

Load protocol table from an already connected 'Birdscan MR1' 'SQL' database.

Usage

getProtocolTable(dbConnection, dbDriverChar)

Arguments

Value

A dataframe with the protocol table

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

protocolTable = getProtocolTable(dbConnection)

## End(Not run)

Description

Get the Radar table from an already connected DB and rename the columns appropriately.

Usage

getRadarTable(dbConnection, dbDriverChar)

Arguments

Value

the radar table as a data frame

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

radarTable = getRadarTable(dbConnection)

## End(Not run)

Description

Gets the 'rfClasses' table from a 'Birdscan MR1' 'SQL' database.

Usage

getRfClassification(dbConnection, dbDriverChar)

Arguments

Value

A list containing three variables: (1) rfclassificationTable: The 'rfClassification' database table; (2) classProbabilitiesAndMtrFactors: A dataframe containing the classification probabilities for all classes for each object; and (3) availableClasses: the classes used for the classification of the objects.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

rfClassification = getRfClassification(dbConnection)

## End(Not run)

Description

Load site table from an already connected 'Birdscan MR1' 'SQL' database.

Usage

getSiteTable(dbConnection, dbDriverChar)

Arguments

Value

A data.frame with the site table

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

siteTable <- getSiteTable(dbConnection)

## End(Not run)

Description

Load time bins table from an already connected 'Birdscan MR1' 'SQL' database.

Usage

getTimeBinsTable(dbConnection, dbDriverChar)

Arguments

Value

A dataframe with the time bins table

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

timeBinsTable = getTimeBinsTable(dbConnection)

## End(Not run)

Description

Load visibility table from an already connected 'Birdscan MR1' 'SQL' database.

Usage

getVisibilityTable(dbConnection, dbDriverChar)

Arguments

Value

A data.frame with the visibility table.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: QUERY(), dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable()

Examples

## Not run: 
# Set server and database settings
# ==========================================================================
# Using and Microsoft SQL database
# ========================================================================
dbServer = "MACHINE\\SERVERNAME" # Set the name of your SQL server
dbName = "db_Name" # Set the name of your database
dbDriverChar = "SQL Server" # Set to "SQL Server"

# Using a PostgreSQL
# ========================================================================
dbServer = "cloud.birdradar.com" # Set the name or IP of your postgreSQL
dbName = "db_Name" # Set the name of your database
dbDriverChar = "PostgreSQL" # Set to "PostgreSQL"

# Open the connection with the database
# ==========================================================================
dbConnection = dbConnectBirdscanSQL(
  dbDriverChar = dbDriverChar,
  dbServer     = dbServer,
  dbName       = dbName,
)

visibilityTable = getVisibilityTable(dbConnection)

## End(Not run)

Description

Load manual blind times from csv file. For the MTR computation the times when the radar was blind have to be known. The radar itself can be blind in case of a protocol change (block time at the beginning of each protocol, usually 60s) or due to rain/snow or clutter (nearby objects, leaves or similar on radome, etc.). These times are stored in the visibility table or in the time_bins table in relation to the time bins duration (5min). To be flexible and not fixed to the 5 min time bins created by the radar, the visibility table is used in this script. In addition to the radar blind times, manual blind times can be defined. Manual blind times have to be defined in a csv file and are loaded with loadManualBlindTimes(). An example dataset is available by running: data(manualBlindTimes) write.csv(manualBlindTimes, file = 'the output file destination', row.names = F) The file path is defined as a global variable ‘manualBlindTimesFile’. A custom file and filepath can be used instead. The manual blind times have to be entered with 3 columns: start time 'yyyy-mm-dd hh:mm:ss', stop time 'yyyy-MM-dd hh:mm:ss', type.

Example: 2021-01-16 04:15:00,2021-01-16 05:42:00,rain 2021-01-17 16:33:00,2021-01-17 18:04:00,clutter Manual blind time types can be chosen freely. When computing observation times, it can be decided if some of the defined manual blind time types should be treated as observed time with MTR zero or as blind time (e.g. rain). If no file is present or the file is empty, no manual blind times will be computed.

Usage

loadManualBlindTimes(filePath, blindTimesTZ, targetTZ)

Arguments

Value

A dataframe with the manual blind times

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other sample data: CH_Sempach_2024_SEP24_25_DataExtract, classAbbreviations, manualBlindTimes

Examples

# Load manual blind time example data from birdscanR package
# ===========================================================================
data(manualBlindTimes)

# Save example manual blind times to a temporary file
# ===========================================================================
tmpFile = tempfile(fileext = ".csv")
write.table(manualBlindTimes, file = tmpFile, sep = ",",
            row.names = FALSE, col.names = FALSE)

# Read the manual blind times from file
# ===========================================================================
manualBlindTimes.new = loadManualBlindTimes(
  filePath     = tmpFile,
  blindTimesTZ = "Etc/GMT0",
  targetTZ     = "Etc/GMT0"
)

Description

To create your own manual blind times file, just copy this file, and adjust.

Usage

data(manualBlindTimes)

Format

An object of class data.frame.

See Also

Other sample data: CH_Sempach_2024_SEP24_25_DataExtract, classAbbreviations, loadManualBlindTimes()

Examples

data(manualBlindTimes)

Description

Function to merge manual blind times with blind times from visibility table. For further processing the radar (visibility) and manual blind times have to be merged with mergeVisibilityAndManualBlindTimes(). This function will add a blind time type to the radar/visibility blind times. Blind times during the block time (usually 60s) at the beginning of each protocol are given the type 'protocolChange', the rest of the radar blind times are given the type “visibility”. After that the visibility and manual blind times will be merged. In case manual blind times and radar blind times are overlapping, radar blind times with type “visibility” will be overwritten, but not radar blind times with type “protocolChange”.

Usage

mergeVisibilityAndManualBlindTimes(
  visibilityData,
  manualBlindTimes = NULL,
  protocolData
)

Arguments

Value

dataframe with overall blind times

Author(s)

Fabian Hertner, Birgen Haest, Baptiste Schmid

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeDensity(), computeMTR(), convertTimeZone(), createVPTS(), filterSpeedFeature37(), reclassToBats(), twilight()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Get manual blind times
# ===========================================================================
data(manualBlindTimes)
tmpFile = tempfile(fileext = ".csv")
write.table(manualBlindTimes, file = tmpFile, sep = ",",
            row.names = FALSE, col.names = FALSE)
cManualBlindTimes = loadManualBlindTimes(
  filePath     = tmpFile,
  blindTimesTZ = "Etc/GMT0",
  targetTZ     = "Etc/GMT0"
)

# Merge manual and automatic blind times
# ===========================================================================
blindTimes = mergeVisibilityAndManualBlindTimes(
  visibilityData   = dbData$visibilityData,
  manualBlindTimes = cManualBlindTimes,
  protocolData     = dbData$protocolData
)

Description

This function creates a time series plot showing all of the observed echoes at their respective altitudes. These plots are helpful to roughly visually explore your data (and for example spot oddities).

Usage

plotExploration(
  echoData = NULL,
  timeRange = NULL,
  targetTimeZone = "Etc/GMT0",
  manualBlindTimes = NULL,
  visibilityData = NULL,
  protocolData = NULL,
  sunriseSunset = NULL,
  maxAltitude = NULL,
  filePath = NULL
)

Arguments

Value

png files stored in the directory specified in 'filePath'

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other plot functions: createTimeRangeForPlot(), plotLongitudinalMTR()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Set manual blind times to NULL (no manual blind times)
# ===========================================================================
cManualBlindTimes = NULL

# Make Plot
# ===========================================================================
timeRangePlot = list(
  c("2024-09-24 00:00", "2024-09-24 23:59"),
  c("2024-09-25 00:00", "2024-09-25 23:59")
)
plotExploration(
  echoData         = dbData$echoData,
  timeRange        = timeRangePlot,
  targetTimeZone   = "Etc/GMT0",
  manualBlindTimes = cManualBlindTimes,
  visibilityData   = dbData$visibilityData,
  protocolData     = dbData$protocolData,
  sunriseSunset    = dbData$sunriseSunset,
  maxAltitude      = -1,
  filePath         = "./"
)

Description

Plots a time series of MTR values as a bar plot. For each bar the spread (first and third Quartile) is shown as error bars as well as the numbers of echoes. Periods with no observation are indicated with grey, negative bars.

Usage

plotLongitudinalMTR(
  mtr,
  maxMTR,
  timeRange = NULL,
  targetTimeZone = "Etc/GMT0",
  plotClass = "allClasses",
  propObsTimeCutoff = 0.2,
  plotSpread = TRUE,
  filePath = NULL
)

Arguments

Value

png files stored in the directory specified with 'filePath'

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other plot functions: createTimeRangeForPlot(), plotExploration()

Examples

# Load example data
# ===========================================================================
dbData         = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))
dbName         = "CH_Sempach_2024_SEP24_25"
targetTimeZone = "Etc/GMT0"
timeRangeData  = c("2024-09-24 00:00", "2024-09-25 23:59")

# Set manual blind times to NULL (no manual blind times)
# ===========================================================================
cManualBlindTimes = NULL

# Compute migration traffic rate
# ===========================================================================
classSelection.mtr = c("passerine_type")
mtrData = computeMTR(
  dbName                       = dbName,
  echoes                       = dbData$echoData,
  classSelection               = classSelection.mtr,
  altitudeRange                = c(25, 1025),
  altitudeBinSize              = 50,
  timeRange                    = timeRangeData,
  timeBinDuration_sec          = 1800,
  timeZone                     = targetTimeZone,
  sunriseSunset                = dbData$sunriseSunset,
  sunOrCivil                   = "civil",
  protocolData                 = dbData$protocolData,
  visibilityData               = dbData$visibilityData,
  manualBlindTimes             = cManualBlindTimes,
  saveBlindTimes               = FALSE,
  blindTimesOutputDir          = getwd(),
  blindTimeAsMtrZero           = NULL,
  propObsTimeCutoff            = 0,
  computePerDayNight           = FALSE,
  computeAltitudeDistribution  = TRUE
)

# Make Plot
# ===========================================================================
timeRangePlot = list(
  c("2024-09-24 00:00", "2024-09-24 23:59"),
  c("2024-09-25 00:00", "2024-09-25 23:59")
)
plotLongitudinalMTR(
  mtr               = mtrData,
  maxMTR            = -1,
  timeRange         = timeRangePlot,
  targetTimeZone    = "Etc/GMT0",
  plotClass         = "allClasses",
  propObsTimeCutoff = 0.2,
  plotSpread        = TRUE,
  filePath          = "./"
)

Description

Run an 'SQL' query on an already connected database.

Usage

QUERY(dbConnection, dbDriverChar, query, as.is = FALSE)

Arguments

Value

the result of the query

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other read SQL database functions: dbConnectBirdscanSQL(), extractDbData(), getBatClassification(), getCollectionTable(), getEchoFeatures(), getEchoValidationTable(), getProtocolTable(), getRadarTable(), getRfClassification(), getSiteTable(), getTimeBinsTable(), getVisibilityTable()

Examples

## Not run: 
# Set server and database settings
# ===========================================================================
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"

# Open the connection with the database
# ===========================================================================
dsn = paste0(
  "driver=", dbDriverChar, ";server=", dbServer,
  ";database=", dbName,
  ";uid=", rstudioapi::askForPassword("Database user"),
  ";pwd=", rstudioapi::askForPassword("Database password")
)
dbConnection = RODBC::odbcDriverConnect(dsn)

QUERY(
  dbConnection = dbConnection,
  query = "Select * From collection order by row asc"
)

## End(Not run)

Description

Reclassifies echoes based on bat classification.

Usage

reclassToBats(
  echoData = NULL,
  batProbabilitiesAndMtrFactors = NULL,
  reclassToBatCutoff = -1
)

Arguments

Value

echoData dataframe

Author(s)

Fabian Hertner

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeDensity(), computeMTR(), convertTimeZone(), createVPTS(), filterSpeedFeature37(), mergeVisibilityAndManualBlindTimes(), twilight()

Examples

# Load example data
# ===========================================================================
dbData = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))

# Reclass To Bats
# ===========================================================================
dbData$echoData = reclassToBats(
  echoData                     = dbData$echoData,
  batProbabilitiesAndMtrFactors = dbData$batProbabilitiesAndMtrFactors,
  reclassToBatCutoff           = 0.5
)

Description

Saves MTR data to a .rds file in the directory filepath. If the directory is not existing it will be created if possible.

Usage

saveMTR(
  mtr,
  filepath,
  fileName = NULL,
  fileNamePrefix = NULL,
  dbName = NULL,
  rotSelection = NULL,
  pulseTypeSelection = NULL,
  classAbbreviations = NULL
)

Arguments

Value

No return value, used to save MTR to file.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other write file functions: compileData(), savePlotToFile()

Examples

# Load example data
# ===========================================================================
dbData         = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))
dbName         = "CH_Sempach_2024_SEP24_25"
mainOutputDir  = file.path(".", "results")
targetTimeZone = "Etc/GMT0"
timeRangeData  = c("2024-09-24 00:00", "2024-09-25 23:59")

# Set manual blind times to NULL (no manual blind times)
# ===========================================================================
cManualBlindTimes = NULL

# Compute migration traffic rate
# ===========================================================================
classSelection.mtr = c("passerine_type")
mtrData = computeMTR(
  dbName                      = dbName,
  echoes                      = dbData$echoData,
  classSelection              = classSelection.mtr,
  altitudeRange               = c(25, 1025),
  altitudeBinSize             = 50,
  timeRange                   = timeRangeData,
  timeBinDuration_sec         = 1800,
  timeZone                    = targetTimeZone,
  sunriseSunset               = dbData$sunriseSunset,
  sunOrCivil                  = "civil",
  protocolData                = dbData$protocolData,
  visibilityData              = dbData$visibilityData,
  manualBlindTimes            = cManualBlindTimes,
  saveBlindTimes              = FALSE,
  blindTimesOutputDir         = mainOutputDir,
  blindTimeAsMtrZero          = NULL,
  propObsTimeCutoff           = 0,
  computePerDayNight          = FALSE,
  computeAltitudeDistribution = TRUE
)

# Save the MTR data to file
# ===========================================================================
saveMTR(
  mtr      = mtrData,
  filepath = mainOutputDir,
  dbName   = dbName
)

Description

Saves created plots as .png.

Usage

savePlotToFile(
  plot = NULL,
  filePath = NULL,
  plotType = NULL,
  plotWidth_mm = NULL,
  plotHeight_mm = NULL,
  timeRange = NULL,
  classSelection = NULL,
  altitudeRange = NULL,
  classAbbreviations = NULL
)

Arguments

Value

No return value, used to save plots to file.

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other write file functions: compileData(), saveMTR()

Examples

# Load example data
# ===========================================================================
dbData         = readRDS(system.file("extdata",
  "CH_Sempach_2024_SEP24_25_DataExtract.rds",
  package = "birdscanR"))
mainOutputDir  = file.path(".", "results")

# Set manual blind times to NULL (no manual blind times)
# ===========================================================================
cManualBlindTimes = NULL

# Make Plot
# ===========================================================================
timeRangePlot = list(
  c("2024-09-24 00:00", "2024-09-24 23:59"),
  c("2024-09-25 00:00", "2024-09-25 23:59")
)
cPlot = plotExploration(
  echoData         = dbData$echoData,
  timeRange        = timeRangePlot,
  targetTimeZone   = "Etc/GMT0",
  manualBlindTimes = cManualBlindTimes,
  visibilityData   = dbData$visibilityData,
  protocolData     = dbData$protocolData,
  sunriseSunset    = dbData$sunriseSunset,
  maxAltitude      = -1,
  filePath         = mainOutputDir
)

# Save plot
# ===========================================================================
savePlotToFile(
  plot          = cPlot,
  filePath      = mainOutputDir,
  plotType      = "S",
  plotWidth_mm  = 400,
  plotHeight_mm = 200
)

Description

Get the time of nautical (sun at 12 degrees below horizon), civil (sun at 6 degrees below horizon) and solar (sun at 0 degrees below horizon) dawn and dusk for each day over a given time range.

Usage

twilight(timeRange, latLon, crs_datum = "WGS84", timeZone)

Arguments

Value

A data frame with the results

Author(s)

Fabian Hertner, Birgen Haest

See Also

Other manipulation functions: addDayNightInfoPerEcho(), computeDensity(), computeMTR(), convertTimeZone(), createVPTS(), filterSpeedFeature37(), mergeVisibilityAndManualBlindTimes(), reclassToBats()

Examples

sunriseSunset = twilight(
  timeRange = c("2024-09-24 00:00", "2024-09-25 23:59"),
  latLon    = c(47.12764, 8.192569),
  timeZone  = "Etc/GMT0"
)