melafit 0.1.1__py3-none-any.whl

melafit/__init__.py

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

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

melafit/markers.py

@@ -0,0 +1,136 @@
+import numpy as np
+import pandas as pd
+from melafit.utils import day_profile, abs_threshold, time_to_phase
+
+def amplitude(values: np.ndarray) -> np.float64:
+    """
+    Peak-to-baseline amplitude of fitted waveform
+
+    Parameters
+    ----------
+        values : Numpy array of floats
+            Waveform values
+
+    Returns
+    -------
+        ampl : float
+            Peak-to-baseline amplitude
+    """
+
+    return np.max(values) - np.min(values)
+
+
+def midpoint(times: pd.DatetimeIndex,
+             values: np.ndarray,
+             threshold: np.float64,
+             thresh_abs: bool = False
+             ) -> tuple[np.float64, np.float64, np.float64, np.float64]:
+    """
+    Compute melatonin midpoint, DLMOn and DLMOff times. NOTE: This function
+    assumes that there is at least 24h of data. If this is not the case, the
+    results may be inaccurate. When working with waveforms, make sure to
+    generate a full 24h curve which is usually possible even with shorter
+    raw data the curve was fitted to.
+
+    Parameters
+    ----------
+        times : pandas DatetimeIndex
+            Datetime values
+        values : Numpy array of floats
+            Melatonin waveform values
+        threshold: float
+            Relative threshold, fraction of range peak-to-baseline (0 to 1)
+        thresh_abs: bool
+            If True, the given threshold is absolute. Otherwise, the absolute
+            threshold is computed from the given relative threshold and the
+            range of values (defaults to False)
+
+    Returns
+    -------
+        result : tuple[float, float, float, float]
+            Melatonin midpoint, DLMOn and DLMOff times as phase (from 0.0 to
+            1.0, 1.0 = 24h), and absolute threshold
+
+    See also
+    --------
+         melafit.utils.compute_wave: Compute waveform resampled to given time
+         resolution
+    """
+
+    data_series = pd.Series(index=times, data=values)        
+    d_profile = day_profile(data_series, binsize=1)[0]
+
+    if not thresh_abs:
+        threshold = abs_threshold(values, threshold)
+
+    idx_on = np.argwhere((d_profile.values[:-1] < threshold) &
+                         (d_profile.values[1:] >= threshold))[0]
+    idx_off = np.argwhere((d_profile.values[:-1] >= threshold) &
+                          (d_profile.values[1:] < threshold))[0]
+
+    time_on = d_profile.index.values[idx_on][0] / 24.0
+    time_off = d_profile.index.values[idx_off][0] / 24.0
+
+    if time_on > time_off:
+        time_off += 1.0
+
+    time_midpoint = 0.5 * (time_on + time_off)
+
+    time_midpoint = time_to_phase(time_midpoint)
+    time_on = time_to_phase(time_on)
+    time_off = time_to_phase(time_off)
+
+    return time_midpoint, time_on, time_off, threshold
+
+def area_cog(times: pd.DatetimeIndex,
+             values: np.ndarray,
+             baseline: np.float64 | None = None
+             ) -> tuple[np.float64, np.float64]:
+    """
+    Center of gravity of area under the curve
+
+    Parameters
+    ----------
+        times : pandas DatetimeIndex
+            Datetime values
+        values : Numpy array of floats
+            Waveform values
+        baseline : float or None
+            Baseline for area computation. Equals to minimum of values if
+            None is given (default)
+
+    Returns
+    -------
+        area : float
+            Area under the curve
+        cog : float
+            Center of gravity of area under the curve as phase (from 0.0 to
+            1.0, 1.0 = 24h)
+    """
+
+    if baseline is None:
+        baseline = np.min(values)
+    
+    bin_minutes = 1
+
+    data_series = pd.Series(index=times, data=values)
+    d_profile = day_profile(data_series, binsize=bin_minutes)[0]
+
+    times = d_profile.index.values / 24.0
+    values = d_profile.values
+
+    idx_on = np.argwhere((values[:-1] <= baseline) &
+                         (values[1:] > baseline))[0][0]
+
+    times = np.concatenate([times[idx_on:], 1.0 + times[:idx_on]])
+    values = np.concatenate([values[idx_on:], values[:idx_on]]) - baseline
+
+    area = np.sum(values)
+    cog = np.dot(values, times) / area
+
+    # Convert COG to phase (from 0.0 to 1.0, 1.0 = 24h)
+    cog = time_to_phase(cog)
+
+    area /= (24.0 * 60.0 / bin_minutes) # Normalize by bin size in minutes
+
+    return area, cog

