diff --git a/docs/authors.html b/docs/authors.html index 3d13fae..abf5d49 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -23,14 +23,17 @@ - + + - + + + @@ -49,6 +52,12 @@ + + + + +
@@ -34,16 +59,17 @@
-

catmaid

-

This package provides access to the CATMAID API for R users. At present it provides low level functions for appropriately authenticated GET/POST requests, optionally parsing JSON responses. There are also intermediate level functions that retrieve skeleton (i.e. neuron) information, connectivity information for one or more neurons as well as a number of other API endpoints. Finally, there is a high level function to convert neurons to the representation of the nat (NeuroAnatomy Toolbox) R package, enabling a wide variety of analyses.

+

+catmaid

+

This package provides access to the CATMAID API for R users. At present it provides low level functions for appropriately authenticated GET/POST requests, optionally parsing JSON responses. There are also intermediate level functions that retrieve skeleton (i.e. neuron) information, connectivity information for one or more neurons as well as a number of other API endpoints. Finally, there is a high level function to convert neurons to the representation of the nat (NeuroAnatomy Toolbox) R package, enabling a wide variety of analyses.

It is strongly recommended to read through the instructions below, the package overview documentation and then skim the reference documentation index , which groups the available functions into useful categories.

- Quick start

+Quick start 
# install
 if (!require("devtools")) install.packages("devtools")
 # nb repo is rcatmaid, but R package name is catmaid
-devtools::install_github("jefferis/rcatmaid")
+devtools::install_github("jefferis/rcatmaid")
 
 # use 
 library(catmaid)
@@ -67,7 +93,7 @@

- Fancier example

+Fancier example

This produces a 3D plot of the first and second order olfactory neurons coloured according to the peripheral odorant receptor.

# fetch olfactory receptor neurons
 orns=read.neurons.catmaid("name:ORN (left|right)", .progress='text')
@@ -84,27 +110,27 @@

- Even fancier example

+Even fancier example

This follows on from the previous example. It identifies downstream partner neurons of the ORNs and plots them in 3d coloured by their synaptic strength. It then carries out morphological clustering with NBLAST and plots the partner neurons according to those clusters.

# find all the ORN downstream partners with at least 2 synapses
 orn_partners=catmaid_query_connected(orns[,'skid'], minimum_synapses = 2)
 # keep the ones not already in our set of PNs
 # there are lots!
-non_pn_downstream_ids=setdiff(unique(orn_partners$outgoing$partner), pns[,'skid'])
+non_pn_downstream_ids=setdiff(unique(orn_partners$outgoing$partner), pns[,'skid'])
 # download and plot those neurons
 non_pn_downstream=read.neurons.catmaid(non_pn_downstream_ids, .progress='text')
 plot3d(non_pn_downstream, col='grey', soma=1000)
 
 # remove the last set of plotted neurons
-npop3d()
+npop3d()
 
 ## Plot, but colouring partners by number of synapses they receive from ORNs
 # first collect those synapse numbers
 library(dplyr)
 totsyndf=orn_partners$outgoing %>% 
-  group_by(partner) %>% 
-  summarise(totsyn=sum(syn.count)) %>% 
-  arrange(desc(totsyn))
+  group_by(partner) %>% 
+  summarise(totsyn=sum(syn.count)) %>% 
+  arrange(desc(totsyn))
 hist(totsyndf$totsyn)
 # now do the plot
 clear3d()
@@ -121,16 +147,16 @@ 

 # Now let's cluster these other connected neurons
 library(nat.nblast)
 # convert to nblast-compatible format
-# nb also convert from nm to um, resample to 1µm spacing and use k=5
+# nb also convert from nm to um, resample to 1µm spacing and use k=5
 # nearest neighbours of each point to define tangent vector
-non_pn_downstream.dps=dotprops(non_pn_downstream/1e3, k=5, resample=1, .progress='text')
+non_pn_downstream.dps=dotprops(non_pn_downstream/1e3, k=5, resample=1, .progress='text')
 # now compute all x all NBLAST scores and cluster
-non_pn_downstream.aba=nblast_allbyall(non_pn_downstream.dps, .progress='text')
-non_pn_downstream.hc=nhclust(scoremat = non_pn_downstream.aba)
+non_pn_downstream.aba=nblast_allbyall(non_pn_downstream.dps, .progress='text')
+non_pn_downstream.hc=nhclust(scoremat = non_pn_downstream.aba)
 # plot result of clusterting as dendrogram, labelled by neuron name (rather than id)
 plot(non_pn_downstream.hc, label=non_pn_downstream[,'name'])
 # open new window
-nopen3d()
+nopen3d()
 # plot in 3d cutting into 2 clusters essentially left right
 plot3d(non_pn_downstream.hc,db=non_pn_downstream, k=2, soma=1000)
 clear3d() 
@@ -139,82 +165,100 @@

- Authentication

-

You will obviously need to have the login details of a valid CATMAID instance to try this out.

-
+Authentication +

You will obviously need to have the login details of a valid CATMAID instance to try this out. As of December 2015 CATMAID is moving to token based authentication. For this you will need to get an API token when you are logged into the CATMAID web client in your browser. See http://catmaid.github.io/dev/api.html#api-token for details.

