pip install brainglobe is doing what you expect - installing a package from PyPI called
This package, colloquially referred to as the “meta”-package,
brainglobe-meta, doesn’t actually contain any functionality beyond providing a version and some author information.
Instead, it’s primary purpose is to (explicitly) depend on the other BrainGlobe tools that we want users to be able to install in a single command, through this package.
You can find the source for this package in the
brainglobe-meta repository on GitHub.
The meta-package should always be installable in one line, and preferably should be installed for the first time in a clean environment.
brainglobe can be installed from PyPI via
pip install brainglobe
python -m pip install brainglobe
--update flag to
pip to force an update on an existing install.
The rule of thumb for versioning and releasing the meta-package (creating a “new version of
brainglobevX.0.0 release is a set of stable, compatible tools that interoperate with each other consistently. A
brainglobevX.Y.0 or vX.Y.Z release should be used when there have been several minor or patch updates to the BrainGlobe tool suite, that we want to encourage the user-base to adopt.
As such, we typically envision major version releases of the meta-package taking place when one or more BrainGlobe tools undergo major updates.
An example would be the release of
brainglobe version 1; which saw the various
brainreg packages merged, the
cellfinder package was repurposed in order to merge
cellfinder-napari, and the
brainmapper tool replace the (old) cellfinder command-line interface.
brainglobe version 1.0.0 release prevents users from installing incompatible versions of
cellfinder, for example, both by removing the need for users to install these tools manually and by pinning minimum versions for each.
Minor or patch updates to
brainglobe we envision to be cases where multiple tools have undergone performance improvements, minor patches, or under-the-hood code refactoring that we feel benefits the user experience, but does not require a change in how the user interacts with these tools.
A typical example of this might be when a function appears in both
brainglobe-tool-B, so we decide to refactor it into
brainglobe-utils which is a common dependency.
In this case, each of
brainglobe-utils would get new releases, and furthermore both
brainglobe-tool-B would now depend on the new version of
We would then decide to release a minor version of the meta-package, which updates the minimum version of these three packages - from the user perspective, this will come in a single update.
With the above conventions on versioning in mind, meta-package dependencies are always pinned from below, and from above by the next major version.
As such, all BrainGlobe dependencies in the meta-package
pyproject.toml will have the form:
dependencies = [
dependencies = [
This ensures that:
Minor and patch updates to BrainGlobe tools should be picked up automatically by package installer when updating the metapackage. For example, if
1.2.0, updating the meta-package will result in
cellfinderbeing updated to
Major or breaking changes to BrainGlobe tools are not automatically picked up on update!
We can force certain (combinations of) minor/patch updates to tools on users by simply releasing minor/patch updates to
brainrender>=2.2.1,<3", then creating a new
brainglobeminor/patch release, allows the user to update both of these packages with an update to
brainglobe, not having to worry about the individual packages themselves.
BrainGlobe comprises a number of tools, spread across a number of repositories. These tools are all interlinked and interdependent, but the meta-package allows us to abstract this complexity away from the user.
To ensure we retain explicit control over what
brainglobe provides to users, it is important that the meta-package explicitly depends on all BrainGlobe tools that it wants to provide, including “redundant dependencies”.
For example, if the meta-package is providing
brainglobe-tool-A, which itself depends on
brainglobe-tool-B, then the dependency list of the meta-package should include both
Both packages should also have minimum versions pinned as per the dependency pinning guidelines above.
The dependency tree of BrainGlobe tools provided by the meta-package is provided below, and should be updated periodically as new tools are added, or new versions of
brainglobe are released.
Whilst it is not necessary for developers to remember the dependency structure, it is a useful reference guide for discerning how updates to one BrainGlobe tool might have knock-on effects on others.
The dependency tree reads top-to-bottom; that is, arrows are drawn out of dependencies into the tools that depend on them.
The tree does not include non-BrainGlobe dependencies.
Coloured arrows are only present to allow for line-tracing when arrows cross.
Regenerating the Dependency Tree#
The image file containing the dependency tree is saved under
It can be edited with any software that can open and manipulate
.svg files, however the recommended tool is
drawio which provides a GUI for editing
Simply upload the current version of the file to the website, edit the flowchart as you see fit, then hit
File > Export As... > SVG, which will open a further dialogue box with export options.
In this box, be sure to select “
Text Settings: Convert Labels to SVG” to ensure that the exported flowchart’s text is encoded correctly.
You can then export the file and save the new version to the repository.
As a general rule of thumb when editing the dependency chart, packages/tools should be organised into levels from the top down, with arrows pointing out of dependencies into the dependent packages.
Packages on the top level depend on no other BrainGlobe tools. Packages on the level below depend on at least one package from the level above, and any number of packages from the level(s) further up than that. This illustrates both how BrainGlobe tools build on each other, as well as which tools may be affected by new releases of others.
Latest rendering of the dependency tree: