R/conn.R
neuprint_login.Rdneuprint_login allows you to login to a neuPrint server
specified by a neuprint_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
environment variables of the form "neuprint_*" (see details).
If your server has more than one dataset available, it is also a good idea
to set the default neuPrint dataset you want to work with, either by
passing an explicit dataset argument (to neuprint_login or
neuprint_connection) when first making the connection or by setting
a neuprint_dataset environment variable.
The connection object returned by neuprint_login (or cached when
Cache=TRUE, the default) can then be used for future requests to the
neuPrint server by get/query/fetch functions.
neuprint_connection(
server = NULL,
token = NULL,
dataset = NULL,
conn = NULL,
config = httr::config()
)
neuprint_login(conn = NULL, Cache = TRUE, Force = FALSE, ...)the neuprint server
your personal Bearer token
A default dataset to use with this connection (you can still
override this using the dataset argument of other neuprintr
functions.)
a neuprintr connection object
an httr::config object that can be used to
set advanced curl options (e.g. additional authentication, proxy settings
etc). See Curl options section and Examples.
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)
methods passed to neuprint_connection
a neuprint_connection object that can be used to make
authenticated https requests to a neuPrint server, specifically by making
use of its $config field.
After successful login, the neuprint_connection object will
contain a cookie field that includes a sessionid that is required
for subsequent GET/POST operations using the package httr. When
Cache=TRUE (the default) the open connection object is cached and
will be used when EITHER neuprint_login is called with enough
information to indicate that the same server is desired OR (when no
information about the server is passed to neuprint_login) the last
opened connection will be used. A new connection can be made using
Force = TRUE, which is advisable as a first call for debugging if
you are having issues querying the server.
neuPrint requires Bearer token based
authentication. You can get your token by going to your neuPrint server's
webpage and right clicking on the icon showing your Google account on the
top right corner, and selecting AUTH_TOKEN, or often at your
server's address /token, once you have signed in via your approved
Google account. Contact the server's administrators if you do not have
access, but think that you should. You can then set the
catmaid.token package option, but no
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 neuPrint 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 neuprintr package will
automatically login to your preferred neuPrint 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. In order to edit your R.profile or
R.environ files easily and directly, try using
usethis::edit_r_environ() and usethis::edit_r_profile()
neuprint_server
neuprint_token
neuprint_dataset
An example .Renviron file might look like:
neuprint_server = "https://neuprint.janelia.org"
neuprint_token =
"asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5zaGFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIjoiaHR0cHM7Ly9saDQuZ29vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUFBQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21vL3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjU2HH0.jhh1nMDBPl5A1HYKcszXM518NZeAhZG9jKy3hzVOWEU"and must finish with a return at the end of the last line. Your
neuprint_token is unique to you and must be obtained from a neuPrint
web page once you have logged in with an approved Google account.
The use of the neuprint_dataset environment variable is optional and
only recommended when your default neuprint server has more than one
dataset. This default will not apply to connections that refer to a
server other than the one specified by the neuprint_server
environment variable.
neuprint_dataset = "hemibrain:v1.0"Although setting environment variables is the recommended
approach, you can also set R startup options e.g. in your .Rprofile
to specify default neuPrint 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(neuprint_server = 'https://neuprint.janelia.org',
neuprint_token =
"asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5zaGFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIjoiaHR0cHM7Ly9saDQuZ29vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUFBQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21vL3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjU2HH0.jhh1nMDBPl5A1HYKcszXM518NZeAhZG9jKy3hzVOWEU")
in your .Rprofile (see Startup for details). Note that
it is important to have a final return at the end of your .Rprofile
file.
neuprintr uses the curl library provided by the
httr and curl packages to carry out remote requests. You can
set curl options by passing an httr::config object that
can be used to set advanced curl options (e.g. additional authentication,
proxy settings etc). See handle and
curl_options for a full list of possible options.
You can also set default curl options using environment variables with
names of the form neuprint_curl_<curloption>. For example the
following entry in you Renviron file will set the curl
ssl_verifyhost option:
neuprint_curl_ssl_verifyhost=0
if (FALSE) { # \dontrun{
## example explicitly specifying connection options
conn = neuprint_login(server= "neuprint.janelia.org",
token= "asBatEsiOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImFsZXhhbmRlci5za
GFrZWVsLmJhdGVzQGdtYWlsLmNvbSIsImxldmVsIjoicmVhZHdyaXRlIiwiaW1hZ2UtdXJsIj
oiaHR0cHM7Ly9saDQuZ35vZ2xldXNlcmNvbnRlbnQuY29tLy1QeFVrTFZtbHdmcy9BQUFBQUF
BQUFBDD9BQUFBQUFBQUFBQS9BQ0hpM3JleFZMeEI4Nl9FT1asb0dyMnV0QjJBcFJSZlBRL21v
L3Bob3RvLapwZz9zej01MCIsImV4cCI6MTczMjc1MjM2HH0.jhh1nMDBPl5A1HYKcszXM518NZ
eAhZG9jKy3hzVOWEU")
## examples assuming that neuprint_* environment variables/options are set
conn = neuprint_login()
## using env vars + config to set advanced curl options
neuprint_login(config=httr::config(ssl_verifyhost=0))
## now do stuff with the connection like
available.datasets = neuprint_datasets(conn=conn)
## which, if you have edited your R.profile / R.environ, should produce the same results as
available.datasets = neuprint_datasets(conn=NULL)
# make connection to second server
conn2=neuprint_login(server="https://server2.org",
token=Sys.getenv('NPSERVER2'))
# specify a default dataset (only required when >1 dataset available)
conn2=neuprint_login(server="https://server2.org",
token=Sys.getenv('NPSERVER2'), dataset="hemibrain")
# make a connection to the same server but using a different dataset
# this may be more convenient than specifying the dataset argument
conn3=neuprint_login(conn2, dataset="vnc")
} # }