Merge pull request #79 from brainglobe/brainreg-update

V1 updates for `brainreg` changes

docs/source/blog/index.md

@@ -6,5 +6,4 @@
 :date: "%Y-%m-%d"
 :format: "({date}) {title}, by {author}"
 :excerpts:
-:sort:
 ```

docs/source/blog/version1/brainreg_update_live.md

@@ -0,0 +1,35 @@
+---
+blogpost: true
+date: Nov 1, 2023
+author: Will Graham
+location: London, England
+category: BrainGlobe-v1
+language: English
+---
+
+# Version 1 of `brainreg` and `brainglobe-segmentation` released
+
+The [restructuring of BrainGlobe](./version_1_announcement.md) is underway, beginning with the release of version 1 of `brainreg` and `brainglobe-segmentation` (previously known as `brainreg-segment`).
+Previously, there were three tools with the prefix `brainreg` ("brain registration") that were split across three packages:
+
+- `brainreg` was the core Python package that contained the functional code for performing registration of an atlas to a sample image (sequence).
+- `brainreg-napari` provided a plugin to perform the registration steps interactively through napari. It depended on `brainreg` for the core functionality.
+- `brainreg-segment` was a companion to `brainreg` that allowed for manual segmentation of regions/objects within the brain. However it was not necessarily involved with the registration process itself.
+
+This release sees `brainreg` come bundled with its napari plugin as an optional package extra, rather than requiring users to install the two packages separately.
+Consequentially, `brainreg-napari` has been retired; we recommend you uninstall this package from your environments when you update.
+The "combined" `brainreg` is now tagged as `brainreg v1.0.0` and should be considered a stable first release of this tool.
+
+`brainglobe-segmentation` is the new name of the `brainreg-segment` tool.
+With the forthcoming release of BrainGlobe version 1 and the development of `brainglobe-registration`, the decision was made to disambiguate the role of the segmentation functionality and combine the napari plugin with the core functionality.
+
+## What do I need to do?
+
+If you were previously using any of the affected tools; you don't need to do anything right now if you want to wait for the full release of BrainGlobe version 1, which will take care of these dependencies for you.
+In the time between now and then, the tools as installed will still work but be aware that they will no longer receive updates due to the restructuring.
+
+If you would like to update your packages now, or would like to know how this will affect your scripts or workflows, [see the full changelog](#full-changelog) which covers API changes and the installation process.
+
+## Full changelog
+
+You can find the [full changelog on the releases page](../../community/releases/v1/brainreg.md).

docs/source/developers/index.md → docs/source/community/developers/index.md

@@ -5,7 +5,7 @@
 **Contributors to BrainGlobe are absolutely encouraged**, whether to fix a bug, develop a new feature, or add a new atlas.
 
 There are many BrainGlobe repositories, so it may not be obvious where a new contribution should go.
-If you're unsure about any part of the contributing process, please [get in touch](../contact.md). 
+If you're unsure about any part of the contributing process, please [get in touch](../../contact.md). 
 The best place for questions about contributing is probably
 the [BrainGlobe Zulip chat](https://brainglobe.zulipchat.com/).
 

docs/source/external-tools.md → docs/source/community/external-tools.md

@@ -44,5 +44,5 @@ BrainAtlas wraps the BrainGlobe Atlas API into a package for easy use with the U
 
 
 :::{hint}
-if you have developed any software using BrainGlobe tools, please [let us know](contact) and we can advertise it here. 
+if you have developed any software using BrainGlobe tools, please [let us know](../contact) and we can advertise it here. 
 :::

docs/source/more.md → docs/source/community/index.md

@@ -1,7 +1,9 @@
-# More
+# Community
 
-:::{toctree}
+```{toctree}
 :maxdepth: 1
+developers/index
+releases/index
 external-tools
 Sample datasets <https://gin.g-node.org/BrainGlobe>
