first commit for first PR

.github/ISSUE_TEMPLATE/issue.yml

@@ -0,0 +1,46 @@
+# GitHub Issue template for bug reports
+name: Open a GitHub issue
+description: >
+  Please use this form to send along new ideas for content or
+  changes that might be helpful!
+
+body:
+  - type: checkboxes
+    attributes:
+      label: Is this a duplicate of an existing idea for this project?
+      description: >
+        Please make sure to search the existing issues first
+        to see whether the same issue was reported already.
+        If you find an existing issue, please don't hesitate to comment
+        on it or add a reaction to existing content!
+      options:
+        - label: >
+            I found no existing covering this topic.
+          required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What is your idea?
+      description: >
+        Please provide a specific description of what you'd like to see
+        including the context and what the result might look like.
+      placeholder: >
+        For example: "When x happens I see y.
+        The following might be a good way to address this ..."
+    validations:
+      required: true
+
+  - type: checkboxes
+    attributes:
+      label: Would you like to work on a solution for this?
+      description: >
+        This is a community-driven project and we
+        love new contributors (including through opening or adding to issues)!
+        This is an optional check to help us understand your interest to be
+        involved (especially if you already have a good understanding
+        of how to implement it).
+        We are happy to guide you in the contribution process and please
+        don't hesitate to reach out for help along the way.
+      options:
+        - label: Yes I am willing to submit a PR for this!

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+<!-- _modified from [EmbeddedArtistry](https://embeddedartistry.com/blog/2017/08/04/a-github-pull-request-template-for-your-projects/)_
+_referenced with modifications from [pycytominer](https://github.com/cytomining/pycytominer/blob/master/.github/PULL_REQUEST_TEMPLATE.md)_ -->
+
+# Description
+
+<!--
+Thank you so much for your contribution to this project!
+
+Please _succinctly_ summarize your proposed change.
+Namely, consider addressing the following questions:
+
+- What motivated you to open this pull request?
+- Were there any special adjustments you had to make to complete the work?
+- Are there any issues which are related to this pull request (you may used a `#<digit>` to reference GitHub issues as links within this description)?
+
+Also, if you haven't already, please use `pre-commit run --all-files` to help check your files using this project's pre-commit configuration.
+Pre-commit checks will automatically run as part of opening this pull request and we seek to ensure all checks pass before merging changes.
+-->
+
+## What kind of change(s) are included?
+
+- [ ] Documentation (changes docs or other related content)
+- [ ] Bug fix (fixes an issue).
+- [ ] Enhancement (adds functionality).
+- [ ] Breaking change (these changes would cause existing functionality to not work as expected).
+
+# Checklist
+
+Please ensure that all boxes are checked before indicating that this pull request is ready for review.
+
+- [ ] I have read and followed the [CONTRIBUTING.md](CONTRIBUTING.md) guidelines.
+- [ ] I have searched for existing content to ensure this is not a duplicate.
+- [ ] I have performed a self-review of these additions (including spelling, grammar, and related).
+- [ ] These changes pass all pre-commit checks.
+- [ ] I have added comments to my code to help provide understanding
+- [ ] I have added a test which covers the code changes found within this PR
+- [ ] I have deleted all non-relevant text in this pull request template.

.github/dependabot.yml

@@ -0,0 +1,36 @@
+---
+# GitHub Dependabot configuration
+# Note: there is no interaction between this
+# configuration and dependabot security updates.
+# See here for more information:
+# https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-dependabot-security-updates
+
+version: 2
+updates:
+  # GitHub Actions checks
+  # See here for more information:
+  # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "monthly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  # Perform checks and updates for python uv environment.
+  # This depends on changes to dependabot via:
+  # https://github.com/dependabot/dependabot-core/pull/10040
+  # See here for more information:
+  # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#pip-and-pip-compile
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      # Check for updates to uv environment files every week
+      interval: "monthly"
+    groups:
+      python-packages:
+        patterns:
+          - "*"

.github/release-drafter.yml

@@ -0,0 +1,21 @@
+---
+# template configuration for release-drafter
+# see: https://github.com/release-drafter/release-drafter
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+version-resolver:
+  major:
+    labels:
+      - 'release-major'
+  minor:
+    labels:
+      - 'release-minor'
+  patch:
+    labels:
+      - 'release-patch'
+  default: patch
+change-template: '- $TITLE (@$AUTHOR via #$NUMBER)'
+template: |
+  ## Changes
+
+  $CHANGES

.github/workflows/draft-release.yml

@@ -0,0 +1,23 @@
+---
+# workflow for drafting releases on GitHub
+# see: https://github.com/release-drafter/release-drafter
+name: release drafter
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  draft_release:
+    permissions:
+      # write permission is required to create a github release
+      contents: write
+      # write permission is required for autolabeler
+      # otherwise, read permission is required at least
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-docs.yml

@@ -0,0 +1,41 @@
+---
+# used for publishing documentation on push to main or published release
+name: publish docs
+
+on:
+  push:
+    branches:
+      - main
+  release:
+    types:
+      - published
+
+jobs:
+  build:
+    # only build and deploy docs if the actor is not dependabot
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build documentation
+        run: |
+          mkdir pages
+          touch pages/.nojekyll
+          cd docs
+          uv run --frozen sphinx-build src build
+          # remove any doctrees dirs which aren't needed for publishing
+          find ./build -type d -name '.doctrees' -exec rm -rf {} +
+          cp -r build/* ../pages/
+      - name: Deploy documentation
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: pages
+          folder: pages

.github/workflows/publish-pypi.yml

@@ -0,0 +1,33 @@
+---
+# used for publishing packages to pypi on release
+name: publish pypi release
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  publish_pypi:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Fetch tags
+        run: git fetch --all --tags
+      - name: Python setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+      - name: uv build distribution content
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/run-tests.yml

@@ -0,0 +1,66 @@
+---
+# used for running tests
+name: tests
+
+"on":
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  pre_commit_checks:
+    runs-on: ubuntu-24.04
+    steps:
+      # checks out the repo
+      - uses: actions/checkout@v4
+      # run pre-commit
+      - name: Python setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+      - uses: pre-commit/action@v3.0.1
+      # run pre-commit ci lite for automated fixes
+      - uses: pre-commit-ci/lite-action@v1.1.0
+        if: ${{ !cancelled() }}
+  run_tests:
+    strategy:
+      matrix:
+        python_version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        os: [ubuntu-24.04, macos-14]
+    runs-on: ${{ matrix.os }}
+    env:
+      OS: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Python setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python_version }}
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+      - name: Run pytest
+        run: uv run --frozen pytest
+  coverage_and_badge:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Python setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+      - name: Run coverage check and update badge
+        run: just coverage-check
+      - name: Verify coverage badge is up to date
+        run: |
+          git diff --exit-code README.md || {
+            echo "README coverage badge is out of date.";
+            echo "Run 'just coverage-check' and commit changes.";
+            exit 1;
+          }