README.rmd

---
output: github_document
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(knitr)
library(memoise)
library(dplyr)
# listGenes = memoise(listGenes)
# genes = listGenes()
# saveRDS(listGenes,'listGenes.rds')
devtools::load_all()
listGenes = readRDS('listGenes.rds')
dir.create('README_files',showWarnings = FALSE)
```

Table of Contents
=================

   * [allenBrain](#allenbrain)
      * [Example usage](#example-usage)                                                                                                            
         * [Image acquisition](#image-acquisition)                                                                                                 
         * [Region expression data](#region-expression-data)                                                                                       
         * [Incomplete stuff](#incomplete-stuff)   

# allenBrain

This R package acquires pictures from Allen Brain Atlas.

Install allenBrain to R
``` r
devtools::install_github('oganm/allenBrain')
```

## Example usage

### Image acquisition

You can use `downloadImage` and `downloadAtlas` functions to get images. Output of these functions are `magick-image` objects

``` {r}
library(dplyr)


# get a list of structure names and ids
IDs = getStructureIDs()
IDs %>% head
```

```{r, results = FALSE}
# get the id of the desired region
granuleID = IDs['Dentate gyrus, granule cell layer' == IDs$name,]$id

# get the dataset for the desired gene (the first saggital experiment that did not fail)
datasetID = getGeneDatasets(gene = 'Prox1',
                            planeOfSection = 'sagittal',
                            probeOrientation = 'antisense')[1]


# get the slide that has the desired brain region and coordinates of the center of the region
imageID = structureToImage(datasetID = datasetID, regionIDs = granuleID)

# get the closest atlas image. 
atlasID = imageToAtlas(imageID$section.image.id,imageID$x,imageID$y,planeOfSection ='sagittal')

# decide how much to you wish to downsample
downsample = 2

# download the slide
downloadImage(imageID = imageID$section.image.id, 
             view = 'projection',
             outputFile = 'README_files/image.jpg',
             downsample = downsample)
```
![](README_files/image.jpg)

```{r, results = FALSE}
# download the atlas
downloadAtlas(imageID = atlasID$section.image.id, 
             outputFile = 'README_files/atlas.jpg',
             downsample = downsample)
```
![](README_files/atlas.jpg)

Images can be centered by providing center coordinates of a brain region. Input is either a file path or a `magick-image` object
```{r,results=FALSE}
# crop the slide so that the desired brain region is in the center
centerImage(image = 'README_files/image.jpg', 
            x = imageID$x,
            y= imageID$y,
            xProportions = c(.1,.1),
            yProportions =c(.1,.1),
            outputFile = 'README_files/cropped.jpg',
            downsample = downsample)
```

![](README_files/cropped.jpg)

```{r,results = FALSE}
centerImage(image = 'README_files/atlas.jpg', 
            x = atlasID['x'],
            y= atlasID['y'],
            xProportions = c(.1,.1),
            yProportions =c(.1,.1),
            outputFile = 'README_files/croppedAtlas.jpg',
            downsample = downsample)
```
![](README_files/croppedAtlas.jpg)

### Adding a scale to the image

`getSectionImage` function returns all available information about an image. We can
use this to access the resolution information which lists micron/pixel ratio 
in a given image.
```{r}
(image_res = getSectionImage(imageID$section.image.id)$resolution)
```
We can then use the `add_scale` function to add a scale

```{r}
downloadImage(imageID = imageID$section.image.id, 
             view = 'projection',
             downsample = downsample) %>% 
    centerImage(x = imageID$x,
            y= imageID$y,
            xProportions = c(.1,.1),
            yProportions =c(.1,.1),
            outputFile = 'README_files/cropped.jpg',
            downsample = downsample) %>% 
    add_scale(image_res,downsample)
```


### Image syncronization

You can get closest points of other slides from the same dataset to get other slides depicting the region

```{r, results=FALSE}

# gel all images for Prox1 experiment
allImages = listImages(datasetID)  %>% arrange(as.numeric(`section.number`))

# get coordinates that are closest to the center of the brain region
closeSections = imageToImage2D(imageID$section.image.id,imageID$x,imageID$y,allImages$id)

# download and crop them all
croppedImage = closeSections %>% apply(1,function(x){
    # download and crop the images
    image = downloadImage(imageID = x['section.image.id'], 
             view = 'projection',
             # outputFile = file.path('README_files/allProx1',x['section.image.id']),
             downsample = downsample)
    
    centerImage(image = image, 
            x = x['x'],
            y= x['y'],
            xProportions = c(.1,.1),
            yProportions =c(.1,.1),
            # outputFile = file.path('README_files/allProx1',x['section.image.id']),
            downsample = downsample)
}) %>% do.call(c,.)

# some magick
animation = magick::image_animate(croppedImage, fps = 1)
magick::image_write(animation, "README_files/Prox1.gif")

```

![](README_files/Prox1.gif)



### Region expression data

Region expression can be acquired by datasetID. Data displayed in ABA web portals is expression.energy.

```{r}
head(getStructureExpressions(datasetID))
```

If you want to get all genes, use `listGenes` to get all available genes for the species. Then do `getGeneDatasets`.

```{r}
genes = listGenes()

geneDatasets = genes$acronym[1:10] %>% lapply(getGeneDatasets)
```

You may want to limit your search space as getting the data for all genes is a slow process.

### Incomplete stuff


Grid data of a dataset can be downloaded by `gridData` function
```{r,eval= FALSE}
gridData(datasetID = datasetID,
         outputFile ='README_files/Prox1_data.zip',
         include = c('energy','density','intensity'))
unzip(zipfile = 'README_files/Prox1_data.zip',exdir = "README_files")
```