Internal function to create obm_class from data.frame

Description

This internal function creates an obm_class

Usage

as.obm_class(x)

Value

structured data

Retrieve a variable from the OBM session environment

Description

Retrieve a variable from the OBM session environment

Usage

get_obm(name, default = NULL)

Password reader helper function

Description

used in obm_auth() Not intended for direct user use.

Usage

get_password()

Log in to an OpenBioMaps server

Description

This function allows you to connect to and OBM server.

Usage

obm_auth(username = "", password = "", verbose = FALSE, paranoid = TRUE)

Arguments

Value

true if successful and false if not

Examples

# default interactive authentication
obm_auth()

# authentication with username and password
obm_auth('foo@google.com','abc123')

Background Computation Function

Description

This experimental function allows to manage background computation on an OpenBioMaps server.

Usage

obm_computation(
  action = "",
  data_files = NULL,
  params = NULL,
  config_file = NULL
)

Arguments

Value

data frame or boolean

Examples

# Manage computational packs
results <- obm_computation(action='post',
                           data_files='examples/scripts/bombina.R',
                           params=list(package = 'my_project'),
                           config_file='examples/computation_conf.yml')

Connect to a server with a shared link

Description

This function allows to connect to an OBM server with a shared link It using client_credentials authentication, so it is returning an access_token Return an oauth token

Usage

obm_connect(link = "", verbose = FALSE)

Arguments

Value

boolean

Examples

# Interactive connect
obm_connect()
# Non interactive connect
token <- obm_connect('abcdefghikl123456789')

Get or set OpenBioMaps session environment

Description

Get or set OpenBioMaps session environment

Usage

obm_env()

Get Information/Data from an OpenBioMaps project

Description

