MagellanMapper v1.3 Release Notes

MagellanMapper v1.3.8

This is a bugfix release for MagellanMapper.

Changes

Installation

  • Fixed missing dependencies required by Pyface Conda dependency

GUI

  • Fixed incorrect color mapping for some corresponding labels (ie same region in opposite hemispheres)

Atlas refinement

  • Fixed error in compactness measurement when no surface is found

Atlas registration

  • Specify a full fallback atlas profile rather than only a fallback similarity metric if the post-registration DSC falls below threshold (metric_sim_fallback setting)

Cell detection

  • Fixed applying the first channel’s profile setting for image saturation to all channels during blob detection

I/O

  • Fixed reading image size and resolution metadata when values for some dimensions are missing

  • Fixed importing RGB images

  • Fixed redundant channel import for some formats (eg some OME-TIFF files)

Dependency Updates

  • Added import_metadata and import_resources packages required by Pyface

MagellanMapper v1.3.7

This is a bugfix release for MagellanMapper.

Changes

Installation

  • Fixed launch error when Javabridge is installed but Java is not

GUI

  • The “Save Figure” button opens a file save dialog to configure the location, filename, and file format of saved figures

  • Fixed display resolution on HiDPI screens set to fractional scaling (eg 150%; the fix requires Qt 5.14+)

  • Fixed Atlas Editor non-Numpy image initial loading performance (regression introduced in v1.0.0, most notably in larger images)

  • Fixed Atlas Editor to enable saving after edge interpolation

CLI

  • Configure DPI of saved images using --plot_labels dpi=<n>

  • Specify colors for NaN values through --plot_labels nan_color=<color> instead of through --atlas_labels binary=<color>, which is now only specifies colors when displaying labels as binary images to fix this display

  • Defaults to saving images in PNG format, even if --savefig <ext> is not set

  • CLI sub-arguments are now shown in ./run.py -h (help documentation)

  • Fixed saved plane filenames to use the plane index for the axis corresponding to the saved plane

Atlas refinement

  • Smoothing metrics now include the filter size in metrics output

  • Fixed the denominator in the smoothing displacement metric and smoothing metrics for non-existent labels

Python stats and plots

  • Excludes decimal points that were likely included by floating-point errors

  • Fixed mapping measurements to labels with weighting

MagellanMapper v1.3.6

This release focuses on usability fixes. New settings settings and build tools have been added to support older Linux platforms.

Changes

Installation

  • Dockerfile based on Ubuntu 16.04 added to support running on older platforms

GUI

  • Status bar shows pixel values in zoomed ROI plots

  • Fixed upper/lower case in check box labels

  • Fixed saving ROIs to use the original ROI offset

  • Fixed resetting the labels opacity when scrolling through planes

  • Fixed updating channels in the image adjustment panel for the current image type

CLI

  • --cpus <n> command-line argument to specify the maximum number of CPUs to use for multiprocessing tasks

  • ROI profile setting (mp_max_tasks) to set the maximum tasks per process, which can reduce memory usage considerably

Volumetric image processing

  • Density heat maps default to using the whole image

  • Fixed ROI saturation to use the max_thresh_factor ROI profile setting

I/O

  • Better information when a file could not be found for import

  • Specifying the profiles directory is no longer necessary when loading YAML profile files, including those in sub-directories

  • Experiment names in the database now ignore any file extension

Dependency Updates

Python Dependency Changes

  • SimpleElastix compilation

    • Dockerfile to build for older platforms

    • Allow directory to be given as a relative path in the build script

    • Fixed loading a library in the script

  • Install Matplotlib >= 3.3.2 now that the performance regression starting in 3.3.0 has been fixed

  • Additional Pandas dependencies can be installed by specifying the pandas_plus group (installed by default in the setup scripts)

MagellanMapper v1.3.5

This release streamlines refreshing and overlaying images through the GUI. Workarounds are also provided for several installation/dependency issues.

Changes

GUI

  • Multiple intensity images can be selected through the GUI to overlay

  • Refreshes images in each viewer after a new image has been loaded

  • Selecting an ROI dropdown menu entry updates the current viewer

  • Fixed retaining prior images and resolutions from previously loaded image during the session

  • Fixed setting the initially displayed channel from the command-line

  • Fixed to show the labels reference file if loaded from command-line

  • Fixed loading ROI Editor layouts with 3D screenshots if the 3D viewer had not been opened yet

  • Fixed 3D viewer orientation when opening the tab for the first time during a session

  • Fixed blob detections to appear in both the ROI Editor and 3D viewer

