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).

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)

Arguments

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")

Arguments

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)

Arguments

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 = "==")

Arguments

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()

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)

Arguments

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)                           

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)

Arguments

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:password@whaleshark.org/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)

Arguments

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

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

Format

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

Source

http://whaleshark.org