-:::
+```

docs/source/community/releases/index.md

@@ -0,0 +1,11 @@
+# Releases
+
+Changelogs and release notes for all BrainGlobe tools, all in one place.
+
+## BrainGlobe restructuring (version 1) release notes
+
+```{toctree}
+:maxdepth: 2
+
+v1/index
+```

docs/source/community/releases/v1/brainreg.md

@@ -0,0 +1,60 @@
+# Version 1: changes to registration and segmentation tools
+
+## `brainreg` and `brainreg-napari`
+
+The previously separate packages `brainreg` and `brainreg-napari` have now been combined into a single package that keeps the `brainreg` name.
+This (new) `brainreg` package contains two submodules; `brainreg.core` whose contents are equivalent to the (old) `brainreg` package, and `brainreg.napari` that handles the napari widget.
+The `brainreg.napari` module is optional and needs to be specified at install if you are not intending to install it via the BrainGlobe version 1 package.
+
+If you were previously using brainreg in your scripts and have updated to version 1, you will now need to use `brainreg.core` instead of `brainreg`.
+However, the internal structure of the `core` submodule has been retained, so updating your scripts should be a case of replacing "`brainreg`" with "`brainreg.core`" across your codebase.
+Similarly, if you were ever importing `brainreg_napari` into your Python scripts, you will need to replace all occurrences of this with `brainreg.napari`.
+
+If you are installing `brainreg` as part of the brainglobe version 1 package, the napari plugin will be automatically included and you won't need to do anything else to install the plugin.
+Otherwise, to install the napari plugin, you will need to install `brainreg` with it's optional napari dependency via pip (recommended)
+
+```bash
+python -m pip install brainreg[napari]
+```
+
+or alternatively via conda
+
+```bash
+conda install brainreg
+```
+
+After updating, you may want to remove the now deprecated `brainreg-napari` package from your environment if it still persists;
+
+```bash
+pip uninstall brainreg-napari # If you originally installed via pip
+conda remove brainreg-napari # If you originally installed via conda
+```
+
+## Command-line executable
+
+The command-line executable has retained the name `brainreg` and has undergone no usability changes.
+
+## napari plugin
+
+When loading the plugin in napari, you will now find it listed under the plugins menu as "`Atlas Registration (brainreg)`" rather than "`Atlas Registration (brainreg-napari)`".
+If you have external scripts that reply on the internal name of the plugin, you will need to update these to `brainreg` (from `brainreg-napari`) accordingly.
+
+## `brainreg-segment`
+
+This package has been renamed `brainglobe-segmentation`.
+Beyond this renaming, there have been no internal changes to the package, so you may continue to use it as previously.
+However, you will need to switch all occurrences of `brainglobe_segment` to `brainglobe_segmentation` in your Python scripts.
+
+If you want to install the package standalone (without using BrainGlobe version 1 or through installing `brainreg`) then we recommend you `pip install` the package into your environment:
+
+```bash
+pip install brainglobe-segmentation
+```
+
+If you have `brainreg-segment` in your environment, you may wish to remove it as it will no longer be needed by `brainreg`:
+
+```bash
+pip uninstall brainreg-segment
+```
+
+however, `brainreg-segment` is still required by [`cellfinder`](../../../documentation/cellfinder/index.md) versions `<=v1.0.0`.

docs/source/community/releases/v1/index.md

@@ -0,0 +1,20 @@
+# BrainGlobe version 1 overview
+
+## Changes at-a-glance
+
+Below is a high-level overview of the changes to the brainglobe suite of tools that we offer.
+You can follow the links provided for more information; including a listing of relocated and/or renamed tools.
+
+| Change |   |
+|--------|:-:|
+brainreg and brainreg-napari have been merged into a single package | [Further info](brainreg.md#brainreg-and-brainreg-napari) |
+brainreg-segment has been renamed to brainglobe-segmentation | [Further info](brainreg.md#brainreg-segment) |
+
+## Complete index
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+brainreg
+```

docs/source/conf.py

