Package 'RWildbook' reference manual

Title:	Interface for the 'Wildbook' Wildlife Data Management Framework
Description:	Provides an interface with the 'Wildbook' mark-recapture ecological database framework. It helps users to pull data from the 'Wildbook' framework and format data for further analysis with mark-recapture applications like 'Program MARK' (which can be accessed via the 'RMark' package in 'R'). Further information on the 'Wildbook' framework is available at: <http://www.wildbook.org/doku.php>.
Authors:	Simon Bonner [aut, cre], Xinxin Huang [aut]
Maintainer:	Simon Bonner <[email protected]>
License:	GPL (>= 2)
Version:	0.9.3
Built:	2025-02-14 04:57:06 UTC
Source:	https://github.com/cran/RWildbook

Transform a vector of date to a vector of millisecond.

Description

This function is to transform a period of time in date to millisecond according to the origin date and the format of date.

Usage

dateTOmillisecond(date, origin = "1970-01-01", format = "%Y-%m-%d",
  interval = TRUE)
dateTOmillisecond(date, origin = "1970-01-01", format = "%Y-%m-%d",
  interval = TRUE)

Arguments

`date`	A character vector represent a period of time from date[1] to date[2].
`origin`	A point of time which set to be zero in millisecond.
`format`	A format for date and origin arguments.
`interval`	A logical argument which equals to TRUE by default when the function transfer an period of dates to millisecond. When interval=FALSE, the function returns the last minute of every elements of date to millisecons.

Details

A vector of size two represent a period of time. The start date of the period will be transform to the first millisecond of the date and the end of the period to the last millisecond.

Generate the JDOQL part of a filter.

Description

This function is to generate the string in the JDOQL query for some given value of a filter.

Usage

filterstring(filtername, filtervalues, logic = "||", bridge = "==")
filterstring(filtername, filtervalues, logic = "||", bridge = "==")

Arguments

`filtername`	A character which is for the responding variable name in Wildbook framework.
`filtervalues`	A vector of the value for the filter.
`logic`	A parameter which can be "&&" for the logical AND or "\|\|" for the logical OR.
`bridge`	An operator to connect the name and the default value is "==".

Identify operating system as Mac, *nix, or Windows

Description

Copied from Hadley Wickham's rappdir package at his suggestion. The rappdir package currently does not export this function

Usage

get_os()
get_os()

Value

Operating system name (character string).

Format Wildbook data for mark-recaputure analysis

Description

Format data from searchWB function in RWildbook package for mark-recapture analysis with marked and RMark packages.

Usage

markedData(data, varname_of_capturetime = "dateInMilliseconds",
  varlist = c("individualID"), start.dates, end.dates = NULL,
  date_format = "%Y-%m-%d", origin = "1970-01-01", removeZeros = TRUE)
markedData(data, varname_of_capturetime = "dateInMilliseconds",
  varlist = c("individualID"), start.dates, end.dates = NULL,
  date_format = "%Y-%m-%d", origin = "1970-01-01", removeZeros = TRUE)

Arguments

`data`	The raw data set from `searchWB` function in `RWildbook` package.
`varname_of_capturetime`	A character object which is the variable name for capture/encounter sighted time.
`varlist`	A character vector of the names of variables for mark-recapture analysis.
`start.dates`	A character vector of dates which are the start dates of the capture occasions. The elements should be in the form of date_format.
`end.dates`	A character vector of dates which are the end dates of the capture occasions. The elements should be in the form of date_format.
`date_format`	The format for all the arguments of date value.
`origin`	A point of time which set to be zero in millisecond.
`removeZeros`	If TRUE (default) then individuals with no captures are removed from the data.

Details

The markedData function format the wildbook data set that users search with the searchWB fucntion for the mark-recapture analysis with mark and RMark package. In marked package, users can process a certain form of data set with process.data function in marked package. The markedData function reutrns data set which can be the input data set of process.data.

Defalut NULL value for end.dates argument

The default value for end.date argument are NULL which means the capture occasion intervals are divided by the elements of start.date argument. In this case, the end date of the last capture occasion is the value of Sys.Date().

The class of output The class of the ouput of markedData is "data.table" and "data.frame". With installing the data.table package, the ouput is a data.table, otherwise it is a data.frame. That means users can process the data with data.table package. Also users can directly process the output with process.data function in marked package.

Examples


## Not run: 
## You will need to supply your own login information for whaleshark.org to
## run these examples.

## Load packages
library(marked)

## Extract data for individual A-001 through A-099
data1 <- searchWB(username="username",
                  password="password",
                  baseURL ="whaleshark.org",
                  object="Encounter",
                  individualID=paste0("A-0",rep(0:9,rep(10,10)),rep(0:9,10))[-1])