+

Once you have the login information you can use the catmaid_login function to authenticate. The minimal information is your server URL and your CATMAID token.

+
catmaid_login(server="https://mycatmaidserver.org/catmaidroot",
+              authname="Calvin",authpassword="hobbes",
+              token="9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b")
+

Note that the CATMAID servers that I am aware of require two layers of password protection, an outer HTTP auth type user/password combination as well as an inner CATMAID-specific token based login. The outer HTTP auth type user/password combination may be specific to you or generic to the project.

+

- Setting package authentication options in your .Rprofile

-

It is recommended that you set these details by including code like this in in your .Rprofile file:

-
options(catmaid.server="https://mycatmaidserver.org/catmaidroot",
-  catmaid.authname="Calvin",catmaid.authpassword="hobbes",
-  catmaid.username="calvin", catmaid.password="hobbesagain")
-

In this way authentication will happen transparently as required by all functions that interact with the specified CATMAID server. Note that the CATMAID servers that I am aware of require two layers of password protection, an outer HTTP auth type user/password combination as well as an inner CATMAID-specific password.

+Setting environment variables in your .Renviron file +

It is recommended that you set your login details by including code like this in in your .Renviron file:

+
catmaid.server="https://mycatmaidserver.org/catmaidroot"
+catmaid.token="9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
+
+# additional security for mycatmaidserver.org/catmaidroot page
+catmaid.authname="Calvin"
+catmaid.authpassword="hobbes"
+

Be sure to leave one blank line at the end of the .Renviron file, or it will not work.

+

In this way authentication will happen transparently as required by all functions that interact with the specified CATMAID server.

-
+

- Token based authentication

-

As of December 2015 CATMAID is moving to token based authentication. For this you will need to get an API token when you are logged into the CATMAID web client in your browser. See http://catmaid.github.io/dev/api.html#api-token for details.

-

You would then set your .Rprofile like this:

+Setting environment variables in your .Rprofile file +

Alternatively you can set package options in your .Rprofile file, but the environment variable approach is now recommended as it handles a few edge cases where options are not read by R processes e.g. when building vignettes.

options(catmaid.server="https://mycatmaidserver.org/catmaidroot",
   catmaid.authname="Calvin",catmaid.authpassword="hobbes",
   catmaid.token="9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b")
-

Note that you will probably still need to specify you http username/password combination even if you are using an API token to authenticate to the CATMAID server.

+

Once again, be sure to leave one blank line at the end of the .Rprofile file, or it will not work.

- Cached authentication

-

Whether you use options in your .Rprofile as described above or you login explicitly at the start of a session by doing something like:

-
catmaid_login(server="https://mycatmaidserver.org/catmaidroot",
-              authname="Calvin",authpassword="hobbes",
-              token="9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b")
-

the access credentials will be cached for the rest of the session. You can still authenticate explicitly to a different CATMAID server (using catmaid_login) if you wish.

+Cached authentication +

Whether you use options in your .Renviron as described above or you login explicitly at the start of a session using catmaid_login the access credentials will be cached for the rest of the session. You can still authenticate explicitly to a different CATMAID server (using catmaid_login) if you wish.

- Multiple servers

-

If you need to talk to more than one catmaid server in a single session then you must use catmaid_login to login into each server

-
# log in to default server specified in .Rprofile
-conn1=catmaid_login()
+Multiple servers
+
If you use more than one CATMAID server but always do so in different sessions or rmarkdown scripts then you can save an appropriate .Renviron file in the project folder.

+
If you need to talk to more than one CATMAID server in a single session then you must use catmaid_login to login into each server

+
# log in to default server specified in .Renviron/.Rprofile
+conn1=catmaid_login()
 # log into another server, presumably with different credentials
-conn2=catmaid_login(server='https://my.otherserver.com', ...)

+conn2=catmaid_login(server='https://my.otherserver.com', ...)

and then use the returned connection objects with any calls you make e.g.

# fetch neuron from server 1
-n1=read.neuron(123, conn=conn1)
+n1=read.neuron(123, conn=conn1)
 # fetch neuron from server 2
-n2=read.neuron(123, conn=conn2)
-

nb you must use connection objects to talk to both servers because if no connection object is specified, the last connection will be re-used.

+n2=read.neuron(123, conn=conn2)
+

n.b. you must use connection objects to talk to both servers because if no connection object is specified, the last connection will be re-used.

- Installation

-

Currently there isn’t a released version on CRAN but can use the devtools package to install the development version:

+Installation +

Currently there isn’t a released version on CRAN but can use the devtools package to install the development version:

if (!require("devtools")) install.packages("devtools")
-devtools::install_github("jefferis/rcatmaid")
+devtools::install_github("jefferis/rcatmaid")

Note: Windows users need Rtools and devtools to install this way.

- Acknowledgements

+Acknowledgements

Based on python code presently visible at:

- +

by Albert Cardona and Philipp Schlegel. Released under the GPL-3 license.

+

Developers

+
    +
  • Gregory Jefferis
    Author, maintainer
    • +
