merge: release 1.0.5 (#10)

* docs: modify rtd configuration

Refs: ST-2, ST-122

* docs: fix rtd configuration

Corrects package installation path.

Refs: ST-2, ST-122

* fix: main interface references incorrect arguments

Refs: ST-26, ST-123

* feat(metrics): perform regression on datasets

Adds method to MetricsFlux to perform regression on labelled data.

Refs: ST-7, ST-106

* tests(metrics): generate datetime index for series

Refs: ST-3, ST-7, ST-106

* feat(visuals): plot scatter with optional regression line

Creates scatter plot with optional regression line and optional
annotation for the coefficient of determination.

Refs: ST-3, ST-8, ST-106

* refactor!: plots from metrics calculations are paired into lists

Matplotlib plots generated by methods in metrics_calculations are now
structured as list[tuple[plt.Figure, plt.Axes]] instead of stacked
into a single tuple.

Refs: ST-3, ST-7, ST-8, ST-124, ST-126

* feat(metrics): calculate, plot, save regression between data

Adds ability to plot and save regression between calculated fluxes and
innFLUX data.

Fixes some incorrect test conditions which led to tests being skipped.

Refs: ST-3, ST-7, ST-8, ST-106, ST-107

* refactor: minor docstring and logic fixes

Begins:
    - ST-126: Deprecate FigurePlotter.plot_iterated_fluxes in favour of
      plot_iterated_metrics

Refs: ST-3, ST-7, ST-8

* refactor: begin deprecating FigurePlotter.plot_iterated_fluxes

Begins deprecation of FigurePlotter.plot_iterated_fluxes in favour
of MetricsFlux.plot_iterated_metrics.

The former method is redundant.

Refs: ST-7, ST-8, ST-126

* fix(tests): fix incorrect type hinting in conftest

Refs: ST-3

* fix: add scikit-learn to project requirements

Refs: ST-1

* fix: fix broken syntax in pyproject.toml

Refs: ST-1

* merge: merge branch feat-ST127-refactor-project with develop (#8)

* refactor: minor docstring fixes

Refs: ST-2, ST-127

* refactor: update README

Refs: ST-2, ST-127

* refactor: minor efficiency fixes

Refs: ST-2, ST-5, ST-7, ST-127

* refactor: minor updates to test logic

Refs: ST-3, ST-127

* refactor: improve code legibility in main

Refs: ST-26, ST-127

* fix: remove unsupported type hinting

Refs: ST-3, ST-127

Refs: ST-1, ST-127

* merge: merge feat-ST128-deprecations module (#9)

* feat(backed): add decorators for deprecating objects

Call the decorator with:

    from scintillometry.backend.deprecations import Decorators

    @Decorators.deprecated(stage="...", reason="...", version="...")
    def some_function(foo=...):
        ...

Refs: ST-3, ST-6, ST-128

* feat(backend): deprecate individual arguments

Adds method to deprecate individual function arguments.

```
from scintillometry.backend.deprecations import Decorators

@Decorators.deprecated_argument(stage, old_argument="new_argument")
def some_function(new_argument):
    ...
```

Refs: ST-3, ST-6, ST-128

* refactor(visuals): start deprecating plot_iterated_fluxes

Marks `plot_iterated_fluxes` as pending deprecation. This function is
superseded by `MetricsFlux.plot_iterated_metrics`.

Refs: ST-3, ST-8, ST-126

* refactor(metrics): deprecate argument in plot_iterated_metrics

Marks `site_location` as pending deprecation. Argument is replaced by
`location`.

Refs: ST-3, ST-7, ST-126

* docs(metrics): updates docstring noting deprecation

Refs: ST-2, ST-126

* build: toml license refers to name instead of file

Refs: ST-1, ST-2

* fix: incorrect toml syntax

Refs: ST-1

---------

Signed-off-by: gampnico <45390064+gampnico@users.noreply.github.com>

README.md

@@ -16,11 +16,11 @@ limitations under the License. -->
 
 [![Pytest and Flake8](https://github.com/gampnico/scintillometry/actions/workflows/python-app.yml/badge.svg?branch=main)](https://github.com/gampnico/scintillometry/actions/workflows/python-app.yml)
 
-Analyse data & 2D flux footprints from Scintec's BLS scintillometers.
+Development branch: [![Pytest and Linting](https://github.com/gampnico/scintillometry/actions/workflows/python-app.yml/badge.svg?branch=develop)](https://github.com/gampnico/scintillometry/actions/workflows/python-app.yml)
 
-This repository is a complete rewrite of gampnico/ss19-feldkurs. If you have any existing forks or local clones, **please delete them**. The legacy code no longer works. No user features will be lost, but rewriting may take some time. Contributions are always welcome.
+Analyse data & 2D flux footprints from Scintec's BLS scintillometers.
 
-This package started life as part of a field course. If you spot any missing citations or licenses please [open an issue](https://github.com/gampnico/scintillometry/issues).
+This project started life as part of a field course. If you spot any missing citations or licences please [open an issue](https://github.com/gampnico/scintillometry/issues).
 
 Comprehensive documentation is available [via ReadTheDocs](https://scintillometry.readthedocs.io/en/latest/).
 

dev-requirements.txt

@@ -3,6 +3,7 @@ tqdm>4.8
 scipy>=1.10
 mpmath>=1.2.1
 numpy
+scikit-learn
 matplotlib
 kneed
 pytest>=7.0

docs/source/conf.py

@@ -50,7 +50,7 @@ def setup(app):
 project = "Scintillometry"
 copyright = f"2019-{date.today().year}, Scintillometry Contributors"
 author = "Scintillometry Contributors"
-release = "1.0.4"
+release = "1.0.5"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -124,6 +124,7 @@ def setup(app):
 .. |Psi_m| replace:: :math:`\\Psi_{{m}}`
 .. |Q_0| replace:: :math:`Q_{{0}}`
 .. |r| replace:: :math:`r`
+.. |R^2| replace:: math:`R^{{2}}`
 .. |R_dry| replace:: :math:`R_{{dry}}`
 .. |R_v| replace:: :math:`R_{{v}}`
 .. |rho| replace:: :math:`\\rho`

docs/source/scintillometry.backend.rst

@@ -70,6 +70,16 @@ In: scintillometry.backend.iterations.py
    :undoc-members:
    :show-inheritance:
 
+Deprecations module
+-------------------
+
+In: scintillometry.backend.deprecations.py
+
+.. automodule:: scintillometry.backend.deprecations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 References
 ----------
 

pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scintillometry"
-version = "1.0.4"
+version = "1.0.5"
 authors = [
   { name="Scintillometry Contributors", email="" },
 ]
 description = "Analyse data & 2D flux footprints from Scintec's BLS scintillometers."
 readme = "README.md"
 requires-python = ">=3.8"
-license = {file = "LICENSE"}
+license = "Apache-2.0"
 classifiers = [
     "Private :: Do Not Upload",
     "License :: OSI Approved :: Apache Software License",
@@ -31,6 +31,7 @@ dependencies = [
   "scipy >= 1.10",
   "mpmath >= 1.2.1",
   "numpy",
+  "scikit-learn",
   "matplotlib",
   "kneed",
 ]

requirements.txt

@@ -3,5 +3,6 @@ tqdm>4.8
 scipy>=1.10
 mpmath>=1.2.1
 numpy
+scikit-learn
 matplotlib
 kneed

src/scintillometry/backend/constants.py

@@ -34,10 +34,6 @@ class AtmosConstants(object):
             BLS type.
         lamda (float): BLS wavelength, |lamda| [nm].
         lamda_error (float): BLS wavelength error, [nm].
-        m1_opt (float): Needed for |A_T| and |A_q|, from Owens (1967).
-            [#owens1967]_
-        m2_opt (float): Needed for |A_T| and |A_q|, from Owens (1967).
-            [#owens1967]_
 
         at_opt (float): |A_T| coefficient for 880 nm & typical
             atmospheric conditions, from Ward et al. (2013).
@@ -60,7 +56,7 @@ class AtmosConstants(object):
             20°C [|Jkg^-1|].
         r_dry (float): Specific gas constant for dry air,
             |R_dry| [|JK^-1| |kg^-1|].
-        r_vapour (float): Specific gas contstant for water vapour,
+        r_vapour (float): Specific gas constant for water vapour,
             |R_v| [|JK^-1| |kg^-1|].
         ratio_rmm (float): Ratio of molecular masses of water vapour and
             dry air i.e. ratio of gas constants |epsilon|.
@@ -149,7 +145,7 @@ def convert_pressure(self, pressure, base=True):
             pressure (Union[pd.DataFrame, pd.Series]): Pressure
                 measurements |P| in pascals [Pa], hectopascals [hPa], or
                 bars [bar].
-            base (bool): If True, converts to pascals [Pa]. Otherwise
+            base (bool): If True, converts to pascals [Pa]. Otherwise,
                 converts to hectopascals [hPa]. Default True.
 
         Returns:
@@ -186,12 +182,12 @@ def convert_temperature(self, temperature, base=True):
         - T [°C] < 130 °C
 
         This method should therefore only be used on pre-processed data
-        as a *convenience*. By default converts to kelvins.
+        as a *convenience*. By default, converts to kelvins.
 
         Args:
             temperature (Union[pd.DataFrame, pd.Series]): Temperature
                 measurements |T| in kelvins [K] or Celsius [°C].
-            base (bool): If True, converts to kelvins [K]. Otherwise
+            base (bool): If True, converts to kelvins [K]. Otherwise,
                 converts to Celsius [°C]. Default True.
 
         Returns:

src/scintillometry/backend/constructions.py

@@ -190,7 +190,7 @@ def get_mixing_ratio(self, wv_pressure, d_pressure):
 
         # (wv_pressure * self.r_dry) / (d_pressure * self.r_vapour)
         m_ratio = (wv_pressure.multiply(self.constants.r_dry)).divide(
-            (d_pressure).multiply(self.constants.r_vapour)
+            d_pressure.multiply(self.constants.r_vapour)
         )
 
         return m_ratio
@@ -236,7 +236,7 @@ def get_reduced_pressure(self, station_pressure, virtual_temperature, elevation)
             elevation (float): Station elevation, |z_stn| [m].
 
         Returns:
-            pd.DataDrame: Derived vertical measurements for mean
+            pd.DataFrame: Derived vertical measurements for mean
             sea-level pressure, |P_MSL| [Pa].
         """
 
@@ -495,7 +495,7 @@ def get_gradient(self, data, method="backward"):
         :math:`\\partial T/\\partial z` for heights |z| with time
         index t.
 
-        By default the gradient is calculated using a 1-D
+        By default, the gradient is calculated using a 1-D
         centred-differencing scheme for non-uniform meshes, since
         vertical measurements are rarely made at uniform intervals.