brainreg docs

Author: adamltyson

brainreg/downloading-files.md

@@ -0,0 +1,30 @@
+---
+description: Downloading the files that amap needs for registration
+---
+
+# Downloading files
+
+## D**ownload atlas \(optional\)**
+
+When amap runs, the appropriate reference atlas will be downloaded \(if not previously done so\). If you would like to download in advance to save time \(or if you will not have an internet connection\) please use `amap_download`.
+
+Currently, the only supported atlas is the Allen reference mouse brain, originally from [here](http://help.brain-map.org/display/mouseconnectivity/API#API-DownloadAtlas). The atlas will download into `./amap/atlas`.
+
+In the future, other atlases will be available, and you will be able to choose which is downloaded.
+
+If you want to modify the am amap download, use:
+
+* `--atlas-install-path` Supply a path to download the atlas elsewhere. This 
+
+  should also update the default `registration.conf` file so that the correct 
+
+  atlas is sourced. Alternatively, use this command to tell amap where an 
+
+  existing atlas is, to save it being downloaded twice. \(Requires 20GB 
+
+  disk space\)
+
+* `--atlas download path` The path to download the atlas into. 
+
+  \(Requires 1.2GB disk space\). Defaults to `/tmp`.
+

brainreg/getting-started/README.md

@@ -0,0 +1,61 @@
+---
+description: How to register your data to the template
+---
+
+# User guide
+
+## Basic usage
+
+```bash
+amap /path/to/raw/data /path/to/output/directory -x 2 -y 2 -z 5
+```
+
+{% hint style="info" %}
+Full command-line arguments are available with `amap -h`
+{% endhint %}
+
+{% hint style="warning" %}
+If you have any spaces in your file-path, please enclose it in quotation marks, otherwise amap will interpret it as two inputs, separated by a space.
+
+**i.e. `"/path/to/my data"` not `path/to/my data`.** 
+{% endhint %}
+
+## Arguments
+
+### Mandatory
+
+* Path to the directory of the images. \(Can also be a text file pointing to the files\)
+* Output directory for all intermediate and final results
+
+{% hint style="warning" %}
+You must also specify the pixel sizes, see [Specifying pixel size](../../user-guide/usage/specifying-pixel-size.md)
+{% endhint %}
+
+### Additional options
+
+* `-d` or `--downsample` Paths to N additional channels to downsample to the same coordinate space.
+* `--no-save-downsampled` Don't save the downsampled brain before filtering.
+* `--registration-config` To supply your own, custom registration configuration file
+* `--sort-input-file` If set to true, the input text file will be sorted using natural sorting. This means that the file paths will be sorted as would be expected by a human and not purely alphabetically
+
+#### Misc options
+
+* `--n-free-cpus` The number of CPU cores on the machine to leave unused by the program to spare resources.
+* `--debug` Debug mode. Will increase verbosity of logging and save all intermediate files for diagnosis of software issues.
+
+### Input data orientation
+
+If your data does not match the NifTI standard orientation \(origin is the most ventral, posterior, left voxel\), then please see [Image orientation](image-orientation.md) to reorient the atlas
+
+### Registration options
+
+To change how the actual registration performs, see [Registration parameters](registration-parameters.md)
+
+### Visualisation options
+
+* `--no-boundaries` Do not precompute the outline images \(if you don't want to use `amap_vis`\)
+
+## Visualisation
+
+To visualise your data, please see [Visualisation](../../user-guide/visualisation.md)
+

brainreg/getting-started/image-orientation.md

@@ -0,0 +1,29 @@
+---
+description: Telling amap which way round your images are
+---
+
+# Image orientation
+
+**If the supplied data does not match the NifTI standard orientation \(origin is the most ventral, posterior, left voxel\), then the atlas can be reoriented to match:**
+
+* `--flip-x` Flip the sample brain along the first dimension
+* `--flip-y` Flip the sample brain along the second dimension
+* `--flip-z` Flip the sample brain along the third dimension
+* `--orientation` The orientation of the sample brain `coronal`, `saggital`or `horizontal`
+
+\`\`
+
+**If your data isn't in a standard \(i.e. anatomical orientation\), and needs to be rotated, you can use the `--rotation` flag**  
+ What follows the `--rotation` flag, must be a string in the format `xIyJzK`, where x, y & z are the axes to rotate around, and I, J & K are the number of 90 degree rotations for the respective axes.  The direction of the rotation is: 
+
+* For a rotation around X, the rotation is from the Y axis to Z
+* For a rotation around Y, the rotation is from the X axis to Z
+* For a rotation around Z, the rotation is from the X axis to Y
+
+For example:
+
+* `x0y0z3` would rotate around the Z axis 90 degrees clockwise \(i.e. 270 degrees anticlockwise\)
+* `x0y0z0` would not rotate the image \(default\)
+
+
+

brainreg/getting-started/registration-parameters.md

@@ -0,0 +1,24 @@
+---
+description: How to refine the registration to the template image
+---
+
+# Registration parameters
+
+To change how the image registration performs, you can change the options that are passed to [NiftyReg](http://cmictig.cs.ucl.ac.uk/wiki/index.php/NiftyReg):
+
+### **Affine registration**
+
+* `--affine-n-steps` Registration starts with further downsampled versions of the original data to optimize the global fit of the result and prevent "getting stuck" in local minima of the similarity function. This parameter determines how many downsampling steps are being performed, with each step halving the data size along each dimension. **Default: 6**
+* `--affine-use-n-steps` Determines how many of the downsampling steps defined by `-affine-n-steps` will have their registration computed. The combination `--affine-n-steps 3 --affine-use-n-steps 2` will e.g. calculate 3 downsampled steps, each of which is half the size of the previous one but only perform the registration on the 2 smallest resampling steps, skipping the full resolution data.  Can be used to save time if running the full resolution doesn't result in noticeable improvements. **Default: 5**
+
+### **Freeform registration**
+
+* `--freeform-n-steps` Registration starts with further downsampled versions of the original data to optimize the global fit of the result and prevent "getting stuck" in local minima of the similarity function. This parameter determines how many downsampling steps are being performed, with each step halving the data size along each dimension. **Default: 6**
+* `--freeform-use-n-steps` Determines how many of the downsampling steps defined by `--freeform-n-steps` will have their registration computed. The combination `--freeform-n-steps 3 --freeform-use-n-steps 2` will e.g. calculate 3 downsampled steps, each of which is half the size of the previous one but only perform the registration on the 2 smallest resampling steps, skipping the full resolution data. Can be used to save time if running the full resolution doesn't result in noticeable improvements. **Default: 4**
+* `--bending-energy-weight` Sets the bending energy, which is the coefficient of the penalty term, preventing the freeform registration from over-fitting. The range is between 0 and 1 \(exclusive\) with higher values leading to more restriction of the registration. **Default: 0.95**
+* `--grid-spacing` Sets the control point grid spacing in x, y & z. Positive values are interpreted as real values in mm, negative values are interpreted as the \(positive\) distances in voxels. Smaller grid spacing allows for more local deformations but increases the risk of over-fitting. **Default: -10**
+* `--smoothing-sigma-floating` Adds a Gaussian smoothing to the floating image \(the one being registered\), with the sigma defined by the number. Positive values are interpreted as real values in mm, negative values are interpreted as distance in voxels. **Default: 1.0**
+* `--smoothing-sigma-reference` Adds a Gaussian smoothing to the reference \(the one being registered to\) image, with the sigma defined by the number. Positive values are interpreted as real values in mm, negative values are interpreted as distance in voxels. **Default: 1.0**
+* `--histogram-n-bins-floating` Number of bins used for the generation of the histograms used for the calculation of Normalized Mutual Information on the floating image. **Default: 128**
+* `--histogram-n-bins-reference` Number of bins used for the generation of the histograms used for the calculation of Normalized Mutual Information on the reference image. **Default: 128**
+

brainreg/installation.md

@@ -0,0 +1,54 @@
+---
+description: Installing amap
+---
+
+# Installation
+
+{% hint style="warning" %}
+If you already have cellfinder, then amap has been installed for you.
+{% endhint %}
+
+## Introduction
+
+amap is included with cellfinder. Unless you have a particular reason not to, I would install cellfinder as this will install all the packages you may need. See [cellfinder installation](../installation/installation.md).
+
+If you know what you're doing just run:
+
+```bash
+pip install amap
+```
+
+{% hint style="info" %}
+If you're not completely sure what you're doing, read on.
+{% endhint %}
+
+## Requirements
+
+To run amap you will need a fairly high-powered computer running Windows or Linux  \(see [system requirements](../installation/system-requirements.md) for details\). In particular, to use some of the atlases, you may need at least 32GB of RAM.
+
+## Setting up your machine
+
+### Installing Python
+
+amap is written in Python, and so needs a functional Python installation. Your machine may already have Python installed, but **I recommend installing miniconda**. 
+
+**See** [**Using conda**](../installation/using-conda.md) **for details.** 
+
+{% hint style="danger" %}
+amap should run on any type of Python installation, but if you don't use conda, I may not be able to help you.
+{% endhint %}
+
+## Installing amap
+
+{% hint style="info" %}
+Remember to activate your conda environment before doing anything
+{% endhint %}
+
+```bash
+pip install amap
+```
+
+## Download atlas and trained classification models \(optional\)
+
+When you run amap, it will download the files it needs \(e.g. the atlas\). If you want to save time later, or you know you won't have an internet connection when you run amap you can download these in advance. See [downloading files](downloading-files.md) for details.
+

brainreg/introduction.md

@@ -0,0 +1,46 @@
+# Introduction
+
+{% hint style="info" %}
+amap is included with cellfinder, and exists as a standalone tool if you do not need the cell detection part
+{% endhint %}
+
+## About
+
+amap is the part of cellfinder that takes care of image registration and atlas-based segmentation. It is a Python port of [aMAP](https://github.com/SainsburyWellcomeCentre/aMAP/wiki) \(originally written in Java\), which has been [validated against human segmentation](https://www.nature.com/articles/ncomms11879).
+
+The actual registration is carried out by [NiftyReg](http://cmictig.cs.ucl.ac.uk/wiki/index.php/NiftyReg).
+
+## Details
+
+The aim of amap is to register the template brain \(e.g. from the [Allen Reference Atlas](https://mouse.brain-map.org/static/atlas)\) to the sample image. Once this is complete, any other image in the template space can be aligned with the sample \(such as region annotations, for segmentation of the sample image\). The template to sample transformation can also be inverted, allowing sample images to be aligned in a common coordinate space.
+
+To do this, the template and sample images are filtered, and then registered in a three step process \(reorientation, affine registration, and freeform registration.\) The resulting transform from template to standard space is then applied to the atlas.
+
+Full details of the process are in the [original paper](https://www.nature.com/articles/ncomms11879).  
+
+![Overview of the registration process](https://raw.githubusercontent.com/SainsburyWellcomeCentre/amap-python/master/resources/reg_process.png)
+
+## Installation
+
+```bash
+pip install amap
+```
+
+{% hint style="info" %}
+For detailed instructions see [Installation](installation.md)
+{% endhint %}
+
+## Usage
+
+```bash
+amap /path/to/raw/data /path/to/output/directory -x 2 -y 2 -z 5
+```
+
+{% hint style="info" %}
+For more information see [Getting started](getting-started/)
+{% endhint %}
+
+### 
+
+
+