comfort-db 0.1.0__tar.gz

comfort_db-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yvonne Jenniges, Universität Bremen
+
+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.

comfort_db-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include test *.py

comfort_db-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: comfort-db
+Version: 0.1.0
+Summary: Helper library for working with the COMFORT oceanographic dataset (SQLite)
+Author: Are Olsen, Boris Peter Koch, Sebastian Maneth
+Author-email: Yvonne Jenniges <yvonne.jenniges@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/y-jenniges/comfort-db
+Project-URL: Issues, https://github.com/y-jenniges/comfort-db/issues
+Project-URL: Documentation, https://comfort-db.readthedocs.io/en/latest/
+Keywords: oceanography,data-exploration,data-analysis,COMFORT,SQLite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: gsw>=3.6.16
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8.1; extra == "plot"
+Requires-Dist: seaborn>=0.13; extra == "plot"
+Provides-Extra: geo
+Requires-Dist: shapely>=2.0; extra == "geo"
+Requires-Dist: geopandas>=0.14.4; extra == "geo"
+Requires-Dist: cartopy>=0.22; extra == "geo"
+Provides-Extra: grid
+Requires-Dist: xarray>=2023.1; extra == "grid"
+Requires-Dist: netcdf4>=1.6; extra == "grid"
+Provides-Extra: scale
+Requires-Dist: scikit-learn>=1.2; extra == "scale"
+Provides-Extra: dash
+Requires-Dist: dash>=2.14; extra == "dash"
+Requires-Dist: dash-bootstrap-components>=1.5; extra == "dash"
+Requires-Dist: plotly>=5.18; extra == "dash"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: comfort-db[plot]; extra == "all"
+Requires-Dist: comfort-db[geo]; extra == "all"
+Requires-Dist: comfort-db[grid]; extra == "all"
+Requires-Dist: comfort-db[scale]; extra == "all"
+Requires-Dist: comfort-db[dash]; extra == "all"
+Requires-Dist: comfort-db[docs]; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
+Requires-Dist: openpyxl>=3.1; extra == "test"
+Provides-Extra: dev
+Requires-Dist: comfort-db[all]; extra == "dev"
+Requires-Dist: comfort-db[test]; extra == "dev"
+Dynamic: license-file
+
+# comfort-db
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/y-jenniges/comfort-db/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![Documentation Status](https://img.shields.io/readthedocs/comfort-db)](https://comfort-db.readthedocs.io/en/latest/)
+
+Python library for working with the [COMFORT](https://www.doi.org/10.11582/2022.00039)[1] oceanographic SQLite dataset 
+with [code documentation](https://comfort-db.readthedocs.io/en/latest/). 
+
+`comfort-db` wraps database access, preprocessing and basic analysis utilities into one library. 
+This includes filtering for quality and space-time ranges, unit conversions, spatiotemporal gridding, profile and water-mass analysis, 
+geospatial utilities, scaling, plotting and visualisation using a dashboard.
+
+The data structure broadly follows oceanographic ship measurement practice: 
+At a latitude, longitude and time, a station defines where measurements were taken.
+At a station, profiles are measured, i.e. a parameter like temperature at different depths with a specific instrument.
+There can be multiple profiles at the same station, though in the COMFORT dataset, it is mostly one profile per station. 
+
+This library bases on and extends code developed in [2], including parts of the gridding, unit conversion, analysis and plotting 
+routines.
+
+[1] Korablev, A., Olsen, A., (2022) Geophysical Institute, University of Bergen, Bjerknes Centre for Climate Research. COMFORT Dataset [Data set]. NIRD RDA. https://doi.org/10.11582/2022.00039
+
+[2] Jenniges, Y., Sonnewald, M., Maneth, S., Olsen, A., Koch, Boris P., (2025) Unveiling 3D ocean biogeochemical provinces in the North Atlantic: 
+A systematic comparison and validation of clustering methods, Ecological Informatics, Volume 91, 103390, ISSN 1574-9541,
+https://doi.org/10.1016/j.ecoinf.2025.103390.
+
+---
+
+## Installation
+
+```bash
+pip install comfort-db
+```
+
+Optional extras add more specialised functionality:
+
+| Extra | Adds | Enables                                               |
+|---|---|-------------------------------------------------------|
+| `plot` | matplotlib, seaborn | `comfort.plot`                                        |
+| `geo` | shapely, geopandas, cartopy | Water masses, Longhurst provinces, coastline distance (`distance_to_coast`) |
+| `grid` | xarray, netcdf4 | Spatio-temporal gridding, bathymetry masking, biome classification (`load_biomes`), xarray output |
+| `scale` | scikit-learn | `ParamScaler`                                         |
+| `dash` | dash, plotly | Interactive Dash explorer app                         |
+| `docs` | sphinx, sphinx-rtd-theme | Building the documentation locally                    |
+| `all` | everything above |                                                       |
+
+Install via e.g.
+
+```bash
+pip install "comfort-db[geo,plot]"
+```
+
+**From source (editable, for development):**
+
+```bash
+git clone https://github.com/y-jenniges/comfort-db.git
+cd comfort-db
+pip install -e ".[dev]"
+```
+
+To build the documentation locally:
+
+```bash
+sphinx-build documentation/source documentation/build/html
+```
+
+Requires Python 3.10 or newer.
+
+---
+
+## Quick start
+
+```python
+import comfort
+
+# Overview of the database (no data loaded, takes some minutes)
+comfort.info("/path/to/comfort.sqlite")
+
+# Filter at SQL level, get back one DataFrame per parameter
+# (output="xarray" returns an xarray Dataset and needs the `grid` extra)
+data = comfort.load_comfort(
+    "/path/to/comfort.sqlite",
+    parameters=["NITRATE", "DIC"],
+    quality_flags=comfort.QC_GOOD,  # quality filter
+    lat_min=30, lat_max=70,  # latitude filter
+    date_min="2000-01-01 00:00:00",  # date filter, format YYYY-MM-DD HH:MM:SS
+    target_depths=[0, 50, 100, 200, 500, 1000],  # depth interpolation
+    limit=500_000,  # first 500,000 rows per parameter (a warning is logged if rows are cut)
+    output="dict",
+)
+
+# Table exploration
+with comfort.connect("/path/to/comfort.sqlite") as conn:
+    summary = comfort.describe_variables(conn, parameters=["NITRATE", "DIC"], quality_flags=comfort.QC_GOOD)
+```
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+
+# Include the bathymetry test (needs a GEBCO NetCDF file)
+export BATHYMETRY_PATH=/path/to/gebco_bathymetry.nc
+pytest
+```
+
+---
+
+## Citing
+
+If you use `comfort-db` in published work, please cite the COMFORT dataset [1] and this library: 
+```bibtex
+@article{jenniges_inprep,
+    author = {Yvonne Jenniges and Are Olsen and Boris Peter Koch and Sebastian Maneth},
+    title = {{comfort-db}: A Python toolkit to access, preprocess and explore the oceanographic COMFORT dataset},
+    journal = {Journal of Open Source Software},
+    year = {in prep.},
+}
+```
+
+## License
+
+MIT

comfort_db-0.1.0/README.md

@@ -0,0 +1,127 @@
+# comfort-db
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/y-jenniges/comfort-db/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![Documentation Status](https://img.shields.io/readthedocs/comfort-db)](https://comfort-db.readthedocs.io/en/latest/)
+
+Python library for working with the [COMFORT](https://www.doi.org/10.11582/2022.00039)[1] oceanographic SQLite dataset 
+with [code documentation](https://comfort-db.readthedocs.io/en/latest/). 
+
+`comfort-db` wraps database access, preprocessing and basic analysis utilities into one library. 
+This includes filtering for quality and space-time ranges, unit conversions, spatiotemporal gridding, profile and water-mass analysis, 
+geospatial utilities, scaling, plotting and visualisation using a dashboard.
+
+The data structure broadly follows oceanographic ship measurement practice: 
+At a latitude, longitude and time, a station defines where measurements were taken.
+At a station, profiles are measured, i.e. a parameter like temperature at different depths with a specific instrument.
+There can be multiple profiles at the same station, though in the COMFORT dataset, it is mostly one profile per station. 
+
+This library bases on and extends code developed in [2], including parts of the gridding, unit conversion, analysis and plotting 
+routines.
+
+[1] Korablev, A., Olsen, A., (2022) Geophysical Institute, University of Bergen, Bjerknes Centre for Climate Research. COMFORT Dataset [Data set]. NIRD RDA. https://doi.org/10.11582/2022.00039
+
+[2] Jenniges, Y., Sonnewald, M., Maneth, S., Olsen, A., Koch, Boris P., (2025) Unveiling 3D ocean biogeochemical provinces in the North Atlantic: 
+A systematic comparison and validation of clustering methods, Ecological Informatics, Volume 91, 103390, ISSN 1574-9541,
+https://doi.org/10.1016/j.ecoinf.2025.103390.
+
+---
+
+## Installation
+
+```bash
+pip install comfort-db
+```
+
+Optional extras add more specialised functionality:
+
+| Extra | Adds | Enables                                               |
+|---|---|-------------------------------------------------------|
+| `plot` | matplotlib, seaborn | `comfort.plot`                                        |
+| `geo` | shapely, geopandas, cartopy | Water masses, Longhurst provinces, coastline distance (`distance_to_coast`) |
+| `grid` | xarray, netcdf4 | Spatio-temporal gridding, bathymetry masking, biome classification (`load_biomes`), xarray output |
+| `scale` | scikit-learn | `ParamScaler`                                         |
+| `dash` | dash, plotly | Interactive Dash explorer app                         |
+| `docs` | sphinx, sphinx-rtd-theme | Building the documentation locally                    |
+| `all` | everything above |                                                       |
+
+Install via e.g.
+
+```bash
+pip install "comfort-db[geo,plot]"
+```
+
+**From source (editable, for development):**
+
+```bash
+git clone https://github.com/y-jenniges/comfort-db.git
+cd comfort-db
+pip install -e ".[dev]"
+```
+
+To build the documentation locally:
+
+```bash
+sphinx-build documentation/source documentation/build/html
+```
+
+Requires Python 3.10 or newer.
+
+---
+
+## Quick start
+
+```python
+import comfort
+
+# Overview of the database (no data loaded, takes some minutes)
+comfort.info("/path/to/comfort.sqlite")
+
+# Filter at SQL level, get back one DataFrame per parameter
+# (output="xarray" returns an xarray Dataset and needs the `grid` extra)
+data = comfort.load_comfort(
+    "/path/to/comfort.sqlite",
+    parameters=["NITRATE", "DIC"],
+    quality_flags=comfort.QC_GOOD,  # quality filter
+    lat_min=30, lat_max=70,  # latitude filter
+    date_min="2000-01-01 00:00:00",  # date filter, format YYYY-MM-DD HH:MM:SS
+    target_depths=[0, 50, 100, 200, 500, 1000],  # depth interpolation
+    limit=500_000,  # first 500,000 rows per parameter (a warning is logged if rows are cut)
+    output="dict",
+)
+
+# Table exploration
+with comfort.connect("/path/to/comfort.sqlite") as conn:
+    summary = comfort.describe_variables(conn, parameters=["NITRATE", "DIC"], quality_flags=comfort.QC_GOOD)
+```
+
+---
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+
+# Include the bathymetry test (needs a GEBCO NetCDF file)
+export BATHYMETRY_PATH=/path/to/gebco_bathymetry.nc
+pytest
+```
+
+---
+
+## Citing
+
+If you use `comfort-db` in published work, please cite the COMFORT dataset [1] and this library: 
+```bibtex
+@article{jenniges_inprep,
+    author = {Yvonne Jenniges and Are Olsen and Boris Peter Koch and Sebastian Maneth},
+    title = {{comfort-db}: A Python toolkit to access, preprocess and explore the oceanographic COMFORT dataset},
+    journal = {Journal of Open Source Software},
+    year = {in prep.},
+}
+```
+
+## License
+
+MIT

comfort_db-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+# Build instructions
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+# Metadata and requirements
+[project]
+name = "comfort-db"
+dynamic = ["version"]  # read from comfort.__version__, see [tool.setuptools.dynamic]
+description = "Helper library for working with the COMFORT oceanographic dataset (SQLite)"
+authors = [
+    { name = "Yvonne Jenniges", email = "yvonne.jenniges@gmail.com" },
+    { name = "Are Olsen" },
+    { name = "Boris Peter Koch" },
+    { name = "Sebastian Maneth" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["oceanography", "data-exploration", "data-analysis", "COMFORT", "SQLite"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.23",
+    "pandas>=2.0",
+    "scipy>=1.10",
+    "gsw>=3.6.16",
+    "python-dateutil>=2.8.2",
+    "python-dotenv>=1.0",
+]
+
+# Optional dependencies
+[project.optional-dependencies]
+plot = [
+    "matplotlib>=3.8.1",
+    "seaborn>=0.13",
+]
+geo = [
+    "shapely>=2.0",
+    "geopandas>=0.14.4",
+    "cartopy>=0.22",
+]
+grid = [
+    "xarray>=2023.1",
+    "netcdf4>=1.6",
+]
+scale = [
+    "scikit-learn>=1.2",
+]
+dash = [
+    "dash>=2.14",
+    "dash-bootstrap-components>=1.5",
+    "plotly>=5.18",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme>=2.0",
+]
+all = [
+    "comfort-db[plot]",
+    "comfort-db[geo]",
+    "comfort-db[grid]",
+    "comfort-db[scale]",
+    "comfort-db[dash]",
+    "comfort-db[docs]",
+]
+test = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "openpyxl>=3.1",
+]
+dev = [
+    "comfort-db[all]",
+    "comfort-db[test]",
+]
+
+# Links shown on PyPI
+[project.urls]
+Repository = "https://github.com/y-jenniges/comfort-db"
+Issues = "https://github.com/y-jenniges/comfort-db/issues"
+Documentation = "https://comfort-db.readthedocs.io/en/latest/"
+
+# Directory of packages
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Single source of the version: Read from src/comfort/__init__.py
+[tool.setuptools.dynamic]
+version = { attr = "comfort.__version__" }
+
+# Test suite settings
+[tool.pytest.ini_options]
+testpaths = ["test"]  # test dir
+pythonpath = ["src"]  # source dir
+tmp_path_retention_policy = "failed"  # only keep temp dirs if tests fail
+markers = [
+    "needs_bathymetry: Tests that require a real bathymetry NetCDF file (skipped by default)",
+]  # register bathymetry marker

comfort_db-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

comfort_db-0.1.0/src/comfort/__init__.py

@@ -0,0 +1,35 @@
+"""comfort-db - helper library for the COMFORT oceanographic dataset."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .io import (
+    connect,
+    describe_variables,
+    info,
+    list_parameters,
+    load_comfort,
+    read_parameter,
+    read_station,
+    subset_region,
+)
+from .qc import QC_ALL, QC_GOOD, QCFilter
+from .gridding import Grid
+from .units import UnitsConverter
+
+__all__ = [
+    "__version__",
+    "connect",
+    "describe_variables",
+    "info",
+    "list_parameters",
+    "load_comfort",
+    "read_parameter",
+    "read_station",
+    "subset_region",
+    "QC_ALL",
+    "QC_GOOD",
+    "QCFilter",
+    "Grid",
+    "UnitsConverter",
+]

comfort_db-0.1.0/src/comfort/app/__init__.py

@@ -0,0 +1,2 @@
+"""Dash web applications for exploring COMFORT data."""
+from __future__ import annotations

comfort_db-0.1.0/src/comfort/app/__main__.py

@@ -0,0 +1,9 @@
+"""Launch the COMFORT Data Explorer app.
+
+Usage:
+    python -m comfort.app
+"""
+from __future__ import annotations
+from .explorer import main
+
+main()