Title: R Interface to Experigen
Version: 0.2.1
Maintainer: Daniel Szeredi <daniel@szeredi.hu>
Description: Provides convenience functions to communicate with an Experigen server: Experigen (http://github.com/aquincum/experigen) is an online framework for creating linguistic experiments, and it stores the results on a dedicated server. This package can be used to retrieve the results from the server, and it is especially helpful with registered experiments, as authentication with the server has to happen.
Depends: R (≥ 3.2.3)
License: GPL-3
URL: https://github.com/aquincum/Rexperigen
LazyData: true
Imports: RCurl, digest, jsonlite
Suggests: testthat
RoxygenNote: 5.0.1
NeedsCompilation: yes
Packaged: 2016-08-25 21:06:32 UTC; dani
Author: Daniel Szeredi [aut, cre]
Repository: CRAN
Date/Publication: 2016-08-26 02:48:12

Rexperigen: an R interface to Experigen

Description

An R interface for downloading results from an Experigen server. Works with the "classic" server that is currently running on db.experigen.org as well, but its main advantage is that it helps a lot with the new functions of the newer version of the Experigen server. Most importantly, it helps with registration of experimenters, registration of experiments and accessing their data.

Setup functions

setExperigenServer, setExperigenCredentials

Registration functions

registerExperiment, removeRegistration, getRegisteredExperiments

Download functions

The main function is downloadExperiment. Further information about the experiment can be inquired with getUsers and getDestinations

Run a request to the API

Description

Run a request to the API

Usage

API.request(server = getOption("Rexperigen.server"), request = "version",
  params = list(), auth = FALSE, method = "GET")

Arguments

server

The server name (no need to be clean)

request

The request verb to the server

params

A list of name=value pairs that will be passed to the server

auth

Do we send authentication? If this is FALSE, we don't.

method

The HTTP method to use (GET | POST | PUT | DELETE).

See Also

Other development: checkAuthentication, create.API.request.URL, prepare.server.URL, server.version

Error string returned when no server is found

Description

Error string returned when no server is found

Usage

NO_SERVER_ERROR

Format

An object of class character of length 1.

Checks whether the authentication is supported by the server and handles the different POST request routes.

Description

Checks whether the authentication is supported by the server and handles the different POST request routes.

Usage

checkAuthentication(request, auth, version.needed = 1)

Arguments

request

The needed request to be made (without .cgi).

auth

Whether authentication is requested in R.

version.needed

The minimum version of the request. If it is 1, and the server is version 1, the function will append .cgi to the request.

Value

A list:

  1. request: the request to send

  2. auth: whether to still send an authenticated request.

See Also

Other development: API.request, create.API.request.URL, prepare.server.URL, server.version

Examples

checkAuthentication("makecsv", TRUE)
checkAuthentication("registration", TRUE, 2)

Checks whether the user is logged in.

Description

Checks whether the user is logged in. It also throws an exception if the server is of an old version and logging in is not supported.

Usage

checkLogin()

Value

The experimenter login user name

Examples

options(Rexperigen.server.version="2.0.0")
setExperigenCredentials("my", "credentials", check = FALSE)
checkLogin()

Returns the cleaned source URL.

Description

Experigen has been using some URL cleaning since version 1. This function asks the server (if version >= 2) to return how it would clean the given URL. For older versions, you still have to replace /'s and stuff by .'s by yourself, sorry!

Usage

cleanURL(sourceURL)

Arguments

sourceURL

The source URL to clean

Value

The cleaned URL

Examples

## Not run: 
cleanURL("https://s3.amazonaws.com/myexperiment/index.html")

## End(Not run)

Create an URL for a request to the Experigen API.

Description

Create an URL for a request to the Experigen API.

Usage

create.API.request.URL(server, request, params = list())

Arguments

server

The server name (no need to be clean)

request

The request verb to the server

params

A list of name=value pairs that will be passed to the server

Value

A URL that can be queried.

See Also

Other development: API.request, checkAuthentication, prepare.server.URL, server.version

Examples

create.API.request.URL("db.phonologist.org", "users", list(sourceurl="x.y", experimentName="z"))

Create a login for yourself using this function

Description

Create a login for yourself using this function

Usage

createExperimenter(experimenter, password)

Arguments

experimenter

The username.

password

Your password.

Value

A string that the server returns ("done" if success)

Makes a download request from the server.

Description

This function downloads the results of an experiment.

Usage

downloadExperiment(sourceURL, experimentName, destination = "default.csv",
  auth = FALSE)

Arguments

sourceURL

The source URL for the experiment

experimentName

The experiment name as set in settings.js

destination

The file to download. By default, all uploaded results are saved in default.csv, which is the default file to download.

auth

Whether authentication is needed

Value

The downloaded data set as data frame

See Also

Other download: getDestinations, getUsers

Examples

## Not run: 
downloadExperiment("https...s3.amazonaws.com.myexperiment.index.html", "testing1")
downloadExperiment("https...s3.amazonaws.com.myexperiment.index.html", "running", auth = TRUE)

## End(Not run)

Returns the list of destination files for an experiment.

Description

Returns the list of destination files for an experiment.

Usage

getDestinations(sourceURL, experimentName, auth = FALSE)

Arguments

sourceURL

The source URL for the experiment

experimentName

The experiment name as set in settings.js

auth

Whether authentication is needed

Value

The list of destinations

See Also

Other download: downloadExperiment, getUsers

Examples

## Not run: 
getDestinations("https...s3.amazonaws.com.myexperiment.index.html", "running", auth = TRUE)

## End(Not run)

Get a list of registered experiments.

Description

Returns a list of the registered experiments for the logged in experimenter.

Usage

getRegisteredExperiments()

Value

The parsed list of experiments

See Also

Other registration: registerExperiment, removeRegistration

Examples

## Not run: 
getRegisteredExperiments()

## End(Not run)

Requests the table of users from the server.

Description

Requests the table of users from the server.

Usage

getUsers(sourceURL, experimentName, auth = FALSE)

Arguments

sourceURL

The source URL for the experiment

experimentName

The experiment name as set in settings.js

auth

Whether authentication is needed

Value

The table of users

See Also

Other download: downloadExperiment, getDestinations

Examples

## Not run: 
getUsers("https...s3.amazonaws.com.myexperiment.index.html", "running", auth = TRUE)

## End(Not run)

Simply removes the stored credentials, so following requests will be unauthenticated.

Description

Simply removes the stored credentials, so following requests will be unauthenticated.

Usage

logoutExperigen()

Server URL preparation.

Description

Prepares the server URL by checking for the presence of a protocol prefix, and prefixing http:// if there is none. Also, returns the URL with a trailing / if that was not present either.

Usage

prepare.server.URL(server)

Arguments

server

A server name.

Value

A clean URL with protocol prefix and trailing slash.

See Also

Other development: API.request, checkAuthentication, create.API.request.URL, server.version

Examples

prepare.server.URL("db.phonologist.org")
prepare.server.URL("https://myserver.com/")

Registers an experiment to the experimenter.

Description

Registers the given experiment to the experimenter. Returns the server's response. Do provide the credentials before calling this function

Usage

registerExperiment(sourceURL, experimentName)

Arguments

sourceURL

The source URL for the experiment

experimentName

The experiment name as set in settings.js

Value

The server response.

See Also

Other registration: getRegisteredExperiments, removeRegistration

Examples

## Not run: 
registerExperiment("https...s3.amazonaws.com.myexperiment.index.html", "running")

## End(Not run)

Removes the registration of the experiment

Description

Removes the registration of the experiment to the logged in experimenter. Does not remove any data though! All of the data will be available to anyone.

Usage

removeRegistration(sourceURL, experimentName)

Arguments

sourceURL

The source URL for the experiment

experimentName

The experiment name as set in settings.js

Value

The server response.

See Also

Other registration: getRegisteredExperiments, registerExperiment

Examples

## Not run: 
removeRegistration("https...s3.amazonaws.com.myexperiment.index.html", "running")

## End(Not run)

Returns the version of an Experigen server

Description

Returns the version of an Experigen server

Usage

server.version(server = getOption("Rexperigen.server"))

Arguments

server

The server name

Value

A string with the Experigen server version

See Also

Other development: API.request, checkAuthentication, create.API.request.URL, prepare.server.URL

Examples

server.version("db.phonologist.org")

Sets up the experimenter credentials for the further requests. It can also check whether the authentication is successful.

Description

Sets up the experimenter credentials for the further requests. It can also check whether the authentication is successful.

Usage

setExperigenCredentials(experimenter, password, check = TRUE, quiet = FALSE)

Arguments

experimenter

The experimenter username

password

The password for the experimenter

check

Whether to check if the experimenter is registered.

quiet

If TRUE, the function will not print out the result of the existence check

Value

Whether the existence check is successful. If check = FALSE, it will return TRUE by default

See Also

Other setup: setExperigenServer

Examples

## Not run: 
setExperigenCredentials("joesmith", "1234")

## End(Not run)
setExperigenCredentials("janemiller", "passdrow", check = FALSE)

Sets the Experigen server address for further operations. By default, it checks the existence of the server and sets the Rexperigen.server.version option based on the response of the server. If check = FALSE, set the version by yourself!

Description

Sets the Experigen server address for further operations. By default, it checks the existence of the server and sets the Rexperigen.server.version option based on the response of the server. If check = FALSE, set the version by yourself!

Usage

setExperigenServer(server, check = TRUE)

Arguments

server

The server's URL

check

Whether to check the server's existence

See Also

Other setup: setExperigenCredentials

Examples

setExperigenServer("db.phonologist.org")
setExperigenServer("localhost:3000", FALSE)

Returns the main version number of the server.

Description

Returns the main version number of the server.

Usage

versionMain()

Value

The main version number as a numeric