R/catmaid_connection.R
catmaid_login.Rdcatmaid_login allows you to login to a CATMAID server
specified by a catmaid_connection object. If such an object is not
specified, then the last successful connection in this R session is reused
if possible otherwise a new connection object is created using
options of the form "catmaid.\*" or "catmaid_\*" (see details).
The connection object returned by catmaid_login (or cached when
Cache=TRUE, the default) can then be used for future requests to the
CATMAID server by get/query/fetch functions.
catmaid_connection is a lower level function used by
catmaid_login to create a connection object. End users should not
need to call this directly, but it does document the arguments that can be
used to specify a connection to a CATMAID server.
print.catmaid_connection provides a convenient summary of
the status of a catmaid_connection.
catmaid_login(conn = NULL, ..., Cache = TRUE, Force = FALSE)
catmaid_connection(
server,
username = NULL,
password = NULL,
authname = NULL,
authpassword = NULL,
token = NULL,
authtype = NULL,
config = NULL
)
# S3 method for catmaid_connection
print(x, ...)An optional catmaid_connection connection object.
Additional arguments passed to catmaid_connection
Whether to cache open connections at login so that they can be reused automatically.
Whether to force a new login to the CATMAID server (default
FALSE)
url of CATMAID server
Your CATMAID username and password.
The http username/password that optionally secures the CATMAID website. These are not the same as your CATMAID login details.
An API token (A modern alternative to providing your CATMAID username and password). See Token based authentication for details.
The http authentication scheme, see
authenticate for details.
Additional curl config options. See config
for details and the examples section below.
A catmaid_connection object to print
a catmaid_connection object that can be used to make
authenticated http requests to a CATMAID server, specifically by making use
of the $config field.
After successful login, the catmaid_connection object will
contain a cookie field that includes a sessionid that is required
for subsequent GET/POST operations. When Cache=TRUE (the default)
the open connection object is cached and will be used when EITHER
catmaid_login is called with enough information to indicate that the
same server is desired OR (when no information about the server is passed
to catmaid_login) the last opened connection will be used.
Note the difference between authname/authpassword and
username/password. The former are for generic web
authentication, which is sometimes used to protect a private catmaid site
from being accessible to general web traffic. The latter are used to
authenticate to the CATMAID web application itself - for example the
username is the one that will be associated with any tracing carried
out by you in CATMAID.
CATMAID offers token based
authentication as the strongly preferred alternative to specifying you
CATMAID username and password. See
http://catmaid.github.io/dev/api.html#api-token for how to get an API
token. You can then set the catmaid.token or catmaid_token package option, but no
longer need to set the catmaid.username or catmaid_username and catmaid.password or catmaid_password
options.
Note that you must NOT reveal this token e.g. by checking it into a version controlled script as it gives complete access to your CATMAID account.
You will very likely want to set the following environment variables in
your .Renviron file (see Startup for details). This
file is read by R on startup. In this way the catmaid package will
automatically login to your preferred CATMAID server. Note that environment
variables will also be inherited by child R sessions. This means for
example that they will be available when running knitr reports, tests or R
CMD Check from Rstudio.
catmaid.server or catmaid_server
catmaid.token or catmaid_token Preferred to using catmaid.username/password
catmaid.authname or catmaid_authname Optional username for basic http website
authorisation
catmaid.authpassword or catmaid_authpassword Optional password for basic http website
authorisation
catmaid.username or catmaid_username Your catmaid username (deprecated in favour
of token)
catmaid.password or catmaid_password Your catmaid password (deprecated in favour
of token)
An example .Renviron file might look like (the periods(.) in the environmental variable name can be also replaced
with underscore(_) as mentioned above:
catmaid.server="https://mycatmaidserver.org/catmaidroot"
catmaid.token="9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
catmaid.authname="Calvin"
catmaid.authpassword="hobbes"and must finish with a return at the end of the last line. See http://catmaid.github.io/dev/api.html#api-token for details of obtaining an API token
Although setting environment variables is now the recommended
approach, you can also set R startup options e.g. in your .Rprofile
to specify default CATMAID login options including your personal access
token. The startup options have the same names as the environment variables
listed above, so you can place code along the lines of:
options(catmaid.server="https://mycatmaidserver.org/catmaidroot",
catmaid.authname="Calvin",catmaid.authpassword="hobbes", catmaid.token =
"9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b")
in your .Rprofile (see Startup for details). Note that
it is important to have a final return at the end of your .Rprofile
file.
# but see vfbcatmaid() convenience function
catmaid_login(server="https://l1em.catmaid.virtualflybrain.org")
if (FALSE) {
## example explicitly specifying connection options
# using modern token based authentication
conn = catmaid_login(server="https://mycatmaidserver.org/catmaidroot",
authname="Calvin",authpassword="hobbes",
token="9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b")
# ... or using the old fashioned approach specifiy username/password
conn = catmaid_login(server="https://mycatmaidserver.org/catmaidroot",
authname="Calvin",authpassword="hobbes",
username="calvin", password="hobbesagain")
## examples assuming that catmaid.* environment variables/options are set
conn = catmaid_login()
conn = catmaid_login(server='https://someotherserver.org/catmaidroot')
## set additional curl options/headers
# This example will bypass an SSL certificate verification error on the
# remote host e.g. if it has expired. Don't this regularly of course!
conn = catmaid_login(config=httr::config(ssl_verifypeer=0))
# This example will allow you to change the http protocol version while connecting!
# Changing the http version is useful when encountering curl related errors
conn = catmaid_login(config=httr::config(http_version=1))
## now do stuff with the connection like
skel=catmaid_fetch("1/10418394/0/0/compact-skeleton", conn=conn)
# you can also omit the connecttion because it will be cached and reused
skel=catmaid_fetch("1/10418394/0/0/compact-skeleton")
## or for those who want to work at the lowest level
skel2=GET("https://mycatmaidserver.org/catmaidroot/1/10418394/0/0/compact-skeleton",
config=conn$config)
}