diff --git a/NEWS.md b/NEWS.md index 91f8bd58..19024444 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,6 +4,8 @@ `list(c(1,2,3), c(4,5,6)) (#485) * a new function `xyzmatrix2list()` is added to achieve this output format directly +* `xyzmatrix()` can now extract coordinates from a 3-vector like `c(1,3,5)` + (#486) # 1.10.3 diff --git a/docs/404.html b/docs/404.html index bfd50493..1759d08f 100644 --- a/docs/404.html +++ b/docs/404.html @@ -1,74 +1,34 @@ - - -
- + + + + -vignettes/Installation.Rmd
+ Source: vignettes/Installation.Rmd
Installation.Rmd
This document provides additional details about installation that may help you solve certain difficulties, especially on Windows or Mac platforms.
-The source code for this vignette is available at https://github.com/natverse/nat/blob/master/vignettes/Installation.Rmd. If you find something unclear or notice a typo, I would be very happy if you would click on the Pencil Icon on that page or follow this link to edit and suggest an alternative wording. Don’t be shy about doing this; I have to review any change and even if your suggestion is not perfect it will still be a prompt for me to improve this document. Thank you!
+The source code for this vignette is available at https://github.com/natverse/nat/blob/master/vignettes/Installation.Rmd. If you find something unclear or notice a typo, I would be very happy if you would click on the Pencil Icon on that page or follow this link to edit and suggest an alternative wording. Don’t be shy about doing this; I have to review any change and even if your suggestion is not perfect it will still be a prompt for me to improve this document. Thank you!
nat is an R package and therefore runs on Mac/Linux/Windows. The only pre-requisite for most functionality is a recent version of R (>=3.1.0 recommended).
-3D visualisation is provided by the rgl package based on OpenGL. On Mac OS X if you use RStudio or R from the terminal, you must have a copy of XQuartz, the X11 window manager, installed. This is no longer a default install since Mac OS X 10.8. You need to install XQuartz, before installing the nat package. Logout and login for the installation to take effect. You can get it from https://xquartz.macosforge.org/landing/. This page is also linked from the Download R for (Mac) OS X page.
+3D visualisation is provided by the rgl package based on OpenGL. On Mac OS X if you use RStudio or R from the terminal, you must have a copy of XQuartz, the X11 window manager, installed. This is no longer a default install since Mac OS X 10.8. You need to install XQuartz, before installing the nat package. Logout and login for the installation to take effect. You can get it from https://www.xquartz.org/. This page is also linked from the Download R for (Mac) OS X page.
If you want to apply non-rigid registrations calculated by the Computational Morphometry Toolkit (CMTK) you will need to install that separately – see section External Dependencies below.
As of v1.0 there is a released version on CRAN. This is normally updated only every few months.
-install.packages("nat")
install.packages("nat")
If you wish to run the package tests, it is necessary to install with all dependencies:
-install.packages("nat", dependencies=TRUE)
install.packages("nat", dependencies=TRUE)
nat remains under quite active development, so we generally suggest using the development version directly from github. The recommended way to do this is to install Hadley Wickham’s invaluable devtools package (if you have not already done so) and then use that to install nat.
+nat remains under quite active development, so we generally suggest using the development version directly from github. The recommended way to do this is to install Hadley Wickham’s invaluable devtools package (if you have not already done so) and then use that to install nat.
# install devtools if required
-if (!require("devtools")) install.packages("devtools")
+if (!require("devtools")) install.packages("devtools")
# then install nat
-devtools::install_github("natverse/nat")
The nat package includes extensive unit tests which are run along with R’s (extremely fastidious) package check routines by the Travis continuous integration server. The master branch is therefore considered very stable and may well contain fixes or enhancements over released versions. However, you can install any release version including the latest release as follows:
+devtools::install_github("natverse/nat")The nat package includes extensive unit tests which are run along with R’s (extremely fastidious) package check routines by the Travis continuous integration server. The master branch is therefore considered very stable and may well contain fixes or enhancements over released versions. However, you can install any release version including the latest release as follows:
-devtools::install_github("natverse/nat@v1.8.6")
The same syntax can be used to install any arbitrary version that you want from github. See ?install_github
for details.
Note: Windows users need Rtools to install in this way, but devtools should offer to install this for you if you do not already have it.
+devtools::install_github("natverse/nat@v1.8.6")
The same syntax can be used to install any arbitrary version that you want from github. See ?install_github
for details.
Note: Windows users need Rtools to install in this way, but devtools should offer to install this for you if you do not already have it.
nat is self sufficient for core functionality, but the transformation of 3D data using Computational Morphometry Toolkit (CMTK) registrations depends on an external installation of that toolkit. CMTK binaries can be downloaded for Windows, Linux and Mac at http://www.nitrc.org/projects/cmtk/. Source code is available from the same site or an unofficial mirror repository at https://github.com/jefferis/cmtk. We have extensive experience of using CMTK under Linux (where we compile from source) and Mac (where we compile or use the MacOSX-10.6-x86_64.dmg binary installers). We have also used neurodebian to install as part of the Travis continuous integration setup (see the project’s .travis.yml file).
-nat is self sufficient for core functionality, but the transformation of 3D data using Computational Morphometry Toolkit (CMTK) registrations depends on an external installation of that toolkit. CMTK binaries can be downloaded for Windows, Linux and Mac at https://www.nitrc.org/projects/cmtk/. Source code is available from the same site or an unofficial mirror repository at https://github.com/jefferis/cmtk. We have extensive experience of using CMTK under Linux (where we compile from source) and Mac (where we compile or use the MacOSX-10.6-x86_64.dmg binary installers). In the past we have also used neurodebian to install as part of the Travis continuous integration setup (see the project’s .travis.yml file).
+We have much less experience using CMTK on Windows than on Mac/Linux platforms. Experiments in May 2016 suggest that the best option is to use the cygwin CMTK distribution (cygwin provides a linux like environment). Here are the steps we took:
C:\cygwin64
+C:\cygwin64
CMTK-3.3.1-CYGWIN-x86_64.tar.gz
to the cygwin folder (C:\cygwin64
)cd /
(this is the same place as C:\cygwin64
in the Windows file system).tar -xvf CMTK-3.3.1-CYGWIN-x86_64.tar.gz
to extract CMTK to the cygwin folder.C:\cygwin64\bin
to your windows path (since v1.8.10 nat should look after this - see ?cmtk.bindir).cmtk.bindir()
should now correctly identify the CMTK binary directory. You can test that the executables are working by trying the following in R library(nat);cmtk.dof2mat(version = TRUE)
which should then respond with “3.3.1” if you have installed the CMTK version we have just mentioned.cmtk.bindir()
should now correctly identify the CMTK binary directory. You can test that the executables are working by trying the following in R library(nat);cmtk.dof2mat(version = TRUE)
which should then respond with “3.3.1” if you have installed the CMTK version we have just mentioned.Developed by Gregory Jefferis, James Manton, Sridhar Jagannathan.
+ +Developed by Gregory Jefferis, James Manton, Sridhar Jagannathan.
vignettes/NeuroGeometry.Rmd
+ Source: vignettes/NeuroGeometry.Rmd
NeuroGeometry.Rmd
One of the key distinguishing features of nat is the ability to analyse neuronal morphology and connectivity from a geometric perspective. In other words nat provides functions to analyse the placement of neurons within the context of the brain and the organisation of local circuits.
This vignette will give a few examples, but this is only skimming the surface of what is possible.
If you see an analysis in a paper associated with the Jefferis lab but cannot figure out how to use nat to achieve this, then feel free to contact the nat–user Google group to ask for help.
+If you see an analysis in a paper associated with the Jefferis lab but cannot figure out how to use nat to achieve this, then feel free to contact the nat–user Google group to ask for help.
## Loading required package: rgl
-## Registered S3 method overwritten by 'nat':
-## method from
-## as.mesh3d.ashape3d rgl
-##
-## Attaching package: 'nat'
-## The following object is masked from 'package:rgl':
-##
-## wire3d
-## The following objects are masked from 'package:base':
-##
-## intersect, setdiff, union
+library(nat)
## Loading required package: rgl
+## Registered S3 method overwritten by 'nat':
+## method from
+## as.mesh3d.ashape3d rgl
+##
+## Attaching package: 'nat'
+## The following object is masked from 'package:rgl':
+##
+## wire3d
+## The following objects are masked from 'package:base':
+##
+## intersect, setdiff, union
One of the key tools for geometric work in nat is the xyzmatrix
function, which extracts 3-D coordinate information from any object containing vertices.
## X Y Z
-## Min. :186.9 Min. : 90.36 Min. : 88.2
-## 1st Qu.:225.6 1st Qu.: 97.56 1st Qu.:103.4
-## Median :258.4 Median :102.70 Median :112.9
-## Mean :249.4 Mean :104.03 Mean :120.9
-## 3rd Qu.:277.7 3rd Qu.:109.04 3rd Qu.:139.0
-## Max. :289.5 Max. :132.71 Max. :157.3
+summary(xyz)## X Y Z
+## Min. :186.9 Min. : 90.36 Min. : 88.2
+## 1st Qu.:225.6 1st Qu.: 97.56 1st Qu.:103.4
+## Median :258.4 Median :102.70 Median :112.9
+## Mean :249.4 Mean :104.03 Mean :120.9
+## 3rd Qu.:277.7 3rd Qu.:109.04 3rd Qu.:139.0
+## Max. :289.5 Max. :132.71 Max. :157.3
+plot(xyz[,c("X","Y")], type='p')
This also works for neuronlists, so we can extract all of the points in a collection of neurons:
xyz=xyzmatrix(Cell07PNs)
We could ask for all the points close to a specific X coordinate
-## close_to_x250
-## FALSE TRUE
-## 20479 1728
-We can also select points interactively by using the rgl::select3d
function.
close_to_x250=abs(xyz[,'X']-250)<10
+table(close_to_x250)
## close_to_x250
+## FALSE TRUE
+## 20479 1728
+We can also select points interactively by using the rgl::select3d
function.
As a worked example let’s try to find the plane cutting a tract defined by the axons of some example neurons:
-plot(Cell07PNs, WithNodes=F)
+plot(Cell07PNs, WithNodes=F)
dist=10
-abline(v=250, col='red')
-abline(v=c(250-dist, 250+dist), col='red', lty='dotted')
We could ask for all the points close to a specific X coordinate
-## close_to_x250
-## FALSE TRUE
-## 20479 1728
+close_to_x250=abs(xyz[,'X']-250)<10
+table(close_to_x250)
## close_to_x250
+## FALSE TRUE
+## 20479 1728
Let’s find the centroid of those selected points:
-## X Y Z
-## 251.16788 94.76735 141.11495
+## X Y Z
+## 251.16788 94.76735 141.11495
+plot(Cell07PNs, WithNodes=F)
+points(matrix(centroid[1:2],ncol=2), pch=20)
Now let’s do a principal components analysis on those points
-pc=prcomp(xyz[close_to_x250,])
+pc=prcomp(xyz[close_to_x250,])
pc1=pc$rotation[,'PC1']
-plot(Cell07PNs, WithNodes=F)
-points(matrix(centroid[1:2],ncol=2), pch=20)
-res=rbind(centroid-pc1*10, centroid, centroid+pc1*10)
-lines(res[,1:2])
OK, perhaps it would be better if we only used the spine of the neurons
# There is a problem with one neuron with a loop, hence OmitFailures
spines=nlapply(Cell07PNs, spine, UseStartPoint=T, OmitFailures = T)
## Warning in get.shortest.paths(ng, from = from, to = to, mode = "all"): At
-## structural_properties.c:4597 :Couldn't reach some vertices
+## Warning in get.shortest.paths(ng, from = from, to = to, mode = "all"): At
+## structural_properties.c:4745 :Couldn't reach some vertices
-## close_to_x250
-## FALSE TRUE
-## 5137 876
+close_to_x250=abs(xyz[,'X']-250)<10
+table(close_to_x250)## close_to_x250
+## FALSE TRUE
+## 5137 876
-pc=prcomp(xyz[close_to_x250,])
+pc=prcomp(xyz[close_to_x250,])
pc1=pc$rotation[,'PC1']
-plot(spines, WithNodes=F)
-points(matrix(centroid[1:2],ncol=2), pch=20)
-res=rbind(centroid-pc1*10, centroid, centroid+pc1*10)
+plot(spines, WithNodes=F)
+points(matrix(centroid[1:2],ncol=2), pch=20)
+res=rbind(centroid-pc1*10, centroid, centroid+pc1*10)
# nb 1:2 => just the xy coords
-lines(res[,1:2])
Alternatively, we could find the vector of the first PC for each neuron. Let’s write a function to do that and then apply it to the spine of each neuron.
# returns 6 vector
@@ -246,39 +248,39 @@
# second three values first principal component
tract_vector <- function(n, xval=250, thresh=10) {
p=xyzmatrix(n)
- near=abs(p[,'X']-xval)<thresh
- pc=prcomp(p[near,])
- c(colMeans(p[near,]), pc$rotation[,'PC1'])
+ near=abs(p[,'X']-xval)<thresh
+ pc=prcomp(p[near,])
+ c(colMeans(p[near,]), pc$rotation[,'PC1'])
}
-tvs=sapply(spines, tract_vector)
-mean_cent=rowMeans(tvs[1:3,])
-mean_vec=rowMeans(tvs[4:6,])
+tvs=sapply(spines, tract_vector)
+mean_cent=rowMeans(tvs[1:3,])
+mean_vec=rowMeans(tvs[4:6,])
# nb *10 to make the vector longer (10 µm) and more visible
-res2=rbind(mean_cent-mean_vec*10, mean_cent, mean_cent+mean_vec*10)
-plot(spines, col='grey', WithNodes=F)
-lines(res2[,1:2], lwd=3)
We can look at the plane we have defined in a 3D context as follows:
plc=plane_coefficients(mean_cent, mean_vec)
-plot3d(Cell07PNs[c(1,30)], col='grey', WithNodes = F)
-planes3d(plc[,1:3], d=plc[,'d'])
We can also make a small square plane centred on the chosen point
-library(rgl)
-clear3d()
+library(rgl)
+clear3d()
make_centred_plane <- function(point, normal, scale = 1) {
# find the two orthogonal vectors to this one
- uv = Morpho::tangentPlane(normal)
- uv = sapply(uv, "*", scale, simplify = F)
- qmesh3d(
- cbind(
+ uv = Morpho::tangentPlane(normal)
+ uv = sapply(uv, "*", scale, simplify = F)
+ qmesh3d(
+ cbind(
point + uv$z,
point + uv$y,
point - uv$z,
@@ -290,34 +292,34 @@
}
plane=make_centred_plane(mean_cent, mean_vec, scale=15)
plot3d(spines, col='grey')
-shade3d(plane, col='red')
Finally, we can find the positions at which each neuron intersects the plane. Note that when there are multiple intersections, we only choose the closest point to the centroid that we calculated when defining the plane.
-intersections=t(sapply(Cell07PNs, intersect_plane, plc, closestpoint=mean_cent))
+intersections=t(sapply(Cell07PNs, intersect_plane, plc, closestpoint=mean_cent))
# center those intersection points
intersections.cent=scale(intersections, center = T, scale = F)
-d=sqrt(rowSums(intersections.cent^2))
-mean(d)
## [1] 3.118692
+d=sqrt(rowSums(intersections.cent^2))
+mean(d)## [1] 3.118692
Then we can plot those positions on the plane
-spheres3d(intersections, col='red', rad=.5)
-shade3d(plane, col='black')
+spheres3d(intersections, col='red', rad=.5)
+shade3d(plane, col='black')
plot3d(spines, col='grey')
Finally we can construct a 2D coordinate system on the plane and project the intersection positions onto that.
+ +Finally we can construct a 2D coordinate system on the plane and project the intersection positions onto that.
# find pair of orthogonal tangent vectors of plane
-uv = Morpho::tangentPlane(mean_vec)
+uv = Morpho::tangentPlane(mean_vec)
# centre our points on mean
sp=scale(intersections, scale = F, center=T)
-DotProduct=function(a,b) sum(a*b)
+DotProduct=function(a,b) sum(a*b)
# find coordinates w.r.t. to our two basis vectors
-xy=data.frame(u=apply(sp, 1, DotProduct, uv[[1]]),
- v=apply(sp, 1, DotProduct, uv[[2]]))
+xy=data.frame(u=apply(sp, 1, DotProduct, uv[[1]]),
+ v=apply(sp, 1, DotProduct, uv[[2]]))
# maintain consist x-y aspect ratio
-plot(xy, pch=19, asp=1, main = "Position of Axon intersection in plane",
+plot(xy, pch=19, asp=1, main = "Position of Axon intersection in plane",
xlab="u /µm", ylab="v /µm")
Developed by Gregory Jefferis, James Manton, Sridhar Jagannathan.
+ +Developed by Gregory Jefferis, James Manton, Sridhar Jagannathan.