CLI

  • Simplify loading only images by registration suffix to allow specifying a directory as such: --img <dir> --reg_suffixes [atlas-img] [annotation-img]

I/O

  • Resolutions are easier to read with fewer decimal places shown

  • Filenames are saved in the database experiments table without extension to allow more naming flexibility

  • Fixed applying objective magnification and zoom metadata to multi-plane image imports

Server pipelines

  • Removed default microscope objective metadata now that metadata is extracted from input files when possible

Python stats and plots

  • Fixed loading discrete, symmetric colormaps with an even number of colors

Dependency Updates

Python Dependency Changes

  • PyQt is now specified explicitly for Conda environment installs to avoid installing an older release (ie was installing v5.9 instead of v5.12)

  • Matplotlib v3.2 is installed because of performance slowdown especially during mouseover of images when using the latest current release (v3.3)

  • Fixed setup.py to include PyYAML (dependency introduced in MagellanMapper v1.2.1)

Server dependency Changes

  • Dockerfiles are included, with one version based on Miniconda3 and another on Ubuntu 18.04

MagellanMapper v1.3.4

This release eases ROI setup and fixes a number of channel, import, and installer issues.

Changes

Installation

  • The Conda setup script will initialize all shells for Conda, which fixes activation in zsh on macOS

  • Initial Docker integration

  • Fixed Conda light environment specification for the custom Javabridge pacakge

GUI

  • ROI controls synchronize with the ROI and Atlas Editors

  • ROI Editor

    • Preview a new ROI by clicking on a desired position in any overview plot

    • Redraw by double right-clicking in any overview plot

    • Changed the shortcut to jump to the plane of a given ROI plot: right-click the plot (instead of right-arrow + left-click)

    • Option to toggle detection circle visibility

    • Fixed ROI Editor title spacing

  • Fixed channel indexing when selecting a subset of channels

  • Fixed resetting labels images when loading a new image

  • Fixed loading image filenames that partially match registered suffixes

  • Fixed saving blobs when no blobs have been detected

CLI

  • Fixed to apply alpha channel parameter when overlaying images

Atlas registration

  • Fixed YAML atlas profile template for b-spline registration settings

I/O

  • Selecting an imported file in the Import tab loads the file instead

  • Fixed handling incomplete metadata during import

Code base and docs

  • Provided uninstallation directions

MagellanMapper v1.3.3

This is a bug fix release for Conda setup.

Changes

Installation

  • Fix Conda setup when conda is not found, including new installations

  • Fix setting up a Conda environment when another matching environment is found from a different Conda installation

I/O

  • Fix import of multi-file, single-channel RAW images

Python stats and plots

  • Option to drop duplicates when joining data frames using the new --plot_labels drop_dups=<0|1> command-line argument

MagellanMapper v1.3.2 (beta)

This beta release streamlines scripts to install and run MagellanMapper through a file browser, without requiring a terminal. Registered images can now be loaded and overlaid through the GUI. The image import panel auto-populates available metadata, and RAW format images can be imported. Image intensity controls better adapt to the current image.

Changes

Installation

  • Conda setup script for Bash (eg Mac/Linux)

    • Creates a MagellanMapper launch script that auto-detects more python installations to launch run.py (ie when only python3 is available or if python is only available through Conda)

    • Better able to find existing Conda installations before attempting to install Conda

  • run_cli.py has been re-integrated into run.py and removed

GUI

  • Select registered images and labels in the ROI panel

    • Control the main intensity image, showing all available images registered to the current image

    • Selector for a registered labels/annotation image

    • Selector a labels reference file

  • Import panel

    • Brings the user to the import panel when unable to load a file

    • Auto-populates metadata when available from the image file

    • Added output image shape and data type fields

    • Turn on all channel after when displaying a newly imported image

    • Fixed re-displaying an image re-imported to the same output path

  • Image adjusment panel

    • Adapts the intensity range to the current image to allow finer adjustments

    • Option for auto-intensities

    • Fixed settings to persist when scrolling among planes

    • Fixed slider sizes by capping the size of number labels

    • Fixed intensity slider ranges for images that were not imported into Numpy format

  • Blob detector controls have been moved to a separate “Detect” panel

  • Fixed crash when selecting the 3D Viewer tab or detecting blobs without a loaded image

  • Fixed updating ROI size when loading an image through the GUI

  • Fixed decimal point display in integere