melafit/utils.py

@@ -0,0 +1,322 @@
+import numpy as np
+import pandas as pd
+import datetime as dt
+
+def read_data(data_pathname: str) -> pd.DataFrame:
+    """
+    Read data to be analyzed from an Excel spreadsheet.
+
+    Column must be named as follows:
+    * *Participant* for study participant ID
+    * *Date* for dates of the respective samples
+    * *Time* for sample timestamps 
+    * *Mel* for melatonin level values
+
+    Parameters
+    ----------
+        data_pathname : str
+            Pathname of the Excel spreadsheet file to read data from
+
+    Returns
+    -------
+        data : pandas DataFrame
+            Data for all participants read from the Excel table
+    """
+
+    # Read data from Excel spreadsheet
+    data = pd.read_excel(data_pathname)
+
+    # Enforce correct data types
+    data.Participant = data.Participant.astype(int, errors="ignore")
+    data.Date = pd.to_datetime(data.Date, dayfirst=True, errors="coerce").dt.date
+    data.Time = pd.to_datetime(data.Time.astype(str), errors="coerce").dt.time
+    data.Mel = data.Mel.astype(float, errors="ignore")
+
+    # Add combined datetime timestamp
+    data["Timestamp"] = data.apply(lambda x: dt.datetime.combine(x.Date, x.Time), axis=1)
+
+    return data
+
+def prepare_part_data(data: pd.DataFrame,
+                      participant: str | int) -> pd.DataFrame:
+    """
+    Prepare one participant's data for analysis
+
+    Parameters
+    ----------
+        data : pandas DataFrame
+            All participants' data
+        participant : string or integer
+            Participant's identifier
+
+    Returns
+    -------
+        p_data : pandas DataFrame
+            Prepared data for one participant
+    """
+
+    # Select participant's data
+    p_data = data.loc[data.Participant==participant]
+
+    # Extract cumulative time in days
+    base = p_data.Timestamp.min()
+    diff = p_data.Timestamp - base
+    p_data["Timedays"] = (diff.dt.total_seconds() / (24*60*60) +
+                            base.hour / 24 + 
+                            base.minute / (24*60) +
+                            base.second / (24*60*60))
+
+    # Check and fix errors in timestamps
+    idiff = np.diff(p_data.Timedays) < 0
+
+    if any(idiff):
+        ix = np.where(idiff)
+        
+        for i in ix:
+            idx = p_data.index[i[0]+1]  # get the actual index label
+            p_data.loc[idx, 'Timestamp'] += pd.Timedelta(days=1)
+            p_data.loc[idx, 'Timedays'] += 1.0
+            print(f"Corrected one timestamp for participant {participant}")
+
+    return p_data
+
+def compute_wave(tmin: np.float64,
+                 tmax: np.float64,
+                 dt_minutes: np.float64,
+                 f: callable,
+                 p: dict | np.ndarray,
+                 full_wave: bool = True) -> np.ndarray:
+    """
+    Compute waveform resampled to given time resolution
+
+    Parameters
+    ----------
+        tmin : float
+            Start time (1.0 = 24 hours)
+        tmax : float
+            Stop time (inclusive, 1.0 = 24 hours)
+        dt_minutes : float
+            Time increment in minutes
+        f : callable
+            Waveform function
+        p : Dictionary or Numpy array of floats
+            Waveform parameter vector
+        full_wave: bool
+            If True and (tmax-tmin) < 1.0, tmax = tmin + 1.0 (defaults to
+            True)
+
+    Returns
+    -------
+        curve_val : Numpy array of floats
+            Values of the waveform function for the respective time points
+    """
+
+    if full_wave and ((tmax - tmin) < 1.0):
+        tmax = tmin + 1.0
+
+    step = 1.0 / (dt_minutes * 24 * 60)
+    time_curve = np.arange(tmin, tmax + 1.1 * step, step)
+    curve_val = f(t=time_curve, p=p)
+
+    return curve_val
+
+def day_profile(data: pd.Series,
+                binsize: int = 60,
+                double: bool = False, 
+                stderr: bool = False,
+                repfirst: bool = False)->tuple[pd.Series, pd.Series]:
+    """
+    Compute averaged day profile of a (quasi-)periodic time series
+
+    Parameters
+    ----------
+        data : pandas Series
+            Time series data
+        binsize : int
+            Bin size in minutes (defaults to 60)
+        double: bool
+            Prepare data for double plot (defaults to False)
+        stderr : bool
+            Compute standard errors per bin (defaults to False)
+        repfirst : bool
+            Add first bin at 00:00 to the end (defaults to False)
+
+    Returns
+    -------
+        profile : tuple[pd.Series, pd.Series]
+            Bin averages and standard errors with index in hours (0..24)
+    """
+
+    # Bin data, ensure centering of the data points around bin centers
+    smpstr=str(binsize)+'min'
+    profile = data.shift(0.5, freq=smpstr).resample(smpstr).mean()
+    profile = profile.groupby(profile.index.hour + profile.index.minute/60)
+
+    # Compute average profile and standard deviations for each bin
+    profile_mean = profile.mean()
+    profile_std = profile.std()
+    
+    # If standard errors requested, compute these from std's and bin counts
+    if stderr:
+        profile_std  = profile_std / np.sqrt(profile.count())
+
+    # Concatenate results
+    profile = pd.DataFrame(data=pd.concat([profile_mean, profile_std],
+                                          axis=1))
+    
+    # Prepare data for double plot if requested
+    if double:
+        profile = pd.concat([profile, profile])
+        
+    # Add first bin at 00:00 to the end
+    if repfirst:
+        profile = pd.concat([profile, pd.DataFrame(profile.iloc[0,:]).T])
+    
+    # Split returned results up for maximum flexibility
+    return profile.iloc[:,0], profile.iloc[:,1]
+
+def time_to_phase(t: np.float64,
+                  hours: bool = False) -> np.float64:
+    """
+    Convert time values to phase representation (0.0 to 1.0, 1.0 = 24h)
+
+    Parameters
+    ----------
+        t : float
+            Time value (in days or hours)
+        hours: bool
+            If True, time value is in hours and will be converted to phase by
+            dividing by 24. If False, time value is in days (1.0 = 24h).
+            Defaults to False.
+
+    Returns
+    -------
+        phase : float
+            Time as phase (0.0 to 1.0, 1.0 = 24h)
+    """
+
+    if hours:
+        t = t / 24.0
+
+    if t < 0:
+        return np.ceil(-t) + t
+    else:
+        return t - np.floor(t)
+
+def phase_to_string(phase: np.float64) -> str:
+    """
+    Convert phase representation of time (0.0 to 1.0) to string
+
+    Parameters
+    ----------
+        phase : float
+            Time as phase (0.0 to 1.0, 1.0 = 24h)
+
+    Returns
+    -------
+        string : str
+            String representation of phase
+    """
+
+    if phase < 0:
+        sign_str = "-"
+        phase = -phase
+    else:
+        sign_str = ""
+
+    td = pd.Timedelta(days=phase)
+    td_in_seconds = td.total_seconds()
+
+    hours, remainder = divmod(td_in_seconds, 3600)
+    minutes, _ = divmod(remainder, 60)
+    hours = int(hours)
+    minutes = int(minutes)
+
+    string = f"{sign_str}{hours:02d}:{minutes:02d}"
+
+    return string
+
+def abs_threshold(values: np.ndarray,
+                  thresh_rel: np.float64) -> np.float64:
+    """
+    Compute absolute threshold from relative threshold
+
+    Parameters
+    ----------
+        values : Numpy array of floats
+            Waveform values
+        thresh_rel: float
+            Relative threshold, fraction of range peak-to-baseline (0 to 1)
+
+    Returns
+    -------
+        thresh_abs : float
+            Absolute threshold
+    """
+
+    baseline = np.min(values)
+    val_range = np.max(values) - baseline
+    thresh_abs = baseline + thresh_rel * val_range
+
+    return thresh_abs
+
+def phase_diff(phase1: np.float64,
+               phase2: np.float64) -> np.float64:
+    """
+    Compute difference between two phases (0.0 to 1.0, 1.0 = 24h)
+
+    Parameters
+    ----------
+        phase1 : float
+            First time as phase (0.0 to 1.0, 1.0 = 24h)
+        phase2 : float
+            Second time as phase (0.0 to 1.0, 1.0 = 24h)
+
+    Returns
+    -------
+        dp : float
+            Difference between the two phases (0.0 to 1.0, 1.0 = 24h),
+            adjusted to be in the range -0.5 to 0.5 (i.e., -12h to 12h)
+    """
+
+    # Make sure we deal with phases in the range 0.0 to 1.0
+    phase1 = time_to_phase(phase1, hours=False)
+    phase2 = time_to_phase(phase2, hours=False)
+
+    dp = phase1 - phase2
+
+    # Adjust difference to be in the range -0.5 to 0.5 (i.e., -12h to 12h)
+    if dp < -0.5:
+        dp += 1.0
+    elif dp > 0.5:
+        dp -= 1.0
+
+    return dp
+
+def params_to_string(params: dict | np.ndarray, ndec: int = 3) -> str:
+    """
+    Convert curve fitting parameters to string
+
+    Parameters
+    ----------
+        params : dict or Numpy array of floats
+            Curve fitting parameters
+        ndec : int
+            Number of decimal places to display (defaults to 3)
+
+    Returns
+    -------
+        string : str
+            String representation of curve fitting parameters
+    """
+
+    if isinstance(params, dict):
+        param_strs = [f"{key}={value:.{ndec}f}" 
+                      for key, value in params.items()]
+    else:
+        param_strs = [f"p{i}={value:.{ndec}f}"
+                      for i, value in enumerate(params)]
+
+    string = ", ".join(param_strs)
+
+    return string

melafit-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+melafit/__init__.py,sha256=J26zmnP1H9BSnzAqLpeQPpwi4sNcaxEhdtfsQXVjxsU,66
+melafit/fitting.py,sha256=nr0ozZAryy-CWrocQz_tICIC355Bb7JMhU1hSIofrQo,13190
+melafit/markers.py,sha256=4mLNp0HcXydMwSO0sK4sV1_35HWsvjVL2XCBx2A5m8o,4224
+melafit/utils.py,sha256=tELEIRzqwWtu7PLtVHS2Vrbrl8M7oYYHDJqkPteqlew,9188
+melafit-0.1.1.dist-info/licenses/LICENSE,sha256=LmGtoza4siaMUr-hbi1mSVLAVrNrTk0roIjs_WIeMeU,1096
+melafit-0.1.1.dist-info/METADATA,sha256=o9jIY8WPZOfe-JHR5JpqQE4vFGjbhhlYg5eKWfZFN20,370
+melafit-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+melafit-0.1.1.dist-info/top_level.txt,sha256=ZSDwz00o4NuPeW4PSUc0udjKmTgpqy20DNJE5M1sSv0,8
+melafit-0.1.1.dist-info/RECORD,,

melafit-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

melafit-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+melafit