omgutils 0.0.2

Python utils for OMG processing

omgutils

Python utils for OMG processing

This omgutils repo is a WIP. One day it might have and do the following:

• project and dependency management with uv

• unit and integration tests of the intended functionality, via with pytest

• GitHub Actions workflows for tests (CI)

• tagged releases on pypi

• GitHub Actions workflow for publishing tags to pypi (CI)

• Machado lab code for TIFF and OMG processing (currently subpackages of stepsutils)

• nice-to-read Python docstrings

• do we need to publish separate readthedocs docs?

  • clicking through to real code is often more informative
  • published docs are often incomplete and/or stale
  • how far can we get with one good README?
  • publishing docs might be a good thing to do, anyway

• notebooks to demonstrate preprocessing, similar to omg-preprocess

• notebooks to demonstrate motion correction, similar to omg-motion-correction

• installation, testing, getting started instructions

• links to small datasets / test fixtures

Here's an overview of the workflow that this repo might support.

editable diagram

Required and optional data inputs are in yellow boxes. Derived data products are in blue boxes. Diagnostic plots are in purple boxes.

The main processings steps (notebooks?) are in red boxes. Currently these mirror what we have in omg-preprocess and omg-motion-correction. Each of these contains many sub-steps, and the shape of these might want to evolve.

We should make our existing processing steps consume omgutils as a dependency so that we are not duplicating key code, and so that we are dogfooding.

We have oeg-preprocess code that also uses the AlignedTiff class in the stepsutils.tiff subpackage. OEG code could obtain the AlignedTiff dependency from omgutils. This should work find as a practical matter. But it would be slightly awkward to imply that OEG depends on OMG. To me this is the least bad option, though, as opposed to duplicating the common code, or creating ad managing a separate package like "tiffutils".

Dev bootstrapping notes

install uv locally

Init the project as a library

cd omgutils
uv init --lib

Reonfigure the build system in pyproject.toml because we'll want dynamic versioning on CI.

[build-system]
requires = ["hatchling", "uv-dynamic-versioning"]
build-backend = "hatchling.build"

Leave the src/omgutils/__init__.py there, but make it empty.

Add some hello world code so we can test something with pytest.

src/omgutils/hello/hello.py

import numpy as np


def hello(
    repetitions: int = 0
) -> list[str]:
    """Say "hello", repetitions times."""
    hellos = np.full((repetitions,), "hello", dtype=np.object_)
    return hellos

Add the numpy dependency

uv add 'numpy==2.4.6'

This declares the dependency in pyproject.toml. It also sets up a virtual environment for the project (.venv, git-ignored) and a uv.lock with explicit dependency versions.

Add a .gitignore

# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv

Configure dynamic versioning

We want the project version numbers to correspond to Git tags, as described here.

Edit the pyproject.toml

[project]
name = "omgutils"
dynamic = ["version"]

...

[tool.hatch.version]
source = "uv-dynamic-versioning"

Create an initial tag.

git tag v0.0.1

Check the build results.

uv build
ls dist
# omgutils-0.0.1-py3-none-any.whl  omgutils-0.0.1.tar.gz

Make the version available at runtime, in src/omgutils/__init__.py

import importlib.metadata

try:
    __version__ = importlib.metadata.version(__name__)
except importlib.metadata.PackageNotFoundError:
    __version__ = "0.0.0"  # Fallback for development mode

Try printing the version at runtime.

uv run python -c "import omgutils; print(omgutils.__version__)"
# 0.0.1

Dev test bootstrapping notes

Set up pytest and uv tooling, as described here

uv add --dev pytest

Create a few tests to run.

tests/omgutils/hello/test_hello.py

from omgutils.hello.hello import hello


def test_default_is_zero():
    hellos = hello()
    assert len(hellos) == 0

def test_ten():
    hellos = hello(10)
    assert len(hellos) == 10

Run the tests (uv run makes both pytest and omgutils available).

uv run pytest -v

Be able to run with coverage.

uv add --dev coverage

uv run coverage run -m pytest
uv run coverage report -m

Set up CI testing on gitHub actions has described here.