+

Dev status

+
    +
  • Travis-CI Build Status
    • +
  • DOI
    • +
+
@@ -226,6 +270,8 @@

Developers

- + + - + + diff --git a/docs/pkgdown.css b/docs/pkgdown.css index fd7b0ba..209ce57 100644 --- a/docs/pkgdown.css +++ b/docs/pkgdown.css @@ -34,13 +34,14 @@ img.icon { float: right; } -/* Section anchors ---------------------------------*/ - -.hasAnchor { - margin-left: -30px; +img { + max-width: 100%; } +/* Section anchors ---------------------------------*/ + a.anchor { + margin-left: -30px; display:inline-block; width: 30px; height: 30px; @@ -56,6 +57,13 @@ a.anchor { visibility: visible; } +@media (max-width: 767px) { + .hasAnchor:hover a.anchor { + visibility: hidden; + } +} + + /* Fixes for fixed navbar --------------------------*/ .contents h1, .contents h2, .contents h3, .contents h4 { @@ -63,6 +71,17 @@ a.anchor { margin-top: -60px; } +/* Static header placement on mobile devices */ +@media (max-width: 767px) { + .navbar-fixed-top { + position: absolute; + } + .navbar { + padding: 0; + } +} + + /* Sidebar --------------------------*/ #sidebar { @@ -81,33 +100,64 @@ a.anchor { margin-bottom: 0.5em; } -/* Syntax highlighting ---------------------------------------------------- */ +/* Reference index & topics ----------------------------------------------- */ -code { - background-color: #f7f7f7; - color: #333; +.ref-index th {font-weight: normal;} +.ref-index h2 {font-size: 20px;} + +.ref-index td {vertical-align: top;} +.ref-index .alias {width: 40%;} +.ref-index .title {width: 60%;} + +.ref-index .alias {width: 40%;} +.ref-index .title {width: 60%;} + +.ref-arguments th {text-align: right; padding-right: 10px;} +.ref-arguments th, .ref-arguments td {vertical-align: top;} +.ref-arguments .name {width: 20%;} +.ref-arguments .desc {width: 80%;} + +/* Nice scrolling for wide elements --------------------------------------- */ + +table { + display: block; + overflow: auto; } -code a { - color: #375f84; + +/* Syntax highlighting ---------------------------------------------------- */ + +pre { + word-wrap: normal; + word-break: normal; + border: 1px solid #eee; } -.warning { color: red; } -.message { font-weight: bolder; } -.error { color: red; font-weight: bolder; } +pre, code { + background-color: #f8f8f8; + color: #333; +} -.fl,.number {color:rgb(21,20,181);} -.fu,.functioncall {color:#264D66 ;} -.ch,.st,.string {color:#375D81 ;} -.kw,.keyword {color:black;} -.argument {color:#264D66 ;} -.co,.comment {color: #777;} -.formalargs {color: #264D66;} -.eqformalargs {color:#264D66;} -.slot {font-style:italic;} -.symbol {color:black ;} -.prompt {color:black ;} +pre .img { + margin: 5px 0; +} -pre img { +pre .img img { background-color: #fff; display: block; + height: auto; +} + +code a, pre a { + color: #375f84; } + +.fl {color: #1514b5;} +.fu {color: #000000;} /* function */ +.ch,.st {color: #036a07;} /* string */ +.kw {color: #264D66;} /* keyword */ +.co {color: #888888;} /* comment */ + +.message { color: black; font-weight: bolder;} +.error { color: orange; font-weight: bolder;} +.warning { color: #6A0366; font-weight: bolder;} + diff --git a/docs/pkgdown.js b/docs/pkgdown.js index c8b38c4..4b81713 100644 --- a/docs/pkgdown.js +++ b/docs/pkgdown.js @@ -5,4 +5,41 @@ $(function() { offset: 60 }); + var cur_path = paths(location.pathname); + $("#navbar ul li a").each(function(index, value) { + if (value.text == "Home") + return; + if (value.getAttribute("href") === "#") + return; + + var path = paths(value.pathname); + if (is_prefix(cur_path, path)) { + // Add class to parent
  • , and enclosing
  • if in dropdown + var menu_anchor = $(value); + menu_anchor.parent().addClass("active"); + menu_anchor.closest("li.dropdown").addClass("active"); + } + }); }); + +function paths(pathname) { + var pieces = pathname.split("/"); + pieces.shift(); // always starts with / + + var end = pieces[pieces.length - 1]; + if (end === "index.html" || end === "") + pieces.pop(); + return(pieces); +} + +function is_prefix(needle, haystack) { + if (needle.length > haystack.lengh) + return(false); + + for (var i = 0; i < haystack.length; i++) { + if (needle[i] != haystack[i]) + return(false); + } + + return(true); +} diff --git a/docs/reference/as.catmaidmesh.html b/docs/reference/as.catmaidmesh.html index 593df5d..350b71c 100644 --- a/docs/reference/as.catmaidmesh.html +++ b/docs/reference/as.catmaidmesh.html @@ -23,14 +23,17 @@ - + + - + + + @@ -49,6 +52,12 @@