shepherd-data 2022.9.3__py3-none-any.whl → 2023.3.1__py3-none-any.whl

shepherd_data/__init__.py

@@ -10,7 +10,8 @@ import logging
 from .reader import Reader
 from .writer import Writer
 
-__version__ = "2022.9.3"
+__version__ = "2023.3.1"
+
 __all__ = [
     "Reader",
     "Writer",

shepherd_data/calibration.py

@@ -2,21 +2,22 @@
 
 """
 from typing import Dict
-from typing import Union
+from typing import TypeVar
 
 import numpy as np
+from numpy.typing import NDArray
 
-# SI-value [SI-Unit] = raw-value * gain + offset
-cal_default: Dict[str, dict] = {
+cal_default: Dict[str, Dict[str, float]] = {
     "voltage": {"gain": 3 * 1e-9, "offset": 0.0},  # allows 0 - 12 V in 3 nV-Steps
     "current": {"gain": 250 * 1e-12, "offset": 0.0},  # allows 0 - 1 A in 250 pA - Steps
     "time": {"gain": 1e-9, "offset": 0.0},
+    # SI-value [SI-Unit] = raw-value * gain + offset
 }
 
+T_calc = TypeVar("T_calc", NDArray[np.float64], float)
 
-def raw_to_si(
-    values_raw: Union[np.ndarray, float, int], cal: dict
-) -> Union[np.ndarray, float]:
+
+def raw_to_si(values_raw: T_calc, cal: Dict[str, float]) -> T_calc:
     """Helper to convert between physical units and raw unsigned integers
 
     :param values_raw: number or numpy array with raw values
@@ -24,11 +25,15 @@ def raw_to_si(
     :return: converted number or array
     """
     values_si = values_raw * cal["gain"] + cal["offset"]
-    values_si[values_si < 0.0] = 0.0
+    if isinstance(values_si, np.ndarray):
+        values_si[values_si < 0.0] = 0.0
+        # if pyright still complains, cast with .astype(float)
+    else:
+        values_si = float(max(values_si, 0.0))
     return values_si
 
 
-def si_to_raw(values_si: Union[np.ndarray, float], cal: dict) -> Union[np.ndarray, int]:
+def si_to_raw(values_si: T_calc, cal: Dict[str, float]) -> T_calc:
     """Helper to convert between physical units and raw unsigned integers
 
     :param values_si: number or numpy array with values in physical units
@@ -36,5 +41,8 @@ def si_to_raw(values_si: Union[np.ndarray, float], cal: dict) -> Union[np.ndarra
     :return: converted number or array
     """
     values_raw = (values_si - cal["offset"]) / cal["gain"]
-    values_raw[values_raw < 0.0] = 0.0
+    if isinstance(values_raw, np.ndarray):
+        values_raw[values_raw < 0.0] = 0.0
+    else:
+        values_raw = max(values_raw, 0.0)
     return values_raw

shepherd_data/cli.py

@@ -6,7 +6,7 @@ import os
 import sys
 from pathlib import Path
 from typing import List
-from typing import NoReturn
+from typing import Optional
 
 import click
 
@@ -18,7 +18,7 @@ logger = logging.getLogger("SHPData.cli")
 verbose_level = 2
 
 
-def config_logger(verbose: int) -> NoReturn:
+def config_logger(verbose: int) -> None:
     # TODO: put in __init__, provide logger, ditch global var
     if verbose == 0:
         logger.setLevel(logging.ERROR)
@@ -61,8 +61,8 @@ def path_to_flist(data_path: Path) -> List[Path]:
     default=0,
     help="4 Levels [0..3](Error, Warning, Info, Debug)",
 )
-@click.pass_context
-def cli(ctx, verbose: int):
+@click.pass_context  # TODO: is the ctx-type correct?
+def cli(ctx: click.Context, verbose: int) -> None:
     """Shepherd: Synchronized Energy Harvesting Emulator and Recorder
 
     Args:
@@ -79,7 +79,7 @@ def cli(ctx, verbose: int):
 
 @cli.command(short_help="Validates a file or directory containing shepherd-recordings")
 @click.argument("in_data", type=click.Path(exists=True, resolve_path=True))
-def validate(in_data):
+def validate(in_data: Path) -> None:
     """Validates a file or directory containing shepherd-recordings"""
     files = path_to_flist(in_data)
     valid_dir = True
@@ -111,7 +111,7 @@ def validate(in_data):
     type=click.STRING,
     help="Set an individual csv-separator",
 )
-def extract(in_data, ds_factor, separator):
+def extract(in_data: Path, ds_factor: float, separator: str) -> None:
     """Extracts recorded IVSamples and stores it to csv"""
     files = path_to_flist(in_data)
     if not isinstance(ds_factor, (float, int)) or ds_factor < 1:
@@ -160,7 +160,7 @@ def extract(in_data, ds_factor, separator):
     type=click.STRING,
     help="Set an individual csv-separator",
 )
-def extract_meta(in_data, separator):
+def extract_meta(in_data: Path, separator: str) -> None:
     """Extracts metadata and logs from file or directory containing shepherd-recordings"""
     files = path_to_flist(in_data)
     for file in files:
@@ -197,14 +197,16 @@ def extract_meta(in_data, separator):
 @click.option(
     "--sample-rate",
     "-r",
-    type=int,
+    type=click.INT,
     help="Alternative Input to determine a downsample-factor (Choose One)",
 )
-def downsample(in_data, ds_factor, sample_rate):
+def downsample(
+    in_data: Path, ds_factor: Optional[float], sample_rate: Optional[int]
+) -> None:
     """Creates an array of downsampling-files from file
     or directory containing shepherd-recordings"""
     if ds_factor is None and sample_rate is not None and sample_rate >= 1:
-        ds_factor = int(Reader.samplerate_sps / sample_rate)
+        ds_factor = int(Reader.samplerate_sps_default / sample_rate)
     if isinstance(ds_factor, (float, int)) and ds_factor >= 1:
         ds_list = [ds_factor]
     else:
@@ -279,7 +281,14 @@ def downsample(in_data, ds_factor, sample_rate):
     is_flag=True,
     help="Plot all files (in directory) into one Multiplot",
 )
