ipyniivue

A Jupyter Widget for Niivue based on anywidget.

Installation

Install ipyniivue using pip:

pip install ipyniivue

Usage

In a Jupyter environment:

from ipyniivue import NiiVue

nv = NiiVue()
nv.load_volumes([{"path": "images/mni152.nii.gz"}])
nv

This will render an interactive Niivue widget within your notebook.

See the basic demo to learn more.

Documentation

See the Documentation for usage.

Development

ipyniivue uses the recommended hatchling build system, which is convenient to use via the hatch CLI. We recommend installing hatch globally (e.g., via pipx) and running the various commands defined within pyproject.toml. hatch will take care of creating and synchronizing a virtual environment with all dependencies defined in pyproject.toml.

Command Cheat Sheet

Run these commands from the root of the project:

Alternatively, you can manually create a virtual environment and manage installation and dependencies with pip:

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Making Changes to the JavaScript Code

This is an anywidget project, meaning the codebase is a hybrid of Python and JavaScript. The JavaScript code resides under the js/ directory and uses esbuild for bundling. Whenever you make changes to the JavaScript code, you need to rebuild the files under src/ipyniivue/static.

You have two options:

1. Build Once: Build the JavaScript code one time:

   npm run build
   

2. Start Development Server: Start a development server that automatically rebuilds the code as you make changes:

   npm run dev
   

   We recommend this approach for a smoother development experience.

Working with Jupyter

Once the development server is running, you can start JupyterLab or Visual Studio Code to develop the widget. When you're finished, stop the development server with Ctrl+C.

Note: To have anywidget automatically apply changes as you work, set the environment variable ANYWIDGET_HMR=1. You can set this directly in a notebook cell:

%env ANYWIDGET_HMR=1

or in the shell:

export ANYWIDGET_HMR=1

Release Process

Releases are automated using GitHub Actions via the release.yml workflow.

Steps to Create a New Release

1. Commit Changes: Ensure all your changes are committed.

2. Create a Tag: Create a new tag matching the pattern v*:

   git tag -a vX.X.X -m "vX.X.X"
   git push --follow-tags
   

3. Workflow Actions: When triggered, the workflow will:

   • Publish the package to PyPI with the tag version.
   • Generate a changelog based on conventional commits.
   • Create a GitHub Release with the changelog.

Changelog Generation

• We generate a changelog for GitHub releases with antfu/changelogithub.
• Each changelog entry is grouped and rendered based on conventional commits.
• It's recommended to follow the Conventional Commits specification.