melafit 0.1.1__tar.gz

melafit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitaliy Kolodyazhniy, Christian Cajochen
+
+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.

melafit-0.1.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: melafit
+Version: 0.1.1
+Summary: High-precision circadian melatonin profile analysis
+License: MIT
+Project-URL: Homepage, https://github.com/vitaliy-ch25/melafit
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Requires-Dist: matplotlib
+Dynamic: license-file

melafit-0.1.1/README.md

@@ -0,0 +1,137 @@
+# melafit
+
+Python package for **high-precision circadian melatonin profile analysis.** Features a variety of baseline cosine functions for curve fitting (Van Someren & Nagtegaal, 2007) and a robust cost function for superior convergence, even with sparse data ([Gabel et al. (2017)](https://doi.org/10.1038/s41598-017-07060-8)).
+
+## Overview
+
+[melafit](https://github.com/vitaliy-ch25/melafit) is a Python package designed for high-precision modeling of 24-hour melatonin secretion. While standard cosinor or harmonic analyses fail to capture the physiological nuances of the melatonin "wave," [melafit](https://github.com/vitaliy-ch25/melafit) implements several **baseline cosine functions** including bimodal, skewed and bimodal-skewed modifications. This approach accounts for the characteristic baseline, asymmetry and dual peaks often seen in high-resolution circadian melatonin data.
+
+Furthermore, the library utilizes a **specialized cost function** developed to overcome common optimization hurdles (trivial all-zero solutions), ensuring stable convergence even when working with sparse or incomplete time series.
+
+## Installation
+
+The workflow described below is based on [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/) as the package and environment manager. Create a dedicated directory `<YOUR-DIRECTORY>` for the [melafit](https://github.com/vitaliy-ch25/melafit) repository, navigate to it, and clone the repository:
+
+```bash
+cd <YOUR-DIRECTORY>
+git clone https://github.com/vitaliy-ch25/melafit.git
+cd melafit
+```
+
+Then create and activate the conda environment, which ensures all dependencies (Python 3.12, NumPy, SciPy, Pandas, etc.) are correctly configured. The environment configuration file [./melafit.yml](https://github.com/vitaliy-ch25/melafit/blob/main/melafit.yml) explicitly uses `conda-forge` as the sole package channel, ensuring reproducibility and avoiding potential conflicts between packages from different channels:
+
+```bash
+conda env create -f melafit.yml
+conda activate melafit
+```
+
+This will create a fully functional analysis environment, including a number of supporting data manipulation and analysis packages (`numpy`, `scipy`, `pandas`, `openpyxl` and `matplotlib`).
+
+## Updating
+
+Navigate to the cloned repository directory and pull the latest version:
+
+```bash
+cd <YOUR-DIRECTORY>/melafit
+git pull
+```
+
+Then update the conda environment to match any updated dependencies:
+
+```bash
+conda env update -f melafit.yml --prune
+```
+
+This updates both the dependencies and the `melafit` package itself to the latest version.
+
+## Getting Started
+
+Code example and some dummy data demonstrating melatonin profile curve fitting with this package are included in [./examples/](https://github.com/vitaliy-ch25/melafit/blob/main/examples/) and [./data/](https://github.com/vitaliy-ch25/melafit/blob/main/data/). Copy sample scripts and datasets to your working directory and start from there. If you have performed the steps above as described, your script will 'see' all the required packages from any location. Simply make sure to use the virtual environment `melafit` you created.
+
+## Data preparation
+Follow the Excel table format and column naming conventions as in [./data/](https://github.com/vitaliy-ch25/melafit/blob/main/data/):
+* *Participant* for study participant ID
+* *Date* for dates of the respective samples
+* *Time* for sample timestamps 
+* *Mel* for melatonin level values
+
+## Key Features
+
+* **Bimodal Waveform Fitting:** Implementation of the [Nagtegaal & Van Someren (2007)](https://doi.org/10.1016/j.sleep.2007.03.012) model for superior physiological accuracy.
+* **Optimized Convergence:** Leverages the robust cost function described in [Gabel et al. (2017)](https://doi.org/10.1038/s41598-017-07060-8) to ensure reliable fits across diverse datasets.
+* **Sparse Data Support:** Capable of reconstructing full profiles and estimating circadian phase from limited data points, as well as determining dim light melatonin onset (DLMO) with partial data.
+* **Research-Ready:** Direct derivation of phase markers from continuous, fitted waveforms.
+
+## Scientific Foundations
+
+If you use [melafit](https://github.com/vitaliy-ch25/melafit) in your research, please cite the following foundational publications:
+
+### Human-Readable
+1. [Van Someren, E. J., & Nagtegaal, E. (2007). Improving melatonin circadian phase estimates. Sleep Medicine, 8(6), 590-601.](https://doi.org/10.1016/j.sleep.2007.03.012)
+2. [Gabel, V., et al. (2017). Differential impact in young and older individuals of blue-enriched white light on circadian physiology and alertness during sustained wakefulness. Scientific Reports, 7, 7620.](https://doi.org/10.1038/s41598-017-07060-8)
+
+### BibTeX
+```bibtex
+@article{vansomeren2007,
+  title={Improving melatonin circadian phase estimates},
+  author={Van Someren, Eus JW and Nagtegaal, Elsbeth},
+  journal={Sleep Medicine},
+  volume={8},
+  number={6},
+  pages={590--601},
+  year={2007},
+  publisher={Elsevier}
+}
+
+@article{gabel2017,
+  title={Differential impact in young and older individuals of blue-enriched white light on circadian physiology and alertness during sustained wakefulness},
+  author={Gabel, Virginie and Reichert, Carolin F and Maire, Micheline and Schmidt, Christina and Schlangen, Luc JM and Kolodyazhniy, Vitaliy and Garbazza, Corrado and Cajochen, Christian and Viola, Antoine U},
+  journal={Scientific Reports},
+  volume={7},
+  pages={7620},
+  year={2017},
+  publisher={Nature Publishing Group}
+}
+```
+
+## Authors
+* Vitaliy Kolodyazhniy – Lead Developer
+* Christian Cajochen – Scientific Lead
+
+## Revision History
+
+### [v0.1.1](https://github.com/vitaliy-ch25/melafit/releases/tag/v0.1.1) - First PyPI release
+- Enhanced function `fit()` to support custom waveform functions with user-defined initial parameters and bounds
+- Changed named parameter order in `fit()`: `cost_f` and `cost_p` are now the last two parameters
+- Fixed returned type hints in `func_defaults()`
+- Additional unit tests for new functionality
+- Improved README
+- Package registered in Python Package Index PyPI
+
+### [v0.1.0](https://github.com/vitaliy-ch25/melafit/releases/tag/v0.1.0) — First public release
+- Dictionary support for waveform function parameters throughout the package: all functions accept both `dict` and `np.ndarray` for parameter input
+- Named parameter constants: `BCF_PARAM_NAMES`, `SBCF_PARAM_NAMES`, `BBCF_PARAM_NAMES`, `BSBCF_PARAM_NAMES` and `PARAM_NAMES` lookup
+- New utility functions `params_to_array()` and `array_to_params()` for conversion between array and named dictionary representations
+- `fit()` now returns named parameter dictionary as `res.p` in addition to the standard scipy `res.x` array
+- `fit()` now accepts `cost_p` dictionary for passing parameters to the cost function (e.g. `{"eps": 1e-6}`)
+- New utility function `params_to_string()` for human-readable parameter output
+- Fixed `area_cog()`: baseline subtraction and bin size normalization
+- Unit tests for all public functions in `fitting`, `markers` and `utils`
+
+### v0.0.9
+- New function `func_defaults()` in `fitting.py` for standalone access to default initial conditions and constraints for all waveform functions
+- Improved cost function: `eps` parameter for more robust fitting
+- Optional `thresh_abs` parameter in `markers.midpoint()` for absolute threshold support
+- New example script `example_dlmo.py` and dataset for DLMO detection from partial data
+- Previous example renamed to `example_full_profile.py`
+- Improved type hints, docstrings and README
+
+### Initial revisions (v0.0.1 – v0.0.8)
+- Full implementation of melatonin profile analysis as described in [Gabel et al. (2017)](https://doi.org/10.1038/s41598-017-07060-8)
+- Waveform functions: `bcf`, `sbcf`, `bbcf`, `bsbcf`
+- Markers: `amplitude`, `midpoint`, `DLMOn`, `DLMOff`, `area`, `cog`
+- Utilities: `read_data`, `prepare_part_data`, `compute_wave`, `day_profile`, `abs_threshold`, `time_to_phase`, `phase_to_string`, `phase_diff`
+- MIT license, packaging metadata and README
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

melafit-0.1.1/melafit/__init__.py

@@ -0,0 +1,3 @@
+from .fitting import *
+from .markers import *
+from .utils import *

melafit-0.1.1/melafit/fitting.py

@@ -0,0 +1,497 @@
+import scipy.optimize as opt
+import numpy as np
+
+# Parameter names for melatonin wave approximation functions
+BCF_PARAM_NAMES   = ["phi", "b", "H", "c"]
+SBCF_PARAM_NAMES  = ["phi", "b", "H", "c", "v"]
+BBCF_PARAM_NAMES  = ["phi", "b", "H", "c", "m"]
+BSBCF_PARAM_NAMES = ["phi", "b", "H", "c", "v", "m"]
+
+def _resolve_params(p: np.ndarray | dict) -> np.ndarray:
+    """
+    Convert parameter dict to array if needed, pass array through unchanged.
+    """
+    
+    if isinstance(p, dict):
+        return np.array(list(p.values()))
+    return p
+
+def bcf(t: np.ndarray,
+        p: dict | np.ndarray) -> np.ndarray:
+    """
+    Baseline cosine function
+    [Ruf '92](https://doi.org/10.1076/brhm.27.2.153.12942)
+
+    Parameters
+    ----------
+        t : Numpy array of floats
+            Time values for the BCF waveform
+        p : Dictionary or Numpy array of floats
+            BCF parameters phi, b, H, c
+
+    Returns
+    -------
+        bcf_val : Numpy array of floats
+            Values of the BCF function for the respective time points
+    """
+
+    p = _resolve_params(p)
+    
+    phi = p[0]
+    b = p[1]
+    H = p[2]
+    c = p[3]
+
+    phi = 2 * np.pi * phi
+    t = 2 * np.pi * t
+
+    bcf_val = b + H / (2 * (1 - c)) * (
+        np.cos(t - phi) - c + abs(np.cos(t - phi) - c))
+    
+    return bcf_val
+
+def sbcf(t: np.ndarray,
+         p: dict | np.ndarray) -> np.ndarray:
+    """
+    Skewed baseline cosine function
+    [Van Someren & Nagtegaal '07](https://doi.org/10.1016/j.sleep.2007.03.012)
+
+    Parameters
+    ----------
+        t : Numpy array of floats
+            Time values for the SBCF waveform
+        p : Dictionary or Numpy array of floats
+            SBCF parameters phi, b, H, c, v
+    
+    Returns
+    -------
+        sbcf_val : Numpy array of floats
+            Values of the SBCF function for the respective time points
+    """
+
+    p = _resolve_params(p)
+    
+    phi = p[0]
+    b = p[1]
+    H = p[2]
+    c = p[3]
+    v = p[4]
+
+    phi = 2 * np.pi * phi
+    t = 2 * np.pi * t
+
+    sbcf_val = b + H / (2 * (1 - c)) * (
+        np.cos(t - phi + v * np.cos(t - phi)) - c + 
+        abs(np.cos(t - phi + v * np.cos(t - phi)) - c))
+    
+    return sbcf_val
+
+def bbcf(t: np.ndarray,
+         p: dict | np.ndarray) -> np.ndarray:
+    """
+    Bimodal baseline cosine function
+    [Van Someren & Nagtegaal '07](https://doi.org/10.1016/j.sleep.2007.03.012)
+
+    Parameters
+    ----------
+        t : Numpy array of floats
+            Time values for the BBCF waveform
+        p : Dictionary or Numpy array of floats
+            BBCF parameters phi, b, H, c, m
+
+    Returns
+    -------
+        bbcf_val : Numpy array of floats
+            Values of the BBCF function for the respective time points
+    """
+
+    p = _resolve_params(p)
+    
+    phi = p[0]
+    b = p[1]
+    H = p[2]
+    c = p[3]
+    m = p[4]
+
+    phi = 2 * np.pi * phi
+    t = 2 * np.pi * t
+
+    bbcf_val = b + H / (2 * (1 - c)) * (
+        np.cos(t - phi) + m * np.cos(2 * t - 2 * phi - np.pi) - c + 
+        abs(np.cos(t - phi) + m * np.cos(2 * t - 2 * phi - np.pi) - c))
+
+    return bbcf_val
+
+def bsbcf(t: np.ndarray,
+          p: np.ndarray) -> np.ndarray:
+    """
+    Bimodal skewed baseline cosine function
+    [Van Someren & Nagtegaal '07](https://doi.org/10.1016/j.sleep.2007.03.012)
+
+    Parameters
+    ----------
+        t : Numpy array of floats
+            Time values for the bsbcf waveform
+        p : Numpy array of floats
+            BSBCF parameters phi, b, H, c, v, m
+
+    Returns
+    -------
+        bsbcf_val : Dictionary or Numpy array of floats
+            Values of the BSBCF function for the respective time points
+    """
+    
+    p = _resolve_params(p)
+
+    phi = p[0]
+    b = p[1]
+    H = p[2]
+    c = p[3]
+    v = p[4]
+    m = p[5]
+
+    phi = 2 * np.pi * phi
+    t = 2 * np.pi * t
+
+    bsbcf_val = b + H / (2 * (1 - c)) * (
+        np.cos(t - phi + v * np.cos(t - phi)) + 
+        m * np.cos(2 * t - 2 * phi - np.pi) - c + 
+        abs(np.cos(t - phi + v * np.cos(t - phi)) + 
+            m * np.cos(2 * t - 2 * phi - np.pi) - c))
+
+    return bsbcf_val
+
+# Mapping of functions to parameter names for conversion between dict
+# and array representations
+PARAM_NAMES = {
+    bcf:   BCF_PARAM_NAMES,
+    sbcf:  SBCF_PARAM_NAMES,
+    bbcf:  BBCF_PARAM_NAMES,
+    bsbcf: BSBCF_PARAM_NAMES,
+}
+
+def params_to_array(params: dict) -> np.ndarray:
+    """
+    Convert parameter dictionary to numpy array for scipy.optimize.
+
+    Parameters
+    ----------
+        params : dict
+            Dictionary of parameter names and values
+    Returns
+    -------
+        p : Numpy array of floats
+            Parameter vector for scipy.optimize
+    """
+    return np.array(list(params.values()))
+
+def array_to_params(x: np.ndarray, f: callable) -> dict:
+    """
+    Convert scipy.optimize result array to named parameter dictionary.
+
+    Parameters
+    ----------
+        x : Numpy array of floats
+            Parameter vector from scipy.optimize
+        f : callable
+            Melatonin wave approximation function for which the parameters were fitted
+    Returns
+    -------
+        params : dict
+            Dictionary of parameter names and values for the respective function
+    """
+
+    param_names = PARAM_NAMES.get(f)
+    if param_names is None:
+        raise ValueError(f"Function {f.__name__} not recognized for parameter " +
+                          "conversion.")
+    return dict(zip(param_names, x))
+
+def cost(p: np.ndarray,
+         t: np.ndarray,
+         y: np.ndarray,
+         f: callable,
+         cost_p : dict | None = None) -> np.float64:
+    """
+    Cost function for melatonin fitting, penalizes the trivial solution when
+    all model values = 0
+    [Gabel et al. '17](https://doi.org/10.1038/s41598-017-07060-8)
+    NOTE: the order of parameters is pre-defined by the SciPy optimization
+    routine
+
+    Parameters
+    ----------
+        p : Numpy array of floats
+            Function parameter vector
+        t : Numpy array of floats
+            X-values for curve fitting (time)
+        y: Numpy array of floats
+            Y-values for curve fitting (melatonin levels)
+        f : callable
+            Melatonin wave approximation function
+        cost_p : dict | None
+            Cost function parameters (defaults to None) in which case
+            {"eps": 1e-8} is used
+
+    Returns
+    -------
+        val : float
+            Value of the cost function
+    """
+
+    if cost_p is None:
+        cost_p = {}
+    eps = cost_p.get("eps", 1e-8)
+
+    y_ = f(t, p)
+
+    return np.nanmean(np.square(y - y_)) / (np.var(y_) + eps)
+
+def rsquared(Y: np.ndarray,
+             y: np.ndarray) -> np.float64:
+    """
+    R2 goodness of fit
+
+    Parameters
+    ----------
+        Y : Numpy array of floats
+            Reference values
+        y : Numpy array of floats
+            Fitted values
+
+    Returns
+    -------
+        r2 : float
+            R2 value
+    """
+
+    err = Y - y
+    Y_ = Y - np.nanmean(Y)
+    r2 = 1 - np.nansum(np.square(err)) / np.nansum(np.square(Y_))
+
+    return r2
+
+def func_defaults(data_fit: np.ndarray,
+                  f: callable) -> tuple[dict, dict, dict]:
+    """
+    Default initial conditions and constraints for melatonin wave approximation
+    functions
+
+    Parameters
+    ----------
+        data_fit : Numpy array of floats
+            Y-values for curve fitting (melatonin levels)
+        f : callable
+            Melatonin wave approximation function
+
+    Returns
+    -------
+        p0 : Dictionary
+            Initial guess for the function parameters
+        lb : Dictionary
+            Lower bounds for the function parameters
+        ub : Dictionary
+            Upper bounds for the function parameters
+    """
+
+    minx = np.min(data_fit)
+    maxx = np.max(data_fit)
+
+    data_range = (maxx - minx)
+
+    if f==bcf:
+        # Initial guess for BCF parameters
+        p0 = [
+            0, # phi
+            minx, # b
+            (maxx-minx), # H
+            0 # c
+        ]
+            
+        # Lower bounds for BCF parameters
+        lb = [
+            -0.5, # phi
+            minx, # b
+            0.5 * data_range, # H
+            -1 # c
+        ]
+
+        # Upper bounds for BCF parameters
+        ub = [
+            0.5, # phi
+            maxx, # b
+            2 * data_range, # H
+            1 - 1e-6 # c
+        ]
+    elif f==sbcf:
+        # Initial guess for SBCF parameters
+        p0 = [
+            0, # phi
+            minx, # b
+            (maxx-minx), # H
+            0, # c
+            0 # v
+        ]
+            
+        # Lower bounds for SBCF parameters
+        lb = [
+            -0.5, # phi
+            minx, # b
+            0.5 * data_range, # H
+            -1, # c
+            -1 # v
+        ]
+
+        # Upper bounds for SBCF parameters
+        ub = [
+            0.5, # phi
+            maxx, # b
+            2 * data_range, # H
+            1 - 1e-6, # c
+            1 # v
+        ]
+    elif f==bbcf:
+        # Initial guess for BBCF parameters
+        p0 = [
+            0, # phi
+            minx, # b
+            (maxx-minx), # H
+            0, # c
+            0 # m
+        ]
+        
+        # Lower bounds for BBCF parameters
+        lb = [
+            -0.5, # phi
+            minx, # b
+            0.5 * data_range, # H
+            -1, # c
+            0 # m
+        ]
+
+        # Upper bounds for BBCF parameters
+        ub = [
+            0.5, # phi
+            maxx, # b
+            2 * data_range, # H
+            1 - 1e-6, # c
+            1 - 1e-6 # m
+        ]
+    elif f==bsbcf:
+        # Initial guess for BSBCF parameters
+        p0 = [
+            0, # phi
+            minx, # b
+            (maxx-minx), # H
+            0, # c
+            0, # v
+            0 # m
+        ]
+            
+        # Lower bounds for BSBCF parameters
+        lb = [
+            -0.5, # phi
+            minx, # b
+            0.5 * data_range, # H
+            -1, # c
+            -1, # v
+            0 # m
+        ]
+
+        # Upper bounds for BSBCF parameters
+        ub = [
+            0.5, # phi
+            maxx, # b
+            2 * data_range, # H
+            1 - 1e-6, # c
+            1, # v
+            1 - 1e-6 # m
+        ]
+    else:
+        raise NotImplementedError("Constraints and initial conditions for " + 
+                                  f"function '{f.__name__}' are not defined!")
+    
+    return (array_to_params(p0, f),
+            array_to_params(lb, f),
+            array_to_params(ub, f))
+
+def fit(time_fit: np.ndarray,
+        data_fit: np.ndarray,
+        f: callable=bsbcf,
+        p0: np.ndarray | None = None,
+        lb: np.ndarray | None = None,
+        ub: np.ndarray | None = None,
+        cost_f: callable=cost,
+        cost_p: dict | None = None) -> opt.OptimizeResult:
+    """
+    Melatonin data fitting routine
+
+    Parameters
+    ----------
+        time_fit : Numpy array of floats
+            X-values for curve fitting (time)
+        data_fit : Numpy array of floats
+            Y-values for curve fitting (melatonin levels)
+        f : callable
+            Melatonin wave approximation function (defaults to `bsbcf`)
+        p0 : Numpy array of floats or None
+            Non-standard initial values for wave approximation function
+            (defaults to 'None')
+        lb : Numpy array of floats or None
+            Non-standard lower bounds for wave approximation function
+            parameters (defaults to 'None')
+        ub : Numpy array of floats or None
+            Non-standard upper bounds for wave approximation function
+            parameters (defaults to 'None')
+        cost_f : callable
+            Cost function for curve fitting (defaults to `cost`)
+        cost_p : dict | None
+            Cost function parameters as dictionary or None (defaults to None)
+
+    Returns
+    -------
+        res : OptimizeResult
+            Optimization result including parameters of the fitted function
+            in the field `x`
+    """
+
+    # Only try to fetch defaults if we recognize the function
+    if f in PARAM_NAMES.keys():
+        _p0, _lb, _ub = func_defaults(data_fit, f)
+
+        if p0 is not None:
+            _p0 = p0
+
+        if lb is not None:
+            _lb = lb
+
+        if ub is not None:
+            _ub = ub
+    else:
+        # For custom functions, require the user to have provided p0/lb/ub
+        if p0 is None or lb is None or ub is None:
+            raise ValueError(f"Function '{f.__name__}' is not a built-in model. " +
+                             "You must provide p0, lb, and ub manually.")
+        _p0, _lb, _ub = p0, lb, ub
+
+    bounds = opt.Bounds(_resolve_params(_lb), _resolve_params(_ub))
+    res = opt.minimize(fun=cost_f,
+                       args=(time_fit, data_fit, f, cost_p),
+                       x0=_resolve_params(_p0),
+                       bounds=bounds)
+    
+    if f in PARAM_NAMES:
+        res.p = array_to_params(res.x, f)
+    else:
+        if isinstance(_p0, dict):
+            param_names = list(_p0.keys())
+        elif isinstance(_lb, dict):
+            param_names = list(_lb.keys())
+        elif isinstance(_ub, dict):
+            param_names = list(_ub.keys())
+        else:
+            param_names = None
+
+        res.p = dict(zip(param_names, res.x)) if param_names is not None else None
+
+    return res