pkft 0.1.0a1__tar.gz

pkft-0.1.0a1/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+---
+name: Build and Check Docs
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+jobs:
+  docs:
+    name: Test on ${{ matrix.os }} with Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04]
+        python-version: ["3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install -r docs/requirements.txt
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+      - name: Upload docs as artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: html-docs-${{ matrix.os }}-python-${{ matrix.python-version }}
+          path: docs/_build/html
+          if-no-files-found: error

pkft-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,109 @@
+---
+name: Test and Release
+permissions:
+  contents: write
+  packages: write
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+jobs:
+  test:
+    name: Test on ${{ matrix.os }} with Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests and generate coverage report
+        run: |
+          pytest --cov=pkft --cov-branch --cov-report=xml
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1, node24 (v5 tag still nests github-script v7/node20)
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+  check-version:
+    name: Check if major or minor version
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    outputs:
+      is_major_minor: ${{ steps.check_tag.outputs.is_major_minor }}
+    steps:
+      - name: Check tag format
+        id: check_tag
+        run: |
+          TAG=${GITHUB_REF#refs/tags/}
+          VERSION=${TAG#v}
+          VERSION_CORE=$(echo $VERSION | cut -d'-' -f1 | cut -d'+' -f1)
+          IFS='.' read -ra VERSION_PARTS <<< "$VERSION_CORE"
+          if [[ ${#VERSION_PARTS[@]} -eq 3 && ${VERSION_PARTS[2]} != "0" ]]; then
+            echo "Tag $TAG is a patch version"
+            echo "is_major_minor=false" >> $GITHUB_OUTPUT
+          elif [[ "$VERSION" == *"-"* ]]; then
+            echo "Tag $TAG is a prerelease version"
+            echo "is_major_minor=false" >> $GITHUB_OUTPUT
+          else
+            echo "Tag $TAG is a major or minor version"
+            echo "is_major_minor=true" >> $GITHUB_OUTPUT
+          fi
+  build:
+    name: Build and Upload to PyPI
+    needs: check-version
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools wheel twine build setuptools-scm
+      - name: Verify version
+        run: python -m setuptools_scm
+      - name: Build distribution
+        run: |
+          rm -rf dist build *.egg-info
+          python -m build
+      - name: Check dist artifacts
+        run: |
+          ls -lh dist
+          test -f dist/*.whl
+          test -f dist/*.tar.gz
+      - name: Upload to Test PyPI
+        run: twine upload --verbose --repository-url https://test.pypi.org/legacy/ dist/*
+        env:
+          TWINE_USERNAME: "__token__"
+          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      - name: Upload to PyPI
+        run: twine upload --verbose dist/*
+        env:
+          TWINE_USERNAME: "__token__"
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      - name: Upload dist to GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          prerelease: ${{ needs.check-version.outputs.is_major_minor != 'true' }}

pkft-0.1.0a1/.gitignore

@@ -0,0 +1,9 @@
+**.DS_Store
+tmp/
+docs/_build/
+*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+.coverage
+coverage*.xml

pkft-0.1.0a1/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "printWidth": 150,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "endOfLine": "lf"
+}

pkft-0.1.0a1/.readthedocs.yaml

@@ -0,0 +1,17 @@
+---
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements: [dev]
+    - requirements: docs/requirements.txt

pkft-0.1.0a1/.ruff.toml

@@ -0,0 +1,5 @@
+line-length = 150
+target-version = "py310"
+
+[format]
+quote-style = "double"

pkft-0.1.0a1/.zenodo.json

@@ -0,0 +1,8 @@
+{
+  "title": "pkft: Peakfit Explorer",
+  "description": "A FastAPI service for Gaussian mixture peak finding in 1D data with uncertainties.",
+  "creators": [{ "name": "Kerswell, Buchanan" }],
+  "license": "MIT",
+  "keywords": ["peak-finding", "mixture-model", "uncertainty", "fastapi"],
+  "upload_type": "software"
+}

pkft-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Buchanan Kerswell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pkft-0.1.0a1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include pkft *.py
+recursive-include pkft/static *.html *.css *.js *.svg
+recursive-include pkft/data *.csv
+recursive-include tests *.py

pkft-0.1.0a1/Makefile

@@ -0,0 +1,97 @@
+# Top-level dirs
+PROJECT_ROOT := $(CURDIR)
+APP := $(PROJECT_ROOT)/pkft
+TESTS := $(PROJECT_ROOT)/tests
+DOCS := $(PROJECT_ROOT)/docs
+
+# Conda config
+CONDA_ENV_ID := pkft
+CONDA_ENV_YML := environment.yml
+CONDA_PYTHON = $$(conda run -n $(CONDA_ENV_ID) which python)
+
+# Server
+APP_MODULE := pkft.api:app
+
+# Targets
+.PHONY: run docs test format environment clean deep-clean
+
+all: environment test run
+
+run:
+	@$(CONDA_PYTHON) -m uvicorn $(APP_MODULE) --host 127.0.0.1 --port 8000 --reload
+
+# Cleanup directory
+CLEAN := $(APP)/**/__pycache__ $(APP)/**/*.pyc $(TESTS)/**/__pycache__ $(CURDIR)/.pytest_cache $(CURDIR)/build $(CURDIR)/dist $(CURDIR)/*.egg-info $(CURDIR)/.coverage $(CURDIR)/coverage.xml
+DEEP_CLEAN :=
+
+docs:
+	@$(MAKE) -C docs html
+
+test:
+	@$(CONDA_PYTHON) -m pytest --cov=pkft --cov-branch --cov-report=xml
+
+format:
+	@$(CONDA_PYTHON) -m ruff format .
+	@npx --yes prettier --write "pkft/static/*.js" "pkft/static/*.css"
+
+environment: $(CONDA_ENV_YML)
+	@if conda info --envs | awk '{print $$1}' | grep -qx "$(CONDA_ENV_ID)"; then \
+		echo "Environment '$$name' already exists. Skipping..."; \
+	else \
+		echo "Creating environment: $(CONDA_ENV_ID) from $(CONDA_ENV_YML)"; \
+		conda env create -n "$(CONDA_ENV_ID)" -f "$(CONDA_ENV_YML)"; \
+	fi
+
+clean:
+	@echo "==> Cleaning ..."
+	@for item in $(CLEAN); do \
+		safe_rm() { \
+			if [ -e "$$1" ]; then \
+				ABS_PATH=$$(realpath "$$1"); \
+				case "$$ABS_PATH" in \
+					$(PROJECT_ROOT)*) \
+						echo "-> Safely removing\n   $$ABS_PATH"; \
+						rm -rf "$$ABS_PATH";; \
+					*) \
+						echo "!! Skipping (outside project root)\n   $$ABS_PATH";; \
+				esac; \
+			else \
+				echo "-- Skipping (not found)\n   $$1"; \
+			fi; \
+		}; \
+		safe_rm "$$item"; \
+	done
+	@$(MAKE) -C docs clean || true
+	@find . -name ".DS_Store" -type f -delete
+
+deep-clean:
+	@echo "==> Deep cleaning ..."
+	@for item in $(DEEP_CLEAN); do \
+		safe_rm() { \
+			if [ -e "$$1" ]; then \
+				ABS_PATH=$$(realpath "$$1"); \
+				case "$$ABS_PATH" in \
+					$(PROJECT_ROOT)*) \
+						echo "-> Safely removing\n   $$ABS_PATH"; \
+						rm -rf "$$ABS_PATH";; \
+					*) \
+						echo "!! Skipping (outside project root)\n   $$ABS_PATH";; \
+				esac; \
+			else \
+				echo "-- Skipping (not found)\n   $$1"; \
+			fi; \
+		}; \
+		safe_rm "$$item"; \
+	done
+
+
+help:
+	@echo "Available targets:"
+	@echo "  run          Run pkft app locally"
+	@echo "  docs         Build documentation"
+	@echo "  test         Run unit tests"
+	@echo "  format       Format code to 150 columns (ruff + prettier)"
+	@echo "  environment  Create Conda environment"
+	@echo "  clean        Cleanup unnecessary files and directories (safe)"
+	@echo "  deep-clean   Deep clean figures and results (use with caution!)"
+	@echo "  help         Show this help message"

pkft-0.1.0a1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: pkft
+Version: 0.1.0a1
+Summary: A FastAPI service for Gaussian mixture peak finding in 1D geochronological data
+Author-email: Buchanan Kerswell <buck.kerswell@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/buchanankerswell/pkft
+Classifier: Natural Language :: English
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: pydantic>=2.0
+Requires-Dist: numpy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# pkft: Peakfit Explorer
+
+📚 See the [documentation](https://pkft.readthedocs.io/en/latest/) for details.
+
+Peak finding for 1D data with uncertainties by discrete Gaussian mixture
+modelling (Galbraith & Laslett, 1993) in the spirit of IsoplotR
+`peakfit` (Vermeesch, 2018), served as a FastAPI service with a minimal
+dependency-free web UI.
+
+![Peakfit demo](assets/images/repo-banner.png)
+
+*Figure: mixture fit for the bundled Trayler et al. 2020 demo dataset.*
+
+## Prerequisite software
+
+This project is written in [python](https://www.python.org). For most users, I recommend installing the [miniforge](https://github.com/conda-forge/miniforge) python distribution. This distributions includes a minimal installation of python and the package manager [conda](https://docs.conda.io/en/latest/), which is required to build the necessary python environment for this software.
+
+For macOS users, miniforge can be installed with [homebrew](https://brew.sh):
+
+```bash
+brew install miniforge
+```
+
+For Window's users, miniforge can be installed from a binary .exe. Follow the instructions for miniconda, anaconda, or miniforge (recommended) [here](https://docs.conda.io/projects/conda/en/stable/user-guide/install/windows.html).
+
+## Installation Guide
+
+To install with Conda (recommended):
+
+``` bash
+# Create conda environment
+conda create -n pkft python=3.13 pip
+
+# Activate conda environment
+conda activate pkft
+
+# Install pkft
+pip install pkft
+```
+
+If you want to install the development version for local testing in "editable" mode:
+
+``` bash
+# Clone repo
+git clone https://github.com/buchanankerswell/pkft.git
+cd pkft
+
+# Checkout develop branch
+git checkout develop
+
+# Create conda environment and install pkft locally in editable mode
+# including optional development and documentation dependencies
+make environment
+```
+
+## Usage Guide
+
+After installing pkft using either method above, launch the server from the command line:
+
+``` bash
+# Activate conda environment
+conda activate pkft
+
+# Launch server (UI at http://127.0.0.1:8000/)
+pkft
+```
+
+The same JSON serves browsers and agents:
+
+``` bash
+curl -X POST http://127.0.0.1:8000/fit \
+  -H 'Content-Type: application/json' \
+  -d '{"observations": [{"value": 17.634, "standard_error": 0.016}], "peak_count": 1}'
+```
+
+Open http://127.0.0.1:8000/ for the data explorer, http://127.0.0.1:8000/mixture for the mixture tab, or click **Load demo** for the bundled Trayler et al. 2020 dataset.
+
+## Method
+
+Each observation `x[i]` with analytical variance `s[i]**2` contributes
+`sum_j pi[j] * N(x[i] | mu[j], s[i]**2)` to the likelihood (Galbraith &
+Laslett, 1993, discrete mixture; IsoplotR `peakfit` with `log=FALSE`).
+Expectation–maximisation (10 restarts) maximises the log-likelihood;
+`peak_count = 0` selects 1..5 components by BIC. Results maximise
+the same likelihood as IsoplotR `peakfit` with `log=FALSE`, with small
+numerical differences from the different optimiser and starting points.
+See the docs for the full API reference.
+
+## Citation
+
+Cite the app as Kerswell, B. (2023). Peakfit Explorer.
+https://doi.org/10.17605/OSF.IO/2BU3C
+
+## Acknowledgement
+
+I gratefully acknowledge feedback and suggestions provided by
+[Matthew Kohn](https://scholar.google.com/citations?user=xSyB1KQAAAAJ&hl=en&oi=ao)
+and [Kayleigh Harvey](https://www.linkedin.com/in/kayleigh-harvey-phd-98471952).
+Peak modelling follows [IsoplotR](https://github.com/pvermees/IsoplotR/)
+(Vermeesch, 2018); demo data from Trayler et al. (2020).
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

pkft-0.1.0a1/README.md

@@ -0,0 +1,104 @@
+# pkft: Peakfit Explorer
+
+📚 See the [documentation](https://pkft.readthedocs.io/en/latest/) for details.
+
+Peak finding for 1D data with uncertainties by discrete Gaussian mixture
+modelling (Galbraith & Laslett, 1993) in the spirit of IsoplotR
+`peakfit` (Vermeesch, 2018), served as a FastAPI service with a minimal
+dependency-free web UI.
+
+![Peakfit demo](assets/images/repo-banner.png)
+
+*Figure: mixture fit for the bundled Trayler et al. 2020 demo dataset.*
+
+## Prerequisite software
+
+This project is written in [python](https://www.python.org). For most users, I recommend installing the [miniforge](https://github.com/conda-forge/miniforge) python distribution. This distributions includes a minimal installation of python and the package manager [conda](https://docs.conda.io/en/latest/), which is required to build the necessary python environment for this software.
+
+For macOS users, miniforge can be installed with [homebrew](https://brew.sh):
+
+```bash
+brew install miniforge
+```
+
+For Window's users, miniforge can be installed from a binary .exe. Follow the instructions for miniconda, anaconda, or miniforge (recommended) [here](https://docs.conda.io/projects/conda/en/stable/user-guide/install/windows.html).
+
+## Installation Guide
+
+To install with Conda (recommended):
+
+``` bash
+# Create conda environment
+conda create -n pkft python=3.13 pip
+
+# Activate conda environment
+conda activate pkft
+
+# Install pkft
+pip install pkft
+```
+
+If you want to install the development version for local testing in "editable" mode:
+
+``` bash
+# Clone repo
+git clone https://github.com/buchanankerswell/pkft.git
+cd pkft
+
+# Checkout develop branch
+git checkout develop
+
+# Create conda environment and install pkft locally in editable mode
+# including optional development and documentation dependencies
+make environment
+```
+
+## Usage Guide
+
+After installing pkft using either method above, launch the server from the command line:
+
+``` bash
+# Activate conda environment
+conda activate pkft
+
+# Launch server (UI at http://127.0.0.1:8000/)
+pkft
+```
+
+The same JSON serves browsers and agents:
+
+``` bash
+curl -X POST http://127.0.0.1:8000/fit \
+  -H 'Content-Type: application/json' \
+  -d '{"observations": [{"value": 17.634, "standard_error": 0.016}], "peak_count": 1}'
+```
+
+Open http://127.0.0.1:8000/ for the data explorer, http://127.0.0.1:8000/mixture for the mixture tab, or click **Load demo** for the bundled Trayler et al. 2020 dataset.
+
+## Method
+
+Each observation `x[i]` with analytical variance `s[i]**2` contributes
+`sum_j pi[j] * N(x[i] | mu[j], s[i]**2)` to the likelihood (Galbraith &
+Laslett, 1993, discrete mixture; IsoplotR `peakfit` with `log=FALSE`).
+Expectation–maximisation (10 restarts) maximises the log-likelihood;
+`peak_count = 0` selects 1..5 components by BIC. Results maximise
+the same likelihood as IsoplotR `peakfit` with `log=FALSE`, with small
+numerical differences from the different optimiser and starting points.
+See the docs for the full API reference.
+
+## Citation
+
+Cite the app as Kerswell, B. (2023). Peakfit Explorer.
+https://doi.org/10.17605/OSF.IO/2BU3C
+
+## Acknowledgement
+
+I gratefully acknowledge feedback and suggestions provided by
+[Matthew Kohn](https://scholar.google.com/citations?user=xSyB1KQAAAAJ&hl=en&oi=ao)
+and [Kayleigh Harvey](https://www.linkedin.com/in/kayleigh-harvey-phd-98471952).
+Peak modelling follows [IsoplotR](https://github.com/pvermees/IsoplotR/)
+(Vermeesch, 2018); demo data from Trayler et al. (2020).
+
+## License
+
+MIT License — see [LICENSE](LICENSE).

pkft-0.1.0a1/docs/Makefile

@@ -0,0 +1,42 @@
+# Top-level dirs
+PROJECT_ROOT := $(realpath $(dir $(lastword $(MAKEFILE_LIST)))/..)
+DOCS := $(PROJECT_ROOT)/docs
+
+# Python config
+SPHINX_BUILD := sphinx-build
+
+# Sphinx build
+SPHINX_OPTS ?=
+SOURCE_DIR := $(DOCS)
+BUILD_DIR := $(DOCS)/_build
+
+# Cleanup directory
+CLEAN := $(BUILD_DIR)/*
+
+# Targets
+.PHONY: help Makefile
+
+help:
+	@$(SPHINX_BUILD) -M help "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINX_OPTS) $(O)
+
+%: Makefile
+	@$(SPHINX_BUILD) -M $@ "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINX_OPTS) $(O)
+
+clean:
+	@for item in $(CLEAN); do \
+		safe_rm() { \
+			if [ -e "$$1" ]; then \
+				ABS_PATH=$$(realpath "$$1"); \
+				case "$$ABS_PATH" in \
+					$(PROJECT_ROOT)*) \
+						echo "-> Safely removing\n   $$ABS_PATH"; \
+						rm -rf "$$ABS_PATH";; \
+					*) \
+						echo "!! Skipping (outside project root)\n   $$ABS_PATH";; \
+				esac; \
+			else \
+				echo "-- Skipping (not found)\n   $$1"; \
+			fi; \
+		}; \
+		safe_rm "$$item"; \
+	done