csv-session-logger 0.1.0__py3-none-any.whl

csv_session_logger/__init__.py

@@ -0,0 +1 @@
+from csv_session_logger.logger import Logger

csv_session_logger/cli.py

@@ -0,0 +1,128 @@
+from argparse import ArgumentParser
+
+import pandas as pd
+
+import matplotlib.pyplot as plt
+
+def run_info(csv_file: str) -> None:
+    df = pd.read_csv(csv_file, index_col="t_wall")
+    labels = list(df.columns)
+    duration = df.index[-1] - df.index[0]
+    print(
+            "=" * 35,
+            f"Channels: {', '.join(labels)}",
+            f"Duration: {duration:.4f}s",
+            "=" * 35,
+            sep="\n"
+        )
+
+def run_plot(args) -> None:
+    df = pd.read_csv(args.csv_file, index_col="t_wall")
+    t = df.index - df.index[0]
+
+    if args.time is not None and args.xy is not None:
+        raise ValueError("Cannot use -t and -x together. Choose one.")
+    
+    if args.xy is None and args.time is None:
+        _, axes = plt.subplots(nrows=len(df.columns))
+
+        if len(df.columns) == 1:
+            axes = [axes]
+
+        for i, col in enumerate(df.columns):
+            axes[i].plot(t, df[col])
+            axes[i].set_ylabel(col)
+
+        axes[-1].set_xlabel("t [s]")
+        for ax in axes[:-1]:
+            ax.tick_params(labelbottom=False)
+
+        try:
+            manager = plt.get_current_fig_manager()
+            manager.window.showMaximized()
+        except AttributeError:
+            pass
+
+        plt.tight_layout()
+        plt.show()
+
+    elif args.time is not None:
+        invalid = set(args.time) - set(df.columns)
+        if invalid:
+            raise ValueError(f"Unknown columns: {invalid}. Available: {list(df.columns)}")
+        
+        _, axes = plt.subplots(nrows=len(args.time))
+        
+        if len(args.time) == 1:
+            axes = [axes]
+            
+        for i, col in enumerate(args.time):
+            axes[i].plot(t, df[col])
+            axes[i].set_ylabel(col)
+        
+        axes[-1].set_xlabel("t [s]")
+        for ax in axes[:-1]:
+            ax.tick_params(labelbottom=False)
+
+        try:
+            manager = plt.get_current_fig_manager()
+            manager.window.showMaximized()
+        except AttributeError:
+            pass
+        
+        plt.tight_layout()
+        plt.show()
+
+    elif len(args.xy) < 2:
+        raise ValueError("--xy requires at least 2 columns: X and at least one Y")
+    
+    else:
+        invalid = set(args.xy) - set(df.columns)
+        if invalid:
+            raise ValueError(f"Unknown columns: {invalid}. Available: {list(df.columns)}")
+
+        _, axes = plt.subplots(nrows=len(args.xy) - 1)
+        
+        if len(args.xy) - 1 == 1:
+            axes = [axes]
+        
+        for i, col in enumerate(args.xy[1:]):
+            axes[i].plot(df[args.xy[0]], df[col])
+            axes[i].set_ylabel(col)
+        
+        axes[-1].set_xlabel(args.xy[0])
+        for ax in axes[:-1]:
+            ax.tick_params(labelbottom=False)
+
+        try:
+            manager = plt.get_current_fig_manager()
+            manager.window.showMaximized()
+        except AttributeError:
+            pass
+
+        plt.tight_layout()
+        plt.show()
+
+    
+def main() -> None:
+    parser = ArgumentParser(description="csv-session-logger CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Subcommand "info"
+    info_parser = subparsers.add_parser("info")
+    info_parser.add_argument("csv_file")
+
+    # Subcommand "plot"
+    plot_parser = subparsers.add_parser("plot")
+    plot_parser.add_argument("csv_file")
+    plot_parser.add_argument("-x", "--xy", nargs="+")
+    plot_parser.add_argument("-t", "--time", nargs="+")
+
+    args = parser.parse_args()
+
+    if args.command == "info":
+        run_info(args.csv_file)
+    elif args.command == "plot":
+        run_plot(args)
+    else:
+        parser.print_help()

csv_session_logger/logger.py

@@ -0,0 +1,242 @@
+import time
+from datetime import datetime
+
+import pandas as pd
+from pathlib import Path
+
+
+class Logger:
+    """
+    Session-based logger for robotics simulations and hardware experiments.
+
+    Records scalar signals from multiple sources (model, controller, sensors)
+    and writes them to a single time-stamped CSV file.
+
+    Parameters
+    ----------
+    session : str
+        Name of the logging session. Used as part of the output filename.
+    output_dir : str, optional
+        Directory where the CSV file will be written. Created if it does not
+        exist. Default is "logs/".
+    fill : str, optional
+        Strategy for filling NaN values when channels are not logged at the
+        same timestamps. Must be one of:
+        - "none"  : NaN values are left as-is (default).
+        - "ffill" : Forward-fill with the last known value.
+        - "mean"  : Linear interpolation between neighbouring values.
+
+    Raises
+    ------
+    ValueError
+        If an invalid fill strategy is provided.
+
+    Examples
+    --------
+    >>> logger = Logger(session="ntrailer_run", output_dir="logs/", fill="none")
+    >>> logger.register("x_pos", unit="m")
+    >>> logger.register("u_steer", unit="rad")
+    >>> logger.log("x_pos", 0.5)
+    >>> logger.log("u_steer", 0.8)
+    >>> path = logger.save()
+    """
+
+    def __init__(self, session: str, output_dir: str = "logs/", fill: str = "none"):
+        if fill not in ("none", "ffill", "mean"):
+            raise ValueError(
+                f"Invalid fill strategy: '{fill}'. Must be 'none', 'ffill' or 'mean'."
+            )
+
+        self.session = session
+        self.output_dir = output_dir
+        self._fill = fill
+        self._created_at = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+        self._buffer: dict = {}
+
+    def __repr__(self) -> str:
+        return f"Logger(session='{self.session}', channels={len(self._buffer)})"       
+        
+    def register(self, key: str | list[str], unit: str | list[str] | None = None) -> None:
+        """
+        Register one or more logging channels before use.
+
+        Parameters
+        ----------
+        key : str or list[str]
+            Column name(s) in the output CSV. If a list is provided, all keys
+            are registered in a single call.
+        unit : str, list[str], or None, optional
+            Physical unit(s) of the signal, e.g. "rad" or "m/s". If provided,
+            the column header will be formatted as "key [unit]".
+            - Single string: applied to all keys.
+            - List: must be the same length as key.
+            - None: no unit label (default).
+
+        Raises
+        ------
+        ValueError
+            If any key has already been registered.
+        ValueError
+            If unit is a list with different length than key.
+        """
+
+        if isinstance(unit, list) and len(unit) != len(key):
+            raise ValueError(...)
+        
+        if isinstance(key, str):
+            key = [key]
+        
+        for i, k in enumerate(key):
+            u = unit[i] if isinstance(unit, list) else unit
+            if k in self._buffer:
+                raise ValueError(f"Key '{k}' is already registered.")
+            self._buffer[k] = {"values": [], "unit": u, "t_wall": []}
+        
+    def log(self, key: str, value: float) -> None:
+        """
+        Append a single scalar measurement to the buffer.
+
+        The wallclock timestamp is recorded automatically at the moment of
+        the call via time.time().
+
+        Parameters
+        ----------
+        key : str
+            Channel name. Must be registered first via register().
+        value : float
+            Scalar measurement value. Integers are accepted and stored as float.
+
+        Raises
+        ------
+        ValueError
+            If the key has not been registered.
+        """
+
+        if key not in self._buffer:
+            raise ValueError(f"Key '{key}' is not registered. Call register() first.")
+
+        self._buffer[key]["values"].append(float(value))
+        self._buffer[key]["t_wall"].append(time.time())
+
+    def log_many(self, data: dict[str, float]) -> None:
+        """
+        Append multiple scalar measurements to the buffer in a single call.
+
+        All channels share the same wallclock timestamp, recorded once at the
+        moment of the call. Use this instead of multiple log() calls when
+        channels belong to the same timestep and should be aligned in the CSV.
+
+        Parameters
+        ----------
+        data : dict[str, float]
+            Dictionary mapping channel names to scalar measurement values.
+            All keys must be registered first via register().
+
+        Raises
+        ------
+        ValueError
+            If any key in data has not been registered.
+        """
+
+        t_wall = time.time()
+        for k in data:
+            if k not in self._buffer:
+                raise ValueError(f"Key '{k}' is not registered. Call register() first.")
+            self._buffer[k]["values"].append(float(data[k]))
+            self._buffer[k]["t_wall"].append(t_wall)
+
+    def save(self, filename: str | None = None) -> Path:
+        """
+        Align all logged channels onto a common time index and write to CSV.
+
+        Each channel is converted to a pandas Series indexed by t_wall.
+        Channels logged at different times produce NaN in rows where they
+        have no entry. The fill strategy set at construction is applied
+        before writing.
+
+        Parameters
+        ----------
+        filename : str or None, optional
+            Custom filename for the output CSV (without directory). If None,
+            the filename is auto-generated as "{session}_{timestamp}.csv".
+
+        Returns
+        -------
+        Path
+            Absolute path of the written CSV file.
+        """
+
+        if not any(self._buffer[k]["values"] for k in self._buffer):
+            raise RuntimeError("Buffer is empty. Nothing to save.")
+        
+        if filename is not None:
+            if not filename.endswith(".csv"):
+                raise ValueError(f"filename must end with '.csv', got '{filename}'")
+            path = Path(self.output_dir) / filename
+        else:
+            path = Path(self.output_dir) / f"{self.session}_{self._created_at}.csv"
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        concat: dict = {}
+        for key in self._buffer:
+            unit = self._buffer[key]["unit"]
+            label = f"{key} [{unit}]" if unit is not None else key
+            concat[label] = pd.Series(
+                data=self._buffer[key]["values"],
+                index=self._buffer[key]["t_wall"],
+            )
+
+        df = pd.DataFrame(concat)
+        df.index.name = "t_wall"
+
+        if self._fill == "ffill":
+            df = df.ffill()
+        elif self._fill == "mean":
+            df = df.interpolate()
+
+        df.to_csv(path, float_format="%.8f")
+
+        return path.resolve()
+
+    def reset(self) -> None:
+        """
+        Clear all buffered measurements without writing to disk.
+
+        Registered keys and their units are preserved. Only the recorded
+        values and timestamps are cleared. The session timestamp is renewed
+        so the next save() call produces a new filename.
+        """
+
+        self._created_at = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+
+        for key in self._buffer:
+            self._buffer[key]["values"] = []
+            self._buffer[key]["t_wall"] = []
+
+    def summary(self) -> None:
+        """Print a summary of the current logging session to stdout."""
+        
+        labels = []
+        for k in self._buffer:
+            unit = self._buffer[k]["unit"]
+            label = f"{k} [{unit}]" if unit is not None else k
+            labels.append(label)
+        
+        samples = list(map(lambda k: len(self._buffer[k]["values"]), self._buffer))
+
+        all_t = []
+        for k in self._buffer:
+            for t in self._buffer[k]["t_wall"]:
+                all_t.append(t)
+        duration = max(all_t) - min(all_t)
+        
+        print(
+            "=" * 35,
+            f"Session:  {self.session}",
+            f"Channels: {', '.join(labels)}",
+            f"Samples:  {samples}",
+            f"Duration: {duration:.4f}s",
+            "=" * 35,
+            sep="\n"
+        )

csv_session_logger-0.1.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: csv-session-logger
+Version: 0.1.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: PyQt5>=5.15
+Requires-Dist: argcomplete>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# csv-session-logger
+
+A small session-based CSV logger for robotics sims and bench tests, one file per run, channels aligned on wall-clock time.
+
+## Install
+
+```bash
+pip install csv-session-logger
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from csv_session_logger import Logger
+
+log = Logger(session="bench_test", output_dir="logs/", fill="none")
+log.register("voltage", unit="V")
+log.register("current", unit="A")
+
+log.log("voltage", 12.1)
+log.log("current", 0.45)
+
+path = log.save()
+print(path)
+```
+
+Channels must be registered before logging. I made that explicit so you decide upfront what goes in the CSV instead of accumulating mystery columns mid-run.
+
+## `log()` vs `log_many()`
+
+Both append scalar samples to the buffer. The difference is timing.
+
+- `**log(key, value)**`: one channel, one call. Each call records its own `t_wall` via `time.time()`. If you log `x` and then `y` separately, they land on slightly different timestamps. That is fine when channels are independent or arrive asynchronously (e.g. a slow sensor vs a fast control loop).
+- `**log_many({...})**`: several channels in one call. All keys in the dict share a single `t_wall` timestamp, taken once at the start of the call. I use this when values belong to the same timestep and should line up in the CSV without NaN gaps, typical in a simulation loop or a synchronized sensor snapshot.
+
+Simulation time is not special. If you want `t_sim`, register it like any other channel and include it in `log_many()`:
+
+```python
+log.register(["t_sim", "x", "x_dot"], ["s", "m", "m/s"])
+log.log_many({"t_sim": t, "x": x, "x_dot": x_dot})
+```
+
+## Fill strategies
+
+When channels are logged at different `t_wall` times, `save()` merges them onto one time index. Missing entries become NaN before the fill step runs.
+
+
+| `fill`    | Behavior                                                                                                                                     |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"none"`  | Leave NaN as-is. Use when you want to see exactly which channel was missing at each timestamp.                                               |
+| `"ffill"` | Forward-fill with the last known value per column. Leading NaN (before the first sample) stay NaN.                                           |
+| `"mean"`  | Linear interpolation between neighbours (`pandas.interpolate()`). Good for plotting continuous signals when samples are slightly misaligned. |
+
+
+Pick the strategy at `Logger(...)` construction, it applies on every `save()`.
+
+## Output format
+
+The CSV index is `t_wall` (Unix seconds, float). Column headers use `"key [unit]"` when a unit was registered, otherwise plain `key`. Values are written with 8 decimal places.
+
+Example (from a spring-mass-damper run):
+
+```csv
+t_wall,t_sim [s],x [m],x_dot [m/s],x_ref [m],error [m],F [N]
+1781263948.99401498,0.00000000,0.00000000,0.00000000,0.00000000,0.00000000,0.00000000
+1781263948.99402165,0.01000000,0.00000000,0.00000000,0.00000000,0.00000000,0.00000000
+```
+
+Auto-generated filenames look like `{session}_{YYYY-MM-DD_HH-MM-SS}.csv`. Pass `save(filename="my_run.csv")` to override.
+
+## CLI
+
+Entry point: `csl`
+
+### `csl info <csv>`
+
+Print channel names and duration (last `t_wall` minus first).
+
+```bash
+csl info logs/spring_mass_damper_2026-06-12_00-23-22.csv
+```
+
+### `csl plot <csv>`
+
+Quick matplotlib plots. Time axis is `t_wall` relative to the first row (starts at 0).
+
+```bash
+# All channels, stacked subplots
+csl plot logs/spring_mass_damper_2026-06-12_00-23-22.csv
+
+# Subset by column name (-t / --time)
+csl plot logs/spring_mass_damper_2026-06-12_00-23-22.csv -t "x [m]" "F [N]"
+
+# XY plot: first column is X, rest are Y (-x / --xy)
+csl plot logs/spring_mass_damper_2026-06-12_00-23-22.csv -x "t_sim [s]" "x [m]" "error [m]"
+```
+
+`-t` and `-x` cannot be used together.
+
+## Full example: spring-mass-damper
+
+Second-order plant with a P controller, Euler integration. Same as `examples/sim_example.py`:
+
+```python
+import numpy as np
+from csv_session_logger import Logger
+
+m, c, k, Kp = 1.0, 0.5, 2.0, 10.0
+dt, t_end = 0.01, 20.0
+n_steps = int(t_end / dt)
+
+def x_ref(t: float) -> float:
+    return 0.0 if t < 2.0 else 1.0
+
+x, x_dot = 0.0, 0.0
+
+log = Logger(session="spring_mass_damper", output_dir="logs/", fill="none")
+log.register(["t_sim", "x", "x_dot", "x_ref", "error", "F"],
+             ["s", "m", "m/s", "m", "m", "N"])
+
+t = 0.0
+for _ in range(n_steps):
+    ref = x_ref(t)
+    error = ref - x
+    F = Kp * error
+
+    x_ddot = (F - c * x_dot - k * x) / m
+    x_dot += x_ddot * dt
+    x += x_dot * dt
+
+    log.log_many({
+        "t_sim": t, "x": x, "x_dot": x_dot,
+        "x_ref": ref, "error": error, "F": F,
+    })
+    t += dt
+
+path = log.save()
+log.summary()
+```
+
+Run it: `python examples/sim_example.py`, then `csl plot logs/spring_mass_damper_*.csv`.
+
+## Why not rosbag / wandb / mlflow?
+
+I haven't used these in practice, but for this use case I wanted something
+minimal: register a few channels, log scalars in a loop, get one CSV. No
+server, no extra setup, just a file I can open with pandas or `csl plot`.

csv_session_logger-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+csv_session_logger/__init__.py,sha256=2k9raMKl2EfZO0YyAYttoKTFY9TYEEQ0lHEVXDOZE6c,44
+csv_session_logger/cli.py,sha256=TAT1UlYnNPOs2q17csR3NXzc1zz4rIdVKAjHLN_qYeE,3610
+csv_session_logger/logger.py,sha256=C-YmsRfrAiK_GjzZz5RV5Cy9Ckfns7Q3MQHY-aHbh08,8250
+csv_session_logger-0.1.0.dist-info/METADATA,sha256=ibZY6dkRG63-5cZ-8xdUD8M3jrHxKbnhm-h22xmKni0,5549
+csv_session_logger-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+csv_session_logger-0.1.0.dist-info/entry_points.txt,sha256=YZraKtDSfRwFfMtsifGnqiAHcvORXm2VRgPXTX8YJyU,52
+csv_session_logger-0.1.0.dist-info/top_level.txt,sha256=WqUSmbW1VqtOaYWFrRWDJBkj92ycqXoNodbSYeCmszQ,19
+csv_session_logger-0.1.0.dist-info/RECORD,,

csv_session_logger-0.1.0.dist-info/WHEEL

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

csv_session_logger-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+csl = csv_session_logger.cli:main

csv_session_logger-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+csv_session_logger