This function get data or information from a project. Supported functions (APIv3): get_data: Get records from an SQL table or view, get_public_data: Get publicly available records from an SQL table or view, get_tables: Get list of SQL tables (or column list) and VIEWS in a project, get_form_list, get_form_data: Get upload form information For API v3 (api_version >= 3.0), 'get_data' uses GraphQL for powerful filtering and data selection. See the [GraphQL User Guide](https://gitlab.com/openbiomaps/api/obm-project-api/-/blob/main/GraphQLUserGuide.md) for more details on query possibilities.

Usage

obm_get(
  scope = "",
  control_condition = NULL,
  condition = NULL,
  table = get_obm("project")
)

Arguments

Details

The following code *illustrates* how you could use this function in practice, but it is **not meant to be run directly** (e.g., depends on external data).

# — API v3 GraphQL Examples —

# get rows where column 'species' is 'Parus palustris' (case-insensitive)
data <- obm_get('get_data', condition=list(species = list(iequals = 'Parus palustris')))

# get specific fields from a specific table and schema
data <- obm_get('get_data',
                condition=list(
                  schema = "public",
                  table = "dead_animals",
                  fields = c("obm_id", "faj", "hely"),
                  faj = list(iequals = "asio otus")
                ))

# get all fields from the default table
data <- obm_get('get_data', 
                condition=list(
                  fields = '*',
                  faj = list(iequals = "asio otus")
                ))

# get 100 rows with offset 0
data <- obm_get('get_data', 'limit=100:0')

# get list of available forms
data <- obm_get('get_form_list')

# get list of available tables in the project
obm_get('get_tables')

# get table details (columns) in v3
obm_get('get_tables', condition=list(schema="public", table="dead_animals"))

# — API v2 Examples —

results <- obm_get('get_form_list')

form <- obm_get('get_form_data',results[,]$published_form_id)

# get data rows from the main table from 39980 to 39988
data <- obm_get('get_data',condition=list(obm_id = '39980:39988'))

#get rows from the main table where column 'species' is 'Parus palustris'
data <- obm_get('get_data',condition=list(species = 'Parus palustris'))

#get 100 rows only from filtered query
data <- obm_get('get_data','limit=100:0',condition=list(species = 'Parus palustris'))

#get all data from the default/main table
data <- obm_get('get_data','*')

#get data from a non-default table
data <- obm_get('get_data','*',table='additional_data')

Value

a data.frame, list or error message

Examples

data <- obm_get('get_data', condition=list(species = list(iequals = 'Parus palustris')))

obm_get_graphql helper function

Description

Helper to execute GraphQL query Not intended for direct user use.

Usage

obm_get_graphql(
  scope,
  control_condition,
  condition,
  token,
  url,
  table,
  retry = TRUE
)

obm_get_rest_v3 helper function

Description

Helper to execute REST API v3 queries (non-GraphQL) Not intended for direct user use.

Usage

obm_get_rest_v3(scope, control_condition, condition, token, url, table)

Initialise connection to an OpenBioMaps server

Description

This function is initiating an OBM connection.

Usage

obm_init(
  project = "",
  url = "openbiomaps.org",
  scope = c(),
  verbose = FALSE,
  api_version = 3
)

Arguments

Value

boolean

Examples

# connect with API v3 to the dead_animals project on the default openbiomaps.org server
obm_init(project='dead_animals')
# connect to a database on the default server (openbiomaps.org) with API v2.5
obm_init(project='dead_animals', api_version=2.5)
# connect on the local server instance to the butterfly database project
obm_init(url='http://localhost/biomaps',project='butterflies')

obm_parse_control helper function

Description

Helper function to parse control string (e.g. "limit=100:0") Not intended for direct user use.

Usage

obm_parse_control(control_string)

obm_parse_filters helper function

Description

Helper to construct GraphQL filter from condition list Not intended for direct user use.

Usage

obm_parse_filters(condition)

Put data unsing obm forms

Description

This function allows put data into an OpenBioMaps server. For API v3 (api_version >= 3.0), 'put_data' is supported. Note: In API v3, 'put_data' currently supports single observation upload only.

Usage

obm_put(
  scope = NULL,
  form_header = NULL,
  data_file = NULL,
  media_file = NULL,
  form_id = "",
  form_data = "",
  soft_error = "",
  data_table = NULL
)

Arguments

Details

The following code *illustrates* how you could use this function in practice, but it is **not meant to be run directly** (e.g., depends on external data).

# Using own list of columns
results <- obm_get('get_form_list')
form_id <- results$form_id[1] # e.g. 57

response <- obm_put('put_data',columns[1:3],form_id=form_id,data_file='examples/test_upload.csv')

# Using default columns list:
response <- obm_put(scope='put_data',form_id=57,csv_file='examples/test_upload.csv')

# JSON upload
data <- matrix(c(
                 c("Tringa totanus",'egyed',"AWBO",'10','POINT(47.1 21.3)'),
                 c("Tringa flavipes",'egyed',"BYWO",'2','POINT(47.3 21.4)')
               ),ncol=5,nrow=2,byrow=TRUE)
colnames(data)<-c("species","numerosity","location","quantity","geometry")

response <- obm_put(
               scope='put_data',
               form_id=57,
               form_data=as.data.frame(data),
               form_header=c('faj','szamossag','hely','egyedszam'))

# With attached files
data <- matrix(c(c("Tringa totanus",'egyed',"AWBO",'10','numbers.odt'),
                 c("Tringa flavipes",'egyed',"BYWO",'2','observation.jpg')
               ),ncol=5,nrow=2,byrow=TRUE)
colnames(data)<-c("species","numerosity","location","quantity",'Attach')

response <- obm_put(
               scope='put_data',
               form_id=57,
               form_data=as.data.frame(data),
               form_header=c('species','numerosity','location','quantity','obm_files_id'),
               media_file=c('examples/numbers.odt','examples/observation.jpg'))

Value

json or boolean

Examples

csv_path <- system.file("examples/test_upload.csv", package = "obm")
csv_data <- read.csv(csv_path)
columns <- names(csv_data)
response <- obm_put('put_data',columns[1:3],form_id=57,data_file='examples/test_upload.csv')

Put data helper function for API v3

Description

Internal function to handle API v3 puts Not intended for direct user use.

Usage

obm_put_v3(scope, form_id, form_data, media_file, token, url, verbose = FALSE)

Value

json results object or boolean

Refresh an expired OBM access token

Description

This function requests a new access token using the stored refresh token. It should normally be called internally by other OBM functions when the current token has expired.

Usage

obm_refresh_token(
  token = NULL,
  url = get_obm("token_url"),
  client_id = get_obm("client_id", "R"),
  verbose = FALSE
)

Arguments

Value

Logical TRUE if token refreshed successfully, FALSE otherwise

Examples

obm_refresh_token(token='ABCD1234')

Repozitorium manager function

Description

This experimental function allows manage Dataverse repozitorium and datasets.

Usage

obm_repo(scope = NULL, data_table = NULL, params = NULL)

Arguments

Details

The following code *illustrates* how you could use this function in practice, but it is **not meant to be run directly** (e.g., depends on external data).

# Set the default server/project-repo for each of the following operations
#   - default is 0
#   - get possible names from server_conf query above
obm_repo('set', params=list(REPO='ABC-REPO'))
obm_repo('set', params=list(REPO='ABC-REPO', PARENT='dataverse/parent'))

# Listing dataverse
results <- obm_repo('get', params=list(type='dataverse', contents=1))
results <- obm_repo('get', params=list(type='dataverse'))

# Getting content of the named dataverse
results <- obm_repo('get', params=list(id='MY-DATAVERSE'))

# Get JSON Representation of a Dataset
results <- obm_repo('get', params=list(type='datasets', 
                                       persistentUrl='https://doi.org/xxx/xxx/xxx'))
results <- obm_repo('get', params=list(type='datasets', id='XABC-1'))

# Get versions of dataset
results <- obm_repo('get',params=list(type='datasets', id=42, version=''))
results <- obm_repo('get',params=list(type='datasets', id=42, version=':draft'))

# Get files of dataset
results <- obm_repo('get',params=list(type='datasets', id=42, files='', version=''))

# Get a file
results<-obm_repo('get',params=list(type='datafile', id=83))
results<-obm_repo('get',params=list(type='datafile', id=83, version=':draft'))

# Create a dataverse
results <- obm_repo('put',params=list(type='dataverse'))

# Create a dateset
results <- obm_repo('put',params=list(type='datasets', dataverse='my_dataset'))

# Add file to dataset (referenced by id or persistentUrl)
results <- obm_repo('put',params=list(type='datafile', 
                                      file='examples/test_upload.csv',
                                      id='XABC-1' ))
results <- obm_repo('put',params=list(type='datafile', 
                                      file='examples/test_upload.csv', 
                                      persistentUrl='https://doi.org/xxx/xxx/xxx'))

# Add object as file to dataset (referenced by id or persistentUrl)
# - automatically convert data object to JSON
# - returning with the last file's state
init.df <- data.frame()
results <- obm_repo('put',params=list(type='datafile', 
                                      id='XABC-1', 
                    data=list(results=res.list,
                              init_params=init.df)))

# Delete file
results <- obm_repo('delete',params=list(type='datafile',
                                         id='XABC-1',
                                         PARENT_DATAVERSE='dataverse/parent'))

# Set settings
# obm_repo('set',params=list(type='dataset',id='XABC-1'))

Value

data frame or boolean

Examples

# Getting server conf
results <- obm_repo('get', params=list(server_conf=1))

Set Function

Description

Experimental function in APIv2! This function allows you to set rules for obm_get.

Usage

obm_set(scope = "", condition = "")

Arguments

Value

list, json or boolean

Examples

# automatically join tables
data <- obm_set('set_join',c('dead_animals','dead_animals_history'))

SQL Interface

Description

It is a simple SQL Query interface function

Usage

obm_sql_query(
  sqlcmd,
  username = "",
  password = "",
  paranoid = TRUE,
  port = 5432,
  database = "gisdata"
)

Arguments

Value

sql data object or boolean

Examples

obm_sql_query("SELECT DATE_PART('day', enddate::timestamp - startdate::timestamp) AS days 
               FROM nestboxes WHERE enddate IS NOT NULL AND startdate IS NOT NULL 
               ORDER BY days")

Random text generator helper function

Description

Not intended for direct user use.

Usage

randtext(n = 5000)

Value

text string

Assign a variable into the OBM session environment

Description

Assign a variable into the OBM session environment

Usage

set_obm(name, value)