-def plot(in_data, start: float, end: float, width: int, height: int, multiplot: bool):
+def plot(
+    in_data: Path,
+    start: Optional[float],
+    end: Optional[float],
+    width: int,
+    height: int,
+    multiplot: bool,
+) -> None:
     """Plots IV-trace from file or directory containing shepherd-recordings"""
     files = path_to_flist(in_data)
     multiplot = multiplot and len(files) > 1
@@ -294,7 +303,10 @@ def plot(in_data, start: float, end: float, width: int, height: int, multiplot:
     if multiplot:
         logger.info("Got %d datasets to plot", len(data))
         mpl_path = Reader.multiplot_to_file(data, in_data, width, height)
-        logger.info("Plot generated and saved to '%s'", mpl_path.name)
+        if mpl_path:
+            logger.info("Plot generated and saved to '%s'", mpl_path.name)
+        else:
+            logger.info("Plot not generated, path was already in use.")
 
 
 if __name__ == "__main__":

shepherd_data/ivonne.py

@@ -9,7 +9,7 @@ import math
 import os
 import pickle  # noqa: S403
 from pathlib import Path
-from typing import NoReturn
+from typing import Optional
 
 import numpy as np
 import pandas as pd
@@ -34,27 +34,30 @@ def get_isc(coeffs: pd.DataFrame):
 class Reader:
     """container for converters to shepherd-data"""
 
-    samplerate_sps: int = 50
-    sample_interval_ns: int = int(10**9 // samplerate_sps)
-    sample_interval_s: float = 1 / samplerate_sps
-
-    runtime_s: float = None
-    file_size: int = None
-    data_rate: float = None
-
-    _df: pd.DataFrame = None
-
     _logger: logging.Logger = logging.getLogger("SHPData.IVonne.Reader")
 
     def __init__(
-        self, file_path: Path, samplerate_sps: int = None, verbose: bool = True
+        self,
+        file_path: Path,
+        samplerate_sps: Optional[int] = None,
+        verbose: bool = True,
     ):
         self._logger.setLevel(logging.INFO if verbose else logging.WARNING)
 
         self.file_path = Path(file_path)
+        self.samplerate_sps: int = 50
         if samplerate_sps is not None:
             self.samplerate_sps = samplerate_sps
 
+        self.sample_interval_ns: int = int(10**9 // self.samplerate_sps)
+        self.sample_interval_s: float = 1 / self.samplerate_sps
+
+        self.runtime_s: float = 0
+        self.file_size: int = 0
+        self.data_rate: float = 0
+
+        self._df: Optional[pd.DataFrame] = None
+
     def __enter__(self):
         if not self.file_path.exists():
             raise FileNotFoundError(
@@ -75,10 +78,12 @@ class Reader:
         )
         return self
 
-    def __exit__(self, *exc):
+    def __exit__(self, *exc):  # type: ignore
         pass
 
-    def _refresh_file_stats(self) -> NoReturn:
+    def _refresh_file_stats(self) -> None:
+        if self._df is None:
+            raise RuntimeError("IVonne Context was not entered - file not open!")
         self.runtime_s = round(self._df.shape[0] / self.samplerate_sps, 3)
         self.file_size = self.file_path.stat().st_size
         self.data_rate = self.file_size / self.runtime_s if self.runtime_s > 0 else 0
@@ -88,8 +93,8 @@ class Reader:
         shp_output: Path,
         v_max: float = 5.0,
         pts_per_curve: int = 1000,
-        duration_s: float = None,
-    ) -> NoReturn:
+        duration_s: Optional[float] = None,
+    ) -> None:
         """Transforms previously recorded parameters to shepherd hdf database with IV curves.
         Shepherd should work with IV 'surfaces', where we have a stream of IV curves
 
@@ -98,6 +103,8 @@ class Reader:
         :param pts_per_curve: Number of sampling points of the prototype curve
         :param duration_s: time to stop in seconds, counted from beginning
         """
+        if self._df is None:
+            raise RuntimeError("IVonne Context was not entered - file not open!")
         if isinstance(duration_s, (float, int)) and self.runtime_s > duration_s:
             self._logger.info("  -> gets trimmed to %s s", duration_s)
             df_elements_n = min(
@@ -115,7 +122,6 @@ class Reader:
         with Writer(
             shp_output, datatype="ivcurve", window_samples=pts_per_curve
         ) as sfw:
-
             sfw.set_hostname("IVonne")
             curve_interval_us = round(sfw.sample_interval_ns * pts_per_curve / 1000)
             up_factor = self.sample_interval_ns // sfw.sample_interval_ns
@@ -125,7 +131,7 @@ class Reader:
             for idx in job_iter:
                 idx_top = min(idx + max_elements, df_elements_n)
                 df_slice = self._df.iloc[idx : idx_top + 1].copy()
-                df_slice.loc[:, "timestamp"] = pd.TimedeltaIndex(
+                df_slice["timestamp"] = pd.TimedeltaIndex(
                     data=df_slice["time"], unit="s"
                 )
                 df_slice = df_slice.set_index("timestamp")
@@ -153,9 +159,9 @@ class Reader:
         self,
         shp_output: Path,
         v_max: float = 5.0,
-        duration_s: float = None,
-        tracker: MPPTracker = None,
-    ) -> NoReturn:
+        duration_s: Optional[float] = None,
+        tracker: Optional[MPPTracker] = None,
+    ) -> None:
         """Transforms shepherd IV curves to shepherd IV traces.
 
         For the 'buck' and 'buck-boost' modes, shepherd takes voltage and current traces.
@@ -173,6 +179,8 @@ class Reader:
         :param duration_s: time to stop in seconds, counted from beginning
         :param tracker: VOC or OPT
         """
+        if self._df is None:
+            raise RuntimeError("IVonne Context was not entered - file not open!")
         if isinstance(duration_s, (float, int)) and self.runtime_s > duration_s:
             self._logger.info("  -> gets trimmed to %s s", duration_s)
             df_elements_n = min(
@@ -191,7 +199,6 @@ class Reader:
             )
 
         with Writer(shp_output, datatype="ivsample") as sfw:
-
             sfw.set_hostname("IVonne")
             interval_us = round(sfw.sample_interval_ns / 1000)
             up_factor = self.sample_interval_ns // sfw.sample_interval_ns
@@ -206,7 +213,7 @@ class Reader:
                 df_slice.loc[:, "voc"] = get_voc(df_slice)
                 df_slice.loc[df_slice["voc"] >= v_max, "voc"] = v_max
                 df_slice = tracker.process(df_slice)
-                df_slice.loc[:, "timestamp"] = pd.TimedeltaIndex(
+                df_slice["timestamp"] = pd.TimedeltaIndex(
                     data=df_slice["time"], unit="s"
                 )
                 df_slice = df_slice[["time", "v", "i", "timestamp"]].set_index(
@@ -228,14 +235,16 @@ class Reader:
         self,
         shp_output: Path,
         v_max: float = 5.0,
-        duration_s: float = None,
-    ) -> NoReturn:
+        duration_s: Optional[float] = None,
+    ) -> None:
         """Transforms ivonne-parameters to upsampled version for shepherd
 
         :param shp_output: Path where the resulting hdf file shall be stored
         :param v_max: Maximum voltage supported by shepherd
         :param duration_s: time to stop in seconds, counted from beginning
         """
+        if self._df is None:
+            raise RuntimeError("IVonne Context was not entered - file not open!")
         if isinstance(duration_s, (float, int)) and self.runtime_s > duration_s:
             self._logger.info("  -> gets trimmed to %s s", duration_s)
             df_elements_n = min(
@@ -249,7 +258,6 @@ class Reader:
             return
 
         with Writer(shp_output, datatype="isc_voc") as sfw:
-
             sfw.set_hostname("IVonne")
             interval_us = round(sfw.sample_interval_ns / 1000)
             up_factor = self.sample_interval_ns // sfw.sample_interval_ns
@@ -264,7 +272,7 @@ class Reader:
                 df_slice.loc[:, "voc"] = get_voc(df_slice)
                 df_slice.loc[df_slice["voc"] >= v_max, "voc"] = v_max
                 df_slice.loc[:, "isc"] = get_isc(df_slice)
-                df_slice.loc[:, "timestamp"] = pd.TimedeltaIndex(
+                df_slice["timestamp"] = pd.TimedeltaIndex(
                     data=df_slice["time"], unit="s"
                 )
                 df_slice = df_slice[["time", "voc", "isc", "timestamp"]].set_index(

shepherd_data/mppt.py

@@ -5,8 +5,10 @@ Might be exchanged by shepherds py-model of pru-harvesters
 import numpy as np
 import pandas as pd
 
+from .calibration import T_calc
 
-def iv_model(voltages: np.ndarray, coeffs: pd.DataFrame) -> np.ndarray:
+
+def iv_model(voltages: T_calc, coeffs: pd.Series) -> T_calc:
     """Simple diode based model of a solar panel IV curve.
 
     Args:
@@ -16,15 +18,18 @@ def iv_model(voltages: np.ndarray, coeffs: pd.DataFrame) -> np.ndarray:
     Returns:
         Solar current at given load voltage
     """
-    currents = coeffs["a"] - coeffs["b"] * (np.exp(coeffs["c"] * voltages) - 1)
-    if hasattr(currents, "__len__"):
-        currents[currents < 0] = 0
+    currents = float(coeffs["a"]) - float(coeffs["b"]) * (
+        np.exp(float(coeffs["c"]) * voltages) - 1.0
+    )
+    if isinstance(currents, np.ndarray):
+        currents[currents < 0.0] = 0.0
     else:
-        currents = max(0, currents)
+        currents = max(0.0, currents)
+
     return currents
 
 
-def find_oc(v_arr, i_arr, ratio: float = 0.05):
+def find_oc(v_arr: np.ndarray, i_arr: np.ndarray, ratio: float = 0.05):
     """Approximates opencircuit voltage.
 
     Searches last current value that is above a certain ratio of the short-circuit
@@ -51,7 +56,7 @@ class MPPTracker:
         :param coeffs: ivonne coefficients
         :return:
         """
-        pass
+        return pd.DataFrame()
 
 
 class OpenCircuitTracker(MPPTracker):