fractal-feature-explorer

This is the repository that contains the Fractal feature explorer dashboard. Find more information about Fractal in general and the other repositories at the Fractal home page.

Run the dashboard locally

Examples:

1. Via uvx:

uvx --from fractal-feature-explorer explorer

2. Via pipx:

pipx run --spec fractal-feature-explorer explorer

3. Via uv:

git clone https://github.com/fractal-analytics-platform/fractal-feature-explorer.git
cd fractal-feature-explorer
uv run explorer

4. Via venv+pip:

git clone https://github.com/fractal-analytics-platform/fractal-feature-explorer.git
cd fractal-feature-explorer
python3 -m venv venv
source ./venv/bin/activate
python3 -m pip install -e .
explorer

Run the dashboard on a remote server

The most common option is to create a virtual environment and install via pip, and then run via uvicorn

python3 -m venv venv

source venv/bin/activate

pip install fractal-feature-explorer

export FRACTAL_FEATURE_EXPLORER_CONFIG="config.toml"

uvicorn \
    fractal_feature_explorer.app:app\
    --no-server-header \
    --host 0.0.0.0 \
    --port 8501 \

Configuration-file examples:

• config.toml
• .streamlit/config.toml

Develoment

# Clone this repository
git clone https://github.com/fractal-analytics-platform/fractal-feature-explorer.git
cd fractal-feature-explorer
# Install the project via uv
uv sync
# Run the app
export FRACTAL_FEATURE_EXPLORER_CONFIG=./example-config-files/development-config.toml
uv run uvicorn fractal_feature_explorer.app:app --host 0.0.0.0 --port 8501

Note that this development-config.toml simulates a production deployment and thus it requires Fractal services running locally on a given set of ports (fractal-server on port 8000, fractal-web on port 5173, fractal-data on port 3000).

If you do not need all of this, run via

export FRACTAL_FEATURE_EXPLORER_CONFIG=./example-config-files/local-config.toml
uv run uvicorn fractal_feature_explorer.app:app --host 0.0.0.0 --port 8501

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.

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
   

License and contributors

The Fractal project is developed by the BioVisionCenter at the University of Zurich, who contracts eXact lab s.r.l. for software engineering and development support.

Unless otherwise specified, Fractal components are released under the BSD 3-Clause License, and copyright is with the BioVisionCenter at the University of Zurich.