@@ -107,7 +107,7 @@
 
 ## Cutomize the theme
 html_theme_options = {
-    "announcement": "BrainGlobe is undergoing restructuring. Keep track of the latest developments on <a href='https://brainglobe.info/blog/index.html'>the blog</a>",
+    "announcement": "BrainGlobe is undergoing restructuring. Keep track of the latest developments on <a href='blog/version1/version_1_announcement.html'>the blog</a>",
     "icon_links": [
         {
             # Label for this link

docs/source/contact.md

@@ -23,7 +23,7 @@ If you have a feature request, please open an issue at the relevant repository.
 ## Contributing
 If you would like to contribute to the BrainGlobe Initiative, please get in touch with us using the 
 [BrainGlobe Zulip chat](https://brainglobe.zulipchat.com/). We always welcome new Pull Requests,
-but please take a quick look at the [developer guide](developers/index) first.
+but please take a quick look at the [developer guide](community/developers/index) first.
 
 ## Other ways to get in touch
 While we prefer that all discussions about the project are carried out in public, there may be situations in which this 

docs/source/documentation/brainreg/installation.md

@@ -35,7 +35,7 @@ If you know what you're doing just run `conda install -c conda-forge brainreg`
 brainreg is written in Python, and so needs a functional Python installation. Your machine may already have Python 
 installed, but **we recommend installing miniconda**.
 
-**See** [**Using conda**](/documentation/general/conda) **for details.**
+**See** [**Using conda**](/documentation/setting-up/conda) **for details.**
 
 ```{caution}
 brainreg should run on any type of Python installation, but if you don't use conda, 

docs/source/documentation/brainreg/troubleshooting.md

@@ -7,7 +7,7 @@ NiftyReg, and not directly from brainreg.
 ## Common problems
 If brainreg fails to run (rather than runs, but the registration is poor) there are many potential causes. However, 
 the majority of the time, this is due to incorrect parameters passed to brainreg, particularly the [image 
-orientation and the voxel sizes](/documentation/general/image-definition). Please check these values against your image metadata before running brainreg. 
+orientation and the voxel sizes](/documentation/setting-up/image-definition). Please check these values against your image metadata before running brainreg. 
 
 ## Improving registration performance
 There are many ways to improve registration performance, but this will depend on your data. Some options to try include:
@@ -25,4 +25,4 @@ Process failed:
 ```
 
 This error could be caused by many things, but it is usually due to incorrect [definition of the image orientation or 
-voxel sizes](/documentation/general/image-definition). Please double-check the values entered are correct. 
+voxel sizes](/documentation/setting-up/image-definition). Please double-check the values entered are correct. 

docs/source/documentation/brainreg/user-guide/brainreg-cli.md

@@ -23,7 +23,7 @@ If you have any spaces in your file-path, please enclose it in quotation marks,
 * Output directory for all intermediate and final results
 
 :::{hint}
-You must also specify the orientation and voxel size of your data, see [Image definition](/documentation/general/image-definition).
+You must also specify the orientation and voxel size of your data, see [Image definition](/documentation/setting-up/image-definition).
 :::
 
 ### Additional options

docs/source/documentation/brainreg/user-guide/checking-orientation.md

@@ -4,7 +4,7 @@ To ensure that the orientation is set correctly, `napari-brainreg` comes with a
 orientation (thanks to [Jules Scholler](https://github.com/JulesScholler)!).
 
 Once you've loaded your data, fill in the input orientation in the GUI based on the 
-[bg-space definition](/documentation/general/image-definition) and click `Check orientation`. 
+[bg-space definition](/documentation/setting-up/image-definition) and click `Check orientation`. 
 This will generate a number of new images that are displayed to the user. The top row of displayed images are the 
 projections of the reference atlas. The bottom row are the projections of the aligned input data. If the two rows are 
 similarly oriented, the orientation is correct. If not, change the orientation and try again.

docs/source/documentation/brainrender/installation.md

@@ -3,7 +3,7 @@
 ## Environment
 
 To install `brainrender`, you need a python environment with a Python 3.8. This may be a different version than you are 
-using for other software. Using [conda](/documentation/general/conda) this can be created with:
+using for other software. Using [conda](/documentation/setting-up/conda) this can be created with:
 
 ```bash
 conda create --name brainrender python=3.8 -y

docs/source/documentation/cellfinder/installation.md

@@ -3,7 +3,7 @@
 cellfinder should run on most machines, but for routine use on large datasets, you will need a fairly high-powered
 computer (see the guide to [Speeding up cellfinder](/documentation/cellfinder/troubleshooting/speed-up) for details).
 
-Using an NVIDIA GPU will speed up cell classification considerably. See [setting up your GPU](/documentation/general/gpu) 
+Using an NVIDIA GPU will speed up cell classification considerably. See [setting up your GPU](/documentation/setting-up/gpu) 
 for details.
 
 cellfinder uses brainreg for atlas registration, and the hardware requirements for brainreg depend on the atlas 
@@ -25,7 +25,7 @@ Most machines (including laptops) will be able to use most of the atlases, but s
 
 ## Installing Python
 Your machine may already have Python
-installed, but we recommend installing miniconda. See [Using conda](/documentation/general/conda) for details.
+installed, but we recommend installing miniconda. See [Using conda](/documentation/setting-up/conda) for details.
 
 ## Installing cellfinder
 ```{hint}
@@ -41,14 +41,14 @@ pip install cellfinder-core
 :class: dropdown
 
 ```{hint}
-If you know what you're doing (and [your GPU is set up](/documentation/general/gpu)), just run `pip install cellfinder`
+If you know what you're doing (and [your GPU is set up](/documentation/setting-up/gpu)), just run `pip install cellfinder`
 ```
 
 
 ## Installing Python
 
 cellfinder is written in Python, and so needs a functional Python installation. Your machine may already have Python
-installed, but we recommend installing miniconda. See [Using conda](/documentation/general/conda) for details.
+installed, but we recommend installing miniconda. See [Using conda](/documentation/setting-up/conda) for details.
 
 ```{caution}
 cellfinder should run on any type of Python installation, but if you don't use conda, 

docs/source/documentation/cellfinder/troubleshooting/error-messages.md

@@ -78,7 +78,7 @@ In this case, a previous run of cellfinder hasn't completed. Either wait for it
 (in the terminal).
 
 Alternatively, your version of CUDA and cuDNN may be not compatible with TensorFlow. You can update them by 
-following the instructions [here](/documentation/general/gpu).
+following the instructions [here](/documentation/setting-up/gpu).
 
 ### ImportError: DLL load failed: The specified module could not be found.
 

docs/source/documentation/cellfinder/troubleshooting/speed-up.md

@@ -38,7 +38,7 @@ often work well on modern GPUs with >8GB memory.
 :::
 
 These steps may be slow if cellfinder is not properly using the GPU. If you have followed the instructions in 
-[setting up your GPU](/documentation/general/gpu), you may need to check that everything is configured properly:
+[setting up your GPU](/documentation/setting-up/gpu), you may need to check that everything is configured properly:
 
 Open a terminal (or Anaconda Prompt):
 
@@ -89,6 +89,6 @@ False
 ```
 
 Then your GPU is not properly configured. If you have followed everything in 
-[setting up your GPU](/documentation/general/gpu), please go speak to whoever administers your machine. If you're 
+[setting up your GPU](/documentation/setting-up/gpu), please go speak to whoever administers your machine. If you're 
 still stuck [get in touch](/contact), but there is a limited amount we can do to help configure your system.
 

docs/source/documentation/cellfinder/user-guide/command-line/cli.md

@@ -23,7 +23,7 @@ the files.  **This background channel will be used for all signal channels**
 
 :::{caution}
 You must also specify the orientation and voxel size of your data, see 
-[Image definition](/documentation/general/image-definition).
+[Image definition](/documentation/setting-up/image-definition).
 :::
 
 ### The following options can also be used:

docs/source/documentation/cellfinder/user-guide/napari-plugin/training-the-network.md

@@ -6,7 +6,7 @@ Once napari, and the cellfinder plugin is installed, open napari, and load the p
 
 :::{hint}
 Make sure your GPU is set up to speed up the training. See 
-[Setting up your GPU](/documentation/general/gpu).
+[Setting up your GPU](/documentation/setting-up/gpu).
 :::
 
 ## Set parameters

docs/source/documentation/index.md

@@ -1,15 +1,8 @@
 # Documentation
 
-## General
-```{toctree}
-:maxdepth: 1
-general/index
-../developers/index
-```
-
-## Individual tools
 ```{toctree}
 :maxdepth: 1
+setting-up/index
 bg-atlasapi/index
 bg-space/index
 brainreg/index

docs/source/documentation/general/index.md → docs/source/documentation/setting-up/index.md

@@ -1,4 +1,4 @@
-# General BrainGlobe documentation
+# Setting up
 
 
 ```{toctree}

docs/source/index.md

@@ -6,7 +6,7 @@ We have three aims:
 
 * Develop specialist software for specific analysis and visualisation needs, such as 
 [cellfinder](/documentation/cellfinder/index) and [brainrender](/documentation/brainrender/index).
-* Develop core tools to facilitate [others to build interoperable tools in Python](external-tools), e.g., the 
+* Develop core tools to facilitate [others to build interoperable tools in Python](community/external-tools.md), e.g., the 
 [BrainGlobe Atlas API](/documentation/bg-atlasapi/index).
 * Build a community of neuroscientists and developers to share knowledge, build software and engage with the 
 scientific, and open-source community (e.g., by organising hackathons).
@@ -38,7 +38,6 @@ How do I get started with these tools?
 
 Find out more about these tools.
 :::
-
 ::::
 
 ```{toctree}
@@ -48,6 +47,6 @@ Find out more about these tools.
 about
 tutorials/index
 documentation/index
+community/index
 blog/index
-more
 ```

docs/source/tutorials/cellfinder-cli/setting-up.md

@@ -9,7 +9,7 @@
 `test_brain` with two directories, each containing 2800 images
 * Open a terminal (Linux) or your command prompt (Windows)
 * Navigate to the directory containing the `test_brain` directory (e.g. using `cd`)
-* Activate your [conda environment ](/documentation/general/conda)
+* Activate your [conda environment ](/documentation/setting-up/conda)
 
 :::{hint}
 The test data supplied is purposefully not the "best". It has a low SNR, and some artefacts such as fluorescent 
@@ -33,12 +33,12 @@ autofluorescence channel. In this case, `test_brain/ch00` is the signal channel
 autofluroescence channel
 * Where you want to save the output data (we'll just save it into a directory called `cellfinder_output`in the 
 same directory as the `test_brain`)
-* The pixel sizes of your data in microns (see [Image definition](/documentation/general/image-definition) for details). 
+* The pixel sizes of your data in microns (see [Image definition](/documentation/setting-up/image-definition) for details). 
 In this case, our data is 2μm per pixel in the coronal plane and the spacing of each plane is 5μm
 * The orientation of your data. For atlas registration (using [brainreg](/documentation/brainreg/index)) the 
 software needs to know how you acquired your data (coronal, sagittal etc.). For this cellfinder uses 
 [bg-space](/documentation/bg-space/index). Full details on how to enter your data orientation can also be 
-found in the [Image definition](/documentation/general/image-definition) section. For this tutorial, the orientation 
+found in the [Image definition](/documentation/setting-up/image-definition) section. For this tutorial, the orientation 
 is `psl`, which means that the data origin is the most **p**osterior, **s**uperior, **l**eft voxel.
 * Which atlas you want to use (you can see which are available by running `brainglobe list`. In this 
 case, we want to use a mouse atlas (as that's what our data is), and we'll use the 10μm version of the