## Define start and end dates of capture occasions
start.dates1 <- paste0(1998:2016,"-01-01") #Define the start.date value
end.dates1 <- paste0(1998:2016,"-04-01") #Define the end.date value

## Format data for use in marked
markedData1.1 <- markedData(data = data1,
                             varname_of_capturetime = "dateInMilliseconds",
                             varlist = c("individualID"),
                             start.dates = start.dates1,
                             end.dates = NULL,
                             date_format = "%Y-%m-%d",
                             origin = "1970-01-01",
                             removeZeros = TRUE)


## Fit simple CJS model in marked
markedData1.proc=process.data(markedData1.1,model="CJS",begin.time=1)
markedData1.ddl=make.design.data(markedData1.proc)
markedData1.cjs=crm(markedData1.proc,
                    markedData1.ddl,
                    model.parameters=list(Phi=list(formula=~time),p=list(formula=~time)))

## Format data including location as a covariate
markedData1.2 <- markedData(data = data1,
                           varname_of_capturetime = "dateInMilliseconds",
                           varlist = c("individualID","locationID"),
                           start.dates = start.dates1,
                           end.dates = end.dates1,
                           date_format = "%Y-%m-%d",
                           origin = "1970-01-01")

## End(Not run)                           

## Not run: 
## You will need to supply your own login information for whaleshark.org to
## run these examples.

## Load packages
library(marked)

## Extract data for individual A-001 through A-099
data1 <- searchWB(username="username",
                  password="password",
                  baseURL ="whaleshark.org",
                  object="Encounter",
                  individualID=paste0("A-0",rep(0:9,rep(10,10)),rep(0:9,10))[-1])

## Define start and end dates of capture occasions
start.dates1 <- paste0(1998:2016,"-01-01") #Define the start.date value
end.dates1 <- paste0(1998:2016,"-04-01") #Define the end.date value

## Format data for use in marked
markedData1.1 <- markedData(data = data1,
                             varname_of_capturetime = "dateInMilliseconds",
                             varlist = c("individualID"),
                             start.dates = start.dates1,
                             end.dates = NULL,
                             date_format = "%Y-%m-%d",
                             origin = "1970-01-01",
                             removeZeros = TRUE)


## Fit simple CJS model in marked
markedData1.proc=process.data(markedData1.1,model="CJS",begin.time=1)
markedData1.ddl=make.design.data(markedData1.proc)
markedData1.cjs=crm(markedData1.proc,
                    markedData1.ddl,
                    model.parameters=list(Phi=list(formula=~time),p=list(formula=~time)))

## Format data including location as a covariate
markedData1.2 <- markedData(data = data1,
                           varname_of_capturetime = "dateInMilliseconds",
                           varlist = c("individualID","locationID"),
                           start.dates = start.dates1,
                           end.dates = end.dates1,
                           date_format = "%Y-%m-%d",
                           origin = "1970-01-01")

## End(Not run)

RWildbook

Description

The primary objective of this package is to provide an R interface with the Wildbook mark-recapture ecological database framework. It helps users to pull data from the Wildbook framework and format data for further analysis with mark-recapture applications like Program MARK(which can be accessed via the RMark package in R).

Pull data from the Wildbook framework.

Description

This function allows users to pull data from the Wildbook framework into R.

Usage

searchWB(searchURL = NULL, username = NULL, password = NULL, baseURL,
  jdoql = NULL, protocol = "https", object = "encounter",
  location = NULL, locationID = NULL, sighting_date = c("1964-01-01",
  "2016-12-31"), encounter_submission_date = c("2003-01-01", "2016-12-31"),
  date_format = "%Y-%m-%d", sex = c("male", "female", "unknown"),
  status = c("alive", "dead"), measurement = NULL, individualID = NULL,
  encounterID = NULL, encounter_type = NULL, Date_of_birth = NULL,
  Date_of_death = NULL, jsonfile = NULL, showJDOQL = FALSE,
  showURL = TRUE)
searchWB(searchURL = NULL, username = NULL, password = NULL, baseURL,
  jdoql = NULL, protocol = "https", object = "encounter",
  location = NULL, locationID = NULL, sighting_date = c("1964-01-01",
  "2016-12-31"), encounter_submission_date = c("2003-01-01", "2016-12-31"),
  date_format = "%Y-%m-%d", sex = c("male", "female", "unknown"),
  status = c("alive", "dead"), measurement = NULL, individualID = NULL,
  encounterID = NULL, encounter_type = NULL, Date_of_birth = NULL,
  Date_of_death = NULL, jsonfile = NULL, showJDOQL = FALSE,
  showURL = TRUE)

Arguments