I/O

  • Support for importing RAW image format files

  • Export images to RAW format (--proc export_raw)

  • Support for both TIFF and non-TIFF format files through Bioformats

  • Fixed support for incomplete metadata

  • Fixed importing images while skipping channels

  • Fixed import when unable to load the main image

Server pipelines

  • Fixed to not attempt download from S3 if an S3 directory was not set

MagellanMapper v1.3.1 (beta)

This beta release contains multiple new control panels to adjust profiles, brightness/contrast, and image file import. These controls allow users to control MagellanMapper more graphically and reduces the need to restart for new settings.

Changes

Installation

  • Keep Windows setup script open after installing by double-click to view instructions and any error messages

  • MacOS/Linux Conda setup script renamed to allow double-click launch on MacOS and to further distinguish from the Windows setup script

GUI

  • Control panels

    • Profiles panel: select, refresh, and reload profiles

    • Image adjustment panel: change brightness, contrast, and opacity

    • Image import panel: view and adjust matched files before import, add metadata, load immediately after import

  • Select subset of channels instead of only all or single channels

  • Zoom and pane functions in the ROI Editor overview image plots

  • Adapts to high resolution (HiDPI) screens

  • Consistent dark theme applied automatically when the system dark theme is used (depends on PyQt detection)

  • Fixed crash when opening the Atlas Editor tab without an image loaded

  • Fixed performance regression in ROI Editor

CLI

  • --channel command-line parameter accepts multiple arguments

  • Sample commands script prioritizes finding Numpy image files

  • More error output from run scripts

  • Fixed attempting to run MagellanMapper in the Conda base environment

MagellanMapper v1.3.0

This release brings many changes to streamline both the graphical and command-line interfaces. Please note that several options have changed, which may require updating custom scripts. The sample commands script (bin/sample_cmds.sh) has been updated to illustrate this usage.

Summary of usage changes:

Old

New

Purpose

python -m magmap.xx.yy

run_cli.py

All command-line based entry points can be accessed through the CLI using this script

Use atlas profile for registration

No longer needed

Atlases should be fully imported before image registration, and the atlas’s profile should no longer be typically given when registering an image

--stats

--df

Run data-frame (eg CSV file) tasks

--roc

--grid_search <name1>[,name2]

Its main task is to perform Grid Search based hyperparameter tuning; specify profile names or YAML files

--rescale

--transform rescale=x

Grouped with other transformation tasks

--microscope <name1>[_name2]

--roi_profile <name1>[,name2]

Specifies profiles to process by regions of interest; delimit by , to allow underscores especially in file paths

--reg_profile <name1>[_name2]

--atlas_profile <name1>[,name2]

Specifies profiles for atlases; delimit by , to allow underscores especially in file paths

--saveroi

--save_subimg

Consistency with “sub-images” as parts of images that can contain ROIs

--chunk_size

None

Obsolete

finer atlas profile

None

Its settings are now default

--res

--set_meta resolutions=x,y,z

Grouped custom metadata settings into --set_meta

--mag

--set_meta magnification=x.y

Grouped custom metadata settings into --set_meta

--zoom

--set_meta zoom=x,y,z

Grouped custom metadata settings into --set_meta

--no_show

--show 0

Show with 1

--no_scale_bar

--plot_labels scale_bar=1

Grouped with other plot labels controls

--padding_2d

--plot_labels margin=x,y,z

Grouped with other plot labels controls, adding margin as space outside the ROI

--border

--plot_labels padding=x,y,z

Duplicated by the padding argument

--channel c1

--channel c1 [c2...]

Accepts multiple channels (v1.3.1)

Changes

Installation

  • New Windows install script

  • The install scripts are now the recommended installation pathway

  • Install scripts perform silent Miniconda installs after prompting

  • Fixed the URL for Miniconda download

  • Fixed the run script to include command-line arguments

