Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Version 1 release #132

Merged
merged 11 commits into from
Jan 8, 2024
68 changes: 68 additions & 0 deletions docs/source/blog/version1/version_1_released.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
blogpost: true
date: Jan 8th, 2024
author: Will Graham
location: London, England
category: BrainGlobe-v1
language: English
---

# BrainGlobe version 1 is here! :partying_face:
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved

Following our series of incremental updates to a number of BrainGlobe tools, we are pleased to announce that BrainGlobe version 1 has been released today!
Users can now enjoy:

- A one-line installation of _all_ BrainGlobe tools, automatically handling dependency inconsistencies and providing the _entire_ BrainGlobe tool suite. Individual tools no longer need to be manually installed as-and-when they're needed, and users do not need to worry about the behind-the-scenes organisation of the packages providing the tools.
- A clearer and more consistent naming convention for the tools that are provided.
- Access to example analysis workflows, installable on top of the BrainGlobe tool suite.

BrainGlobe version 1 is hallmarked by the release of (version 1 of) the [`brainglobe` package on PyPI](https://pypi.org/project/brainglobe/), and the new [`brainglobe-workflows` package](https://pypi.org/project/brainglobe-workflows/).

## Users: what you need to know

The version 1 release of `brainglobe` on PyPI will provide you with the entire BrainGlobe tool suite and ensure that the tools are consistent with one another.
You will no longer need to worry about manually installing individual BrainGlobe tools and checking how they interface with other tools.
You can also easily install the complete BrainGlobe suite of tools on a new machine or into a fresh environment in a single `pip` command:

```bash
pip install brainglobe>=1.0.0
```

The `brainglobe` package, or "meta-package" as we like to refer to it, ensures that the BrainGlobe tools installed onto your machine are stable and consistent with each other.
Key packages provided include:
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved

- `atlasapi`
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
- `brainreg`
- `brainrender` and `brainrender-napari` (new with version 1)
- `brainglobe-napari-io`
- `brainglobe-segmentation`
- `cellfinder`

The individual tools that you have been using are still available, and are largely still using the same name (with the exception of the old `cellfinder` command-line-tool, see below).
Regardless of how many of our tools you use in your analysis, we recommend that you create a new environment and (re)install any BrainGlobe tools you have been using following the instructions on the installation page.

For the most part, the effects of moving to version 1 should be limited to the cases where a tool has been merged with its napari plugin, or the relocation of the (old) cellfinder command-line tool.
The previous blog posts in this series outline these changes:

- [Blog post](./brainreg_update_live.md) | `brainreg`, `brainreg-napari` have been merged, whilst the somewhat unrelated `brainreg-segment` package has been renamed to distinguish it.
- [Blog post](./cellfinder_migration_live.md) | The old command-line tool (which confusingly was called "cellfinder" despite being a combination of several BrainGlobe tools) has been moved to `brainmapper` in the `brainglobe-workflows` package.
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
- [Blog post](./core_and_napari_merge.md) | `cellfinder-core` and `cellfinder-napari` have been merged into just "`cellfinder`".
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved

Our vision for the new `brainglobe-workflows` package is to take this one step further and provide a selection of pre-written data analysis pipelines for neuroscientific data.
Currently the `brainglobe-workflows` package contains the successor to the old cellfinder command-line tool, now called `brainmapper`, but additional workflows will be added in the future.

## Developers: what you need to know

The `brainglobe` package allows us to ensure that tools cannot be installed in a manner which is inconsistent with each other.
If tool `A` necessitates a change in tool `B`, it was possible to update `A` without knowing about the knock-on effect on `B`, which would cause bugs further down the line.
Now the `brainglobe` package can be re-released in a manner which pins consistent versions of `A` and `B`, preventing this from happening.

The `brainglobe-workflows` package allows us to do two further things:

- It provides a distinct location for workflows that utilise BrainGlobe tools, so these workflows are not bundled together with their backends.
- It provides us with a set of analysis pipelines that we expect users to frequently run, which we can use to benchmark our tools and identify areas for improvement in terms of performance or speed.
- It builds on top of the `brainglobe` package, rather than having packages be interdependent on each other due to a workflow utilising multiple tools but being provided with its backend.

## Full Changelog

The full changelog is [available here](/community/releases/v1/index.md).
52 changes: 50 additions & 2 deletions docs/source/community/releases/v1/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# BrainGlobe version 1 overview

BrainGlobe version 1 provides users with the `brainglobe` "meta"-package: a single package that will fetch all the tools in the BrainGlobe suite and install them onto your machine, ready for use.
It also provides the `brainglobe-workflows` package, which builds on top of `brainglobe` and provides some common analysis pipelines to users, as well as a benchmarking suite for developers working on code performance improvements.

## Updating to version 1

Our recommendation for updating to BrainGlobe version 1 is to follow the [installation instructions on the main documentation page](/documentation/index.md#installing-brainglobe) in a clean virtual environment, and delete or archive your old environment.
This will ensure that when you install `brainglobe`, the tools are fetched in a consistent manner and do not pick up any manually installed BrainGlobe tools that might be in your environment or python path.
Likewise, it also avoids potential issues when tools have been installed from both `conda-forge` and `PyPI`.

If you don't want to install the entire BrainGlobe suite and are happy to manage the tooling interdependencies yourself, you can still manually install the individual BrainGlobe tools that you wish to use.
If you choose to do so; as a general rule of thumb you should not mix `conda-forge` and `PyPI` installs, and avoid installing BrainGlobe tools of versions less than 1 in the same environment as those with version greater than 1 at all costs.
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved

### Previous installs with conda
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved

If you have previously installed any of our tools from conda, we strongly recommend that you create a new environment and follow the `pip` installation instructions provided on the [installation page](/documentation/index.md#installing-brainglobe).
The new "version 1" of BrainGlobe provides a PyPI package that comes with the complete suite of tools, and ensures that these are all consistent with one another.
These are fetched by `pip` and so may cause conflicts if they are already present in your environment, having been fetched from `conda-forge`.
Mixing `conda-forge` installed packages with the `brainglobe` package from PyPI will likely throw versioning issues as we can't guarantee that `conda` will resolve the tool dependencies correctly.

## Changes at-a-glance

Below is a high-level overview of the changes to the brainglobe suite of tools that we offer.
Expand All @@ -13,8 +32,8 @@ The `cellfinder` command-line-interface has been moved into `brainglobe-workflow
The cellfinder package is deprecated - it will later be recycled to merge some backend functionality | [Further info](cellfinder-migration.md#cellfinder-repository) |
The cellfinder Docker image is discontinued | [Further info](cellfinder-migration.md#cellfinder-docker-image) |
cellfinder-core and cellfinder-napari merged into "new cellfinder" | [Further info](cellfinder-core-and-plugin-merge.md) |

## Complete index
The cellfinder command-line tool has been replaced with `brainmapper` | [Further info](cellfinder-core-and-plugin-merge.md) |
`brainrender` and `brainrender-napari` are now available through the `brainglobe` meta-package | [Further info](/blog/version1/version_1_released.md)

```{toctree}
:maxdepth: 1
Expand All @@ -24,3 +43,32 @@ brainreg
cellfinder-migration
cellfinder-core-and-plugin-merge
```

## Full Changelog

- Recommended BrainGlobe install is via pip, into a clean environment.
- `pip install brainglobe` to install BrainGlobe tools. Recommended even if you only want to use one or two tools.
- `pip install brainglobe-workflows` if you also want to use the example analysis workflows that we provide.
- `brainreg-napari` is now shipped with `brainreg`
- `brainreg` functionality is now available in a submodule, `brainreg.core`. If you previously used the Python API provided in `brainreg`, you will need to change your `from brainreg import X` statements to `from brainreg.core import X`.
- The `brainreg-napari` plugin is now just called `brainreg` when using `napari`. The plugin's backend is in the submodule `brainreg.napari` rather than `brainreg-napari`.
- The new `brainreg.core` and `brainreg.napari` submodules retain the old internal structure of the respective deprecated packages.
- `brainreg-segment` has been renamed `brainglobe-segmentation`.
- Beyond the name change, package internals have not changed.
- `cellfinder` command-line-interface (CLI) has been renamed and moved.
- The command-line interface is now provided by `brainglobe-workflows`.
- The command-line tool is now called `brainmapper`.
- The name "cellfinder" is now reserved for the merged `cellfinder-core` and `cellfinder-napari` packages.
- `cellfinder-core` and `cellfinder-napari` have been merged into a single package, called `cellfinder`.
- The `cellfinder` package should not be confused with the old cellfinder command-line tool, described above. Going forward, "cellfinder" will refer exclusively to this new, merged package created from `cellfinder-core` and `cellfinder-napari`. The command-line tool with use the name `brianmapper`.
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
- The `core` and `napari` features are now available as submodules of the `cellfinder` package. If you previously used `from cellfinder_core import X`, you'll have to use `from cellfinder.core import X` instead.
- Internal function names and locations have otherwise not changed, beyond their conversion into the `core` and `napari` submodules.
- The napari plugin is now referred to as the `cellfinder` plugin, and shows up with the name `cellfinder` when viewed in napari (as opposed to the old `cellfinder-napari` name it used to have).
- `brainglobe-workflows` has been released.
- This package provides some exemplar data analysis workflows for users to modify or customise to suit their needs.
- It will also provide command-line interfaces for particularly common workflows. Currently it provides `brainmapper`, the successor to the _old_ cellfinder command-line tool.
- `pip install brainglobe` is now the recommended way to install all BrainGlobe tools.
- This will fetch the `brainglobe` meta-package, which includes the latest stable versions of all BrainGlobe tools and napari plugins.
- All tools will be accessible in the install environment as if they had been pip-installed directly.
- If you are updating to `brainglobe` version 1 having previously installed BrainGlobe tools individually, we [recommend you create](#updating-to-version-1) a clean Python environment and install `brainglobe` into this fresh environment to avoid potential package conflicts.
Comment on lines +71 to +74
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are at least parts of this a duplicate of what we already say on line 50 and should therefore be integrated there or here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Parts of it definitely are, but I felt duplicating these parts made more sense than only including them in one place or another. Otherwise it's not really a full changelog, and it's not worth a "see this section" when users only need to be redirected to one sentence?

- `brainglobe` package now ships the fixed `brainrender`, as well as `brainrender-napari` which we plan to transition to in the future.
49 changes: 48 additions & 1 deletion docs/source/documentation/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,52 @@
# Documentation

## Installing BrainGlobe

We always recommend that you install BrainGlobe tools into a virtual environment (managed by software such as `conda` or `venv`).
Your environment should run Python 3.9 or later.
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved

Once you have created and activated your desired environment, you can install all BrainGlobe tools using `pip`:

```bash
pip install brainglobe
```

This will fetch all BrainGlobe tools, their Python APIs, and [`napari`](https://napari.org) plugins if they possess one.
It will also install `napari` into your environment so that you can make use of the plugins.

If you also want to install our command-line tools and/or example workflows, you will also need to install the `brainglobe-workflows` package.
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
This package builds on top of the `brainglobe` tools, and provides you with some commonly-used data analysis pipelines to save you from having to write your own scripts for standard workflows.
You can read about the workflows that are provided [on the documentation page](./brainglobe-workflows/index.md).
To install `brainglobe-workflows`, run

```bash
pip install brainglobe-workflows>=1.0.0
```

in your environment.
If you didn't previously install `brainglobe` into this environment, `brainglobe-workflows` will do so when you run the command above.
Otherwise, it will use the version of `brainglobe` that you already have installed.

### Updating

You can update your BrainGlobe tools by running

```bash
pip install brainglobe --update
```

in your virtual environment.

### Installing Individual Tools

We recommend installing BrainGlobe in the manner detailed above, however each of the tools in the suite can be individually installed if you so wish.
This can be done by following the install instructions for the particular tool in question.

Please note that, if you choose to install the tools individually, we cannot guarantee that you will have a consistent and interoperable set of BrainGlobe tools - you may encounter version conflicts or dependency issues.
If you're not confident in resolving these yourself, we recommend installing BrainGlobe in the manner above; and updating your BrainGlobe tools by updating the overarching `brainglobe` package.
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved

## Individual Tool Documentation

```{toctree}
:maxdepth: 1
setting-up/index
Expand All @@ -12,4 +59,4 @@ brainrender/index
brainglobe-heatmap/index
cellfinder/index
morphapi/index
```
```