GitBook: [master] 53 pages modified

adamltyson · gitbook-bot · commit b7d73b6f8fc0 · 2020-07-14T12:55:04.000Z
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -55,10 +55,7 @@
 * [Introduction](brainreg/introduction.md)
 * [Installation](brainreg/installation.md)
 * [User guide](brainreg/getting-started/README.md)
-  * [Image orientation](brainreg/getting-started/image-orientation.md)
   * [Registration parameters](brainreg/getting-started/registration-parameters.md)
-* [Downloading files](brainreg/downloading-files.md)
-
 
 ## neuro
 
@@ -96,4 +93,5 @@
 * [cellfinder](https://github.com/SainsburyWellcomeCentre/cellfinder)
 * [amap](https://github.com/SainsburyWellcomeCentre/amap-python)
 * [neuro](https://github.com/SainsburyWellcomeCentre/neuro)
+* [brainreg](https://github.com/brainglobe/brainreg)
 
diff --git a/amap/installation.md b/amap/installation.md
@@ -48,7 +48,7 @@ Remember to activate your conda environment before doing anything
 pip install amap
 ```
 
-## Download atlas and trained classification models \(optional\)
+## Download atlas \(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.
 
diff --git a/brainreg/getting-started/README.md b/brainreg/getting-started/README.md
@@ -7,17 +7,17 @@ description: How to register your data to the template
 ## Basic usage
 
 ```bash
-amap /path/to/raw/data /path/to/output/directory -x 2 -y 2 -z 5
+brainreg /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`
+Full command-line arguments are available with `brainreg -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.
+If you have any spaces in your file-path, please enclose it in quotation marks, otherwise brainreg will interpret it as two inputs, separated by a space.
 
-**i.e. `"/path/to/my data"` not `path/to/my data`.** 
+**i.e. `"/path/to/my data"` not `path/to/my data`.**
 {% endhint %}
 
 ## Arguments
@@ -34,28 +34,50 @@ You must also specify the pixel sizes, see [Specifying pixel size](../../user-gu
 ### 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.
 
+### Atlas
+
+By default, brainreg will use the 25um version of the [Allen Mouse Brain Atlas](https://mouse.brain-map.org/). To use another atlas \(e.g. for another species, or another resolution\), you must use the `--atlas` flag, followed by the string describing the atlas, e.g.:
+
+```bash
+--atlas allen_mouse_50um
+```
+
+{% hint style="info" %}
+To find out which atlases are available, once brainreg is installed, please run `brainglobe list`. The name of the resulting atlases is the string to pass with the `--atlas` flag.
+{% endhint %}
+
+### Registration backend
+
+To change the registration algorithm used, use the `--backend` flag. The default is `niftyreg` as that is currently the only option.
+
 ### 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
+If your data does not match the [brainglobe](https://github.com/brainglobe) default orientation \(the origin voxel is the most anterior, superior, left-most voxel, then you must specify the orientation by using the `--orientation` flag. What follows must be a string in the [bg-space](https://github.com/brainglobe/bg-space) "initials" form, to describe the origin voxel.
 
-### Registration options
+{% hint style="info" %}
+When you work with a stack, the origin is the upper left corner when you show the first element `stack[0, :, :]` with matplotlib or when you open the stack with ImageJ. First dimension is the one that you are slicing, the second the height of the image, and the third the width of the image.
+{% endhint %}
 
-To change how the actual registration performs, see [Registration parameters](registration-parameters.md)
+If the origin of your data \(first, top left voxel\) is the most posterior, superior, left part of the brain, then the orientation string would be "psl" \(posterior, superior, left\), and you would use:
 
-### Visualisation options
+```bash
+--orientation psl
+```
 
-* `--no-boundaries` Do not precompute the outline images \(if you don't want to use `amap_vis`\)
+{% hint style="warning" %}
+The order of the three initials must be the same as the axis order \(sliced plane, height, width\)
+{% endhint %}
+
+### Registration options
+
+To change how the actual registration performs, see [Registration parameters](registration-parameters.md)
 
-## Visualisation
 
-To visualise your data, please see [Visualisation](../../user-guide/visualisation.md)
 
diff --git a/brainreg/getting-started/registration-parameters.md b/brainreg/getting-started/registration-parameters.md
@@ -4,14 +4,18 @@ 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):
+To change how the image registration performs, you can change the options that are passed to the registration backend.
 
-### **Affine registration**
+## NiftyReg
+
+If using the [NiftyReg](http://cmictig.cs.ucl.ac.uk/wiki/index.php/NiftyReg) backend, the following options can be changed:
+
+#### **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 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**
diff --git a/brainreg/installation.md b/brainreg/installation.md
@@ -1,21 +1,15 @@
 ---
-description: Installing amap
+description: Installing brainreg
 ---
 
 # 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
+pip install brainreg
 ```
 
 {% hint style="info" %}
@@ -24,31 +18,31 @@ If you're not completely sure what you're doing, read on.
 
 ## 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.
+The hardware requirements for brainreg depend on the atlas \(and in particular the resolution\) you want to use. Most machines \(including laptops\) will be able to use most of the atlases, but some atlases \(such as the 10um mouse atlases\) may need up to 32GB of RAM.
+
+Currently brainreg works on Windows and Linux. macOS support is experimental.
 
 ## 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**. 
+brainreg 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.** 
+**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.
+brainreg 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
+## Installing brainreg
 
 {% hint style="info" %}
 Remember to activate your conda environment before doing anything
 {% endhint %}
 
 ```bash
-pip install amap
+pip install brainreg
 ```
 
-## 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.
 
diff --git a/brainreg/introduction.md b/brainreg/introduction.md
@@ -1,29 +1,25 @@
 # 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).
+brainreg is an update to [amap](https://github.com/SainsburyWellcomeCentre/amap-python) \(itself a port of the [original Java software](https://www.nature.com/articles/ncomms11879)\) to include multiple registration backends, and to support the many atlases provided by [bg-atlasapi](https://github.com/brainglobe/bg-atlasapi).
 
-The actual registration is carried out by [NiftyReg](http://cmictig.cs.ucl.ac.uk/wiki/index.php/NiftyReg).
+Currently the only registration backend is [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.
+The aim of brainreg 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).  
+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
+pip install brainreg
 ```
 
 {% hint style="info" %}
@@ -33,14 +29,10 @@ For detailed instructions see [Installation](installation.md)
 ## Usage
 
 ```bash
-amap /path/to/raw/data /path/to/output/directory -x 2 -y 2 -z 5
+brainreg /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 %}
 
-### 
-
-
-
