quick-start.Rmd

---
title: "Quick-start guide"
author: "Gregory Jefferis"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    fig_width: 7
    fig_height: 5
vignette: >
  %\VignetteIndexEntry{Quick-start guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Quick-start guide
Data for various neurons can be downloaded from flybrain.mrc-lmb.cam.ac.uk and analysed using this package. The data include information on the location of the neurons in 3D space, details on innervation in different neuropils, and NBLAST scores. This quick-start guide is designed to give a brief examples of a subset of the analyses that can be carried out using this package, using an example dataset of 20 Kenyon cells.

## Set up environment
```{r setup, message=FALSE, warning=FALSE}
# Allow production of figures using RGL
library(knitr)
library(rgl)
rgl::setupKnitr()
```

### Load flycircuit and nat (NeuronAnatomy Toolbox) packages
```{r load-flycircuit}
library(flycircuit)
library(nat)
library(nat.nblast)
```

### Typical startup
In regular use in the Jefferis lab, we use the code available at 
https://gist.github.com/jefferis/bbaf5d53353b3944c090 to set things up to use
our processed version of the  complete [flycircuit.tw](http://flycircuit.tw) 
dataset. This results in a one-off 2GB all by all 
NBLAST score matrix being downloaded from our website. Neurons (up to 1.3 Gb)
will be downloaded when they are referenced.

```{r, eval=FALSE}
devtools::source_gist("bbaf5d53353b3944c090")
```

However for this simple tutorial we will use a smaller dataset of 20 neurons for
which demonstration data is shipped with the *nat* and *flycircuit* packages.

### Package options
By default, any remote data will be downloaded to a subdirectory of the user 
data directory (this is identified by the *rappdirs* package). On this machine
this is `r getOption('flycircuit.datadir')`. This location should be the same
for all R sessions so that data is shared across sessions (avoiding repeated 
downloads).

If you wish to save data to a different location then this can be set using: 
```{r package-options, eval=FALSE}
options(flycircuit.datadir = '/my/favourite/directory')
```
**before** loading the flycicruit package.

## Plot Kenyon cells
Morphological data for 20 Kenyon cells are distributed with the *nat* package. 
We can plot these 20 neurons and see where they are located in the brain:
```{r plot-kcs, rgl=TRUE, dev='png'}
# set default view to frontal
r3dDefaults$userMatrix=structure(c(1, 0, 0, 0, 0, -1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 1),
                                 .Dim = c(4L, 4L))
open3d()
plot3dfc(names(kcs20), db=kcs20)
fcwbsurf()
```

We'll be plotting these Kenyon cells a lot, so let's set an option that will save us some typing:
```{r option-set}
options(nat.default.neuronlist = 'kcs20')
```

## Inspect Kenyon cell NBLAST scores
The package comes with some sample NBLAST scores for a set of 20 Kenyon cells.
Each score is a pairwise comparison between two neurons. The score is asymmetric
i.e. S(A,B)!=S(B,A). See ?kcs20scores for details.

The scores were computed as follows:
```{r compute-scores, eval=FALSE}
kcs20scores=nblast_allbyall(kcs20)
```


Show the scores for the first five neurons:
```{r score-peek}
kcs20scores[1:5, 1:5]
```

## Plotting NBLAST hits
Let's plot the two neurons that NBLAST thinks are most similar.

Find the indices of the maximum off-diagonal score in the score matrix:
```{r top-hits}
# find the maximum off-diagonal (i.e. non-self match)
max_realmatch=max(kcs20scores[upper.tri(kcs20scores,diag=F)])
ind<-which(kcs20scores==max_realmatch,arr.ind=T)
queryneuron <- colnames(kcs20scores)[ind[2]]
targetneuron <- rownames(kcs20scores)[ind[1]]
```
What was the query?
```{r query}
queryneuron
```

What was the target?
```{r target}
targetneuron
```

What do they look like and where in the brain are they?
```{r plot-top-hits, rgl=TRUE, dev='png'}
clear3d()
plot3dfc(c(queryneuron, targetneuron), db=kcs20)
fcwbsurf()
```
Look like a pair of alpha/beta core Kenyon cells.

## Cluster Kenyon cells by morphology
```{r cluster-kcs}
# nb this works because options(flycircuit.scoremat="kcs20scores")
# can also set the score matrix to use explicitly
# hckc <- hclustfc(rownames(kcs20scores), scoremat=kcs20scores)
hckc <- hclustfc(rownames(kcs20scores))
library(dendroextras)
par(mar=c(12, 4, 2, 2))   # Extra margin for labels
plot(colour_clusters(hckc, k=3))
```

Now let's look at the neurons:

```{r rgl-cluster-kcs, rgl=TRUE, dev='png'}
clear3d()
plot3d(hckc, k=3, db=kcs20)
```
Good, we can see the 3 main classes (gamma, alpha'/beta' and alpha/beta).

## More NBLASTing
We know that `r queryneuron` and `r targetneuron` are the two most similar neurons in our subset of 20 Kenyon cells, but how do other neurons compare with `r queryneuron`? Let's NBLAST it against all the other neurons and look at the scores.
```{r blasting}
results <- fc_nblast(queryneuron, names(kcs20), 'kcs20scores')
par(las=2)                # Horizontal labels
par(mar=c(5, 14, 2, 2))   # Extra margin for labels
barplot(results, horiz=T)
```
Unsurprisingly, `r queryneuron` itself has the highest score (seeing as it is exactly the same as itself). Interestingly, while `r targetneuron` has the second-highest score, `r names(sort(results, decreasing=TRUE)[3])` has a similarly high score, closely followed by `r paste0(names(sort(results, decreasing=TRUE)[4:5]), collapse=' and ')`. Let's plot them all, with the query neuron in black, to see how similar they are:
```{r plot-good-hits, rgl=TRUE, dev='png'}
clear3d()
plot3d(queryneuron, col='black')
plot3dfc(names(sort(results,decreasing=TRUE)[2:5]))
```
Hmm, they look pretty similar. Let's plot the four worst hits for comparison:
```{r plot-bad-hits, rgl=TRUE, dev='png'}
clear3d()
plot3d(queryneuron, col='black')
plot3dfc(names(sort(results)[1:4]))
```
Definitely different.