GUI

  • All new integrated graphical interface with unified ROI Editor, Atlas Editor, and 3D viewer in separate tabs alongside the controls panel

  • ROI Editor

    • Overview plot zooming scales to the size of the ROI

    • Orange border highlights the ROI z-plane corresponding to the overview plots

    • Shows similar pixel information as in the Atlas Editor

    • Layout now respects labels

    • Title now specifies axes

    • Title and empty ROI plots compatible with dark theme

    • Halve the size of truth blobs in verification plots to avoid obscuring the underlying image

    • Easier to flag detections in the ROI Editor

  • GUI image loading

    • Load sub-images through the GUI

    • Fixed loading the GUI without an image

    • Fixed loading images through the GUI

    • Fixed image coordinate limits after loading an image

  • Region selection

    • Option to select multiple regions, separating IDs by ,

    • Selecting a region ID shows its basic measurements

    • Fixed potential for label boundaries to exceed image boundaries

  • Isotropic rescaling is turned on by default for 3D visualizations and incorporates image resolution

  • NaN values can be used for invisible pixels, which reduces opacification when highlighting an atlas label in the ROI Editor

  • 3D surface rendering is now default

  • Unified save button for all viewers

  • Auto-select a channel when restoring an ROI based on saved blobs’ channel

  • Fixed hang when opening the Atlas Editor for large images (downsamples images if necessary)

  • Fixed error when showing an image with the z-offset set to the maximum value

  • Fixed clearing picked colors during atlas painting

  • Fixed the aspect ratio for images rotated 90 degrees

  • Fixed display of RGB values for labels

  • Fixed over darking some text boxes when hovering

  • Fixed blob alignment in 3D surface rendering

CLI

  • The CLI now serves as a unified entry point to the Command Line Interface, incuding register, plot_2d, and other tasks,

  • The CLI can be accessed through the run_cli.py script, which benefits from the environment setup in run.py without loading a window

  • --proc preprocess option to preprocess whole images by tasks specified in a preprocess ROI profile setting

  • Many more sample commands for common tasks

  • Better support for using the sample commands script without modification

  • Help information added for command-line arguments

  • Command-line arguments are checked for valid options when available

  • Task to export image planes to separate files (--proc export_planes)

  • Fixed sample commands for sub-images

  • Fixed sample commands path setup for older versions of Bash (< 4.3)

Atlas refinement

  • Resize images using the --size argument as an alternative to a profile setting

  • Atlas operations expecting symmetry have been generalized across any axis

  • Apply adaptive histogram equalization (access as a preprocessing task)

  • Records total volumes of atlas and labels during atlas import

  • Fixed rotation with resizing for non-z axes

  • Fixed storing image plane boundaries for label contour interpolation

Atlas registration

  • The atlas is assumed to be pre-imported, which avoids redundant atlas import tasks

  • Support for more pre-registration atlas pre-processing tasks, such as 3D rotation, inversion, cropping, and rescaling

  • Saves a truncated labels and pre-curated images only if the corresponding options are set

  • Option to rescale units (eg mm to microns)

  • Settings are customizable for each registration transformation task (eg translation, affine) rather than globally

  • Defaults to increased b-spline iterations

  • Fixed display of images through SimpleITK after registration

Volumetric image processing

  • Grid Search profiles

    • Configurable as YAML files

    • Fixed Grid Searches without sub-image parameters

  • Provides basic detection accuracy stats when saving blobs

  • Option for whole-image contrast limited adaptive histogram equalization (using scikit-image)

  • Fixed retrieving saved ROIs from the database

I/O

  • Import from a directory of images

    • Option to convert RGB images to grayscale when importing images from a directory

    • Import multi-channel images

    • Fixed importing large images

  • Option to specify output paths when importing a image directory or multi-page TIFF

  • Can load multi-page TIFF files without channel indicator

  • Defaults to saving figures as PNG

  • Library functions for listing, downloading, and uploading files in AWS S3

  • Library functions for de/compressing and testing files using ZSTD

  • Allows loading the main image from a registered image path

  • Avoids loading a sub-image when saving it to avoid a hang

  • Sample YAML profiles for blob detection, registration

  • profiles folder is checked automatically when loading YAML profiles

Python stats and plots

  • Command-line options for configuring markers (--plot_labels marker) and annotation columns (--plot_labels annot_col)

R stats and plots

  • Simple R script to load and run stats

Code base and docs

Dependency Updates

Python Dependency Changes

  • Javabridge custom binary updated for import fix on MacOS

  • Removed redundant PyQt5 installation during Conda installs

  • Workaround for VTK 9 incompatibility with currently Mayavi dependency