`searchURL`	A character object of the URL for data searching in the Wildbook framework.
`username`	A character object of the username in the Wildbook framework.
`password`	A character object of the password in the Wildbook framework.
`baseURL`	A character object of the base URL represent the Wildbook data base.
`jdoql`	A character object of the JDOQL string for data searching.
`protocol`	Defines communication protocol. either "http" or "https" (default).
`object`	A character object for defining the the search type. The value can be either "encounter" for the encounter search or "individual" for the individual search. The default value is "encounter" for encounter search.
`location`	A vector of character strings for searching encounters in locations containing the character strings.
`locationID`	A character vector for searching encounters in locations with specified locationID. Note that the location ID is case sensitive.
`sighting_date`	A character vector for filtering encounters which are sighted during a period of time. More information of the date argument can be found in the Detail section.
`encounter_submission_date`	A character vector for filtering encounters which are submitted during a period of time.
`date_format`	The format for all the arguments of date value.
`sex`	A character vector of maximum size of three representing the values for the sex filter. The value can be any combination of "male", "female" and "unknown". The default value is "sex = c("male", "female", "unknown")".
`status`	A character vector of maximum size of two representing the values for the encounter status. The value can be any combination of "alive" and "dead".
`measurement`	A numeric object sets the minimum individual measurement when searching in the Wildbook framework.
`individualID`	A character vector of individual ID for searching data of specified individual IDs. Note that the individual ID is case sensitive.
`encounterID`	A character vector for searching data of specific encounter ID. Note that the encounter ID is case sensitive.
`encounter_type`	A character vector of maximum size of three for searching data with specific encounter type. It can be any combination of "unapproved", "approved" and "unidentifiable".
`Date_of_birth`	A character vector for searching data of individual which is born during a period of time.
`Date_of_death`	A character vector for searching data of individual which died during a period of time.
`jsonfile`	character. Name of file in which JSOn formatted data from Wildbook will be stored. If NULL (default) then data is stored in a temporary file generated by R.
`showJDOQL`	logical. If FALSE(default) the function will not return the search JDOQL, otherwise the function returns the search JDOQL.
`showURL`	logical. If TRUE(default) the function returns the search URL, otherwise the function will not return the search URL.

Details

The searchWB function provides the main interface to the Wilbook framework and can be used in one of three ways. First, users may supply filters based on the variables within the database. These filters are combined in a single JDOQL statement which is then combined with the base URL, username, and password to create the URL search string for data extraction. Second, users may supply the JDOQL string, username and password, and base URL as separate arguments. Finally, users may supply the search URL directly.

We envisage that most users will supply filters to create the search URL. The other options allow users to easily repeat or modify previous searches and enable advanced users familiar with the JDOQL API and internals of the Wildbook framework to conduct more complex searches. More examples of extracting data from the Wildbook framework with thesearchWB function can be found in the rwildbook-demo-1 of the RWildbook package.

Filtering Locations

Locations may be filtered with either location names or location ids. Multiple location names can be given to the location argument. Multiple location ids can be given to the locationID argument. In this case the search will return all objects (encounters or individuals) matching at least one of the locations.

Filtering Dates

The sighting_date filter may be specified as a character vector of either one or two elements representing dates. If one date is provided then results will be filtered from 00:00:00 to 24:00:00 on that day. If two dates are provided then results will be filtered from 00:00:00 on the first date to 24:00:00 on the second date. By default, dates must be entered using the "YYYY-MM-DD" format. Other formats may be used by specifying the value of date_format. More details about the date format can be found in the help page of as.Date The same rule can apply to the encounter_submission_date, Date_of_birth and Date_of_death filters.

Defalut NULL value for filter arguments

The default value for some filter arguments are NULL. NULL value for a filter argument returns data not filtering that argument.

Examples

## Not run: 
## The following examples conduct the same search.
## You will need to supply your own login information for whaleshark.org to
## run these examples.

## Search using filter arguments
data1 <- searchWB(username="username",
                  password="password",
                  baseURL ="whaleshark.org",
                  object="Encounter",
                  individualID=c("A-001"))

## Search using existing JDOQL string
jdoql <- "SELECT FROM org.ecocean.Encounter WHERE individualID == 'A-001'"

data2 <- searchWB(username="username",
                  password="password",
                  baseURL ="whaleshark.org",
                  jdoql=jdoql)

## Search using existing URL
WBurl <- paste0("http://username:[email protected]/rest/jdoql?",jdoql)

data3 <- searchWB(searchURL = WBurl)

## End(Not run)

## Not run: 
## The following examples conduct the same search.
## You will need to supply your own login information for whaleshark.org to
## run these examples.

## Search using filter arguments
data1 <- searchWB(username="username",
                  password="password",
                  baseURL ="whaleshark.org",
                  object="Encounter",
                  individualID=c("A-001"))

