fractal-feature-explorer

Installation

The easiest way to install the fractal-feature-explorer is to use uv or pipx:

pipx install fractal-feature-explorer

or

uv tool install fractal-feature-explorer

Alternatively, you can install it in a standart Conda/Venv using pip:

pip install fractal-feature-explorer

Usage

You can run the dashboard using the explorer command:

explorer

at the first run, it will ask you for permission to create a configuration file in your home directory (~/.fractal_feature_explorer/config.toml), which will be used for future runs.

Alternatively, you can expose a configuration file using the FRACTAL_FEATURE_EXPLORER_CONFIG environment variable:

export FRACTAL_FEATURE_EXPLORER_CONFIG=/path/to/config.toml
explorer

More details on the configuration file will be availble soon.

Local development setup

• pixi (lockfile create with pixi 0.47)
• local clone of this repo

running the dashboard

• using pixi task

  pixi run -e dev explorer-dev

• from streamlit directly

  pixi run streamlit run src/fractal_feature_explorer/main.py

Change log

See CHANGELOG.md for details on changes and updates.

URL query parameters

• setup_mode: either Plates or Images. This will determine the setup page of the dashboard.
• zarr_url: the URL of the zarr file to load.
• token: the fractal token to use for authentication (optional).

example URL: http://localhost:8501/?zarr_url=/Users/locerr/data/20200812-23well&?zarr_url=/Users/locerr/data/20200811-23well

Test data

• Small 2D (~100Mb)
• Small 2D (~100Mb) and 3D (~750Mb)
• Large 2D (~30Gb)
• Small data on public URL: https://raw.githubusercontent.com/tcompa/hosting-ome-zarr-on-github/refs/heads/main/20200812-CardiomyocyteDifferentiation14-Cycle1_mip.zarr

Main limitations

• Image preview is not available for 3D images.
• Single images not supported, only plates.

Troubleshooting

• pixi lock file not supported by your local pixi version:

  $ pixi run explorer
  × Failed to load lock file from `/xxx/fractal-feature-explorer/pixi.lock`
  ╰─▶ found newer lockfile format version 6, but only up to including version 5 is supported

  If you get an error like this you need to either update your local pixi version (pixi self-update) or create a new lock file with your local version of pixi. To do this, delete the pixi.lock, a new lock will be created when your run the dashboard again.

Contributing

Releasing a new version on PyPI:

1. Create a new local tag with the format vX.Y.Z, where X.Y.Z is the new version number.

   git tag v0.1.8 -m "v0.1.8"

2. Push the tag to the remote repository.

   git push --tags