## Search using existing JDOQL string
jdoql <- "SELECT FROM org.ecocean.Encounter WHERE individualID == 'A-001'"

data2 <- searchWB(username="username",
                  password="password",
                  baseURL ="whaleshark.org",
                  jdoql=jdoql)

## Search using existing URL
WBurl <- paste0("http://username:[email protected]/rest/jdoql?",jdoql)

data3 <- searchWB(searchURL = WBurl)

## End(Not run)

Generate the JDOQL part for the sex filter.

Description

This function is to generate the sex related portion in the JDOQL query.

Usage

sexstring(sex)
sexstring(sex)

Arguments

sex

The value for the sex filter.

Data for the first vignette.

Description

Sample data for the first vignette. Originally pulled from http://whaleshark.org, the data has been modified to protect the innocent.

Usage

vignette_1_data
vignette_1_data

Format

An object of class data.frame with 69 rows and 65 columns.

Source

http://whaleshark.org

Data for the second vignette.

Description

Sample data for the first vignette. Originally pulled from http://whaleshark.org, the data has been modified to protect the innocent.

Usage

vignette_2_data
vignette_2_data

Format

An object of class data.frame with 1016 rows and 65 columns.

Source

http://whaleshark.org

Generate the JDOQL query for the search in the Wildbook framework.

Description

This function generate the JDOQL query string according to the filters specified by users. The JDOQL query is an essential part of the search URL.

Usage

WBjdoql(object = "encounter", location = NULL, locationID = NULL,
  sighting_date = c("1964-01-01", "2016-12-31"),
  encounter_submission_dates = c("2003-01-01", "2016-12-31"),
  date_format = "%Y-%m-%d", sex = c("male", "female", "unknown"),
  status = c("alive", "dead"), measurement = NULL, individualID = NULL,
  encounterID = NULL, encounter_type = NULL, Date_of_birth = NULL,
  Date_of_death = NULL)
WBjdoql(object = "encounter", location = NULL, locationID = NULL,
  sighting_date = c("1964-01-01", "2016-12-31"),
  encounter_submission_dates = c("2003-01-01", "2016-12-31"),
  date_format = "%Y-%m-%d", sex = c("male", "female", "unknown"),
  status = c("alive", "dead"), measurement = NULL, individualID = NULL,
  encounterID = NULL, encounter_type = NULL, Date_of_birth = NULL,
  Date_of_death = NULL)

Arguments

`object`	can be either "encounter" for the encounter search or "individual" for the individual search.
`location`	A string of character contained in location names.
`locationID`	A character vector for filtering the locationID.
`sighting_date`	A character for filtering encounters which are sighted during a period of time.
`encounter_submission_dates`	A character for filtering encounters which are submitted during a period of time.
`date_format`	The format for all the arguments of date valule.
`sex`	A character vector of maximum size of three represents the value for the sex filter.
`status`	A character vector of maximum size of two represents the value for the encounter status.
`measurement`	A numeric object sets the minimum individual measurement when searching in the Wildbook framework.
`individualID`	A character vector for searching data of specific individual ID.
`encounterID`	A character vector for searching data of specific encounter ID.
`encounter_type`	A character vector of maximum size of three for searching data with specific encounter type.
`Date_of_birth`	A character vector for searching data of individual which is borned during a period of time.
`Date_of_death`	A character vector for searching data of individual which is dead during a period of time.

Generate the search URL given the JDOQL query.

Description

This function helps users to generate the URL for data searching in the Wildbook framework with the account information of Wildbook, the URl of the desire wildbook and the JDOQL query.

Usage

WBsearchURL(username, password, baseURL, jdoql, protocol = "https")
WBsearchURL(username, password, baseURL, jdoql, protocol = "https")

Arguments

`username`	The username in the Wildbook framework.
`password`	The password in the Wildbook framework.
`baseURL`	The URL represent the desire wildbook data base.
`jdoql`	The JDOQL string for data searching.
`protocol`	Defines communication protocol. either "http" or "https" (default).

Package 'RWildbook'

Help Index

Transform a vector of date to a vector of millisecond.

Description

Usage

Arguments

Details

Generate the JDOQL part of a filter.

Description

Usage

Arguments

Identify operating system as Mac, *nix, or Windows

Description

Usage

Value

Format Wildbook data for mark-recaputure analysis

Description

Usage

Arguments

Details

Examples

RWildbook

Description

Pull data from the Wildbook framework.

Description

Usage

Arguments

Details

Examples

Generate the JDOQL part for the sex filter.

Description

Usage

Arguments

Data for the first vignette.

Description

Usage

Format

Source

Data for the second vignette.

Description

Usage

Format

Source

Generate the JDOQL query for the search in the Wildbook framework.

Description

Usage

Arguments

Generate the search URL given the JDOQL query.

Description

Usage

Arguments