csv-session-logger 0.1.0__tar.gz

csv_session_logger-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,149 @@
+# 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/csv_session_logger/__init__.py

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

csv_session_logger-0.1.0/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-0.1.0/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/csv_session_logger.egg-info/PKG-INFO

@@ -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/csv_session_logger.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+csv_session_logger/__init__.py
+csv_session_logger/cli.py
+csv_session_logger/logger.py
+csv_session_logger.egg-info/PKG-INFO
+csv_session_logger.egg-info/SOURCES.txt
+csv_session_logger.egg-info/dependency_links.txt
+csv_session_logger.egg-info/entry_points.txt
+csv_session_logger.egg-info/requires.txt
+csv_session_logger.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_logger.py
+tests/test_session.py
+tests/test_writer.py

csv_session_logger-0.1.0/csv_session_logger.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

csv_session_logger-0.1.0/csv_session_logger.egg-info/entry_points.txt

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

csv_session_logger-0.1.0/csv_session_logger.egg-info/requires.txt

@@ -0,0 +1,8 @@
+pandas>=2.0
+numpy>=1.24
+matplotlib>=3.7
+PyQt5>=5.15
+argcomplete>=3.0
+
+[dev]
+pytest>=7.0

csv_session_logger-0.1.0/csv_session_logger.egg-info/top_level.txt

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

csv_session_logger-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "csv-session-logger"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "pandas>=2.0",
+    "numpy>=1.24",
+    "matplotlib>=3.7",
+    "PyQt5>=5.15",
+    "argcomplete>=3.0",
+]
+
+readme = "README.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+csl = "csv_session_logger.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["csv_session_logger*"]
+exclude = ["tests*", "examples*", "logs*"]

csv_session_logger-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

csv_session_logger-0.1.0/tests/test_cli.py

@@ -0,0 +1,95 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from csv_session_logger.cli import main
+
+
+@pytest.fixture
+def mock_plot():
+    """Headless plot stub for CI — avoids opening a display window."""
+
+    def fake_subplots(*_args, **kwargs):
+        nrows = kwargs.get("nrows", 1)
+        if nrows == 1:
+            return MagicMock(), MagicMock()
+        return MagicMock(), [MagicMock() for _ in range(nrows)]
+
+    with patch("csv_session_logger.cli.plt.subplots", side_effect=fake_subplots):
+        with patch("csv_session_logger.cli.plt.show"):
+            with patch("csv_session_logger.cli.plt.tight_layout"):
+                with patch("csv_session_logger.cli.plt.get_current_fig_manager"):
+                    yield
+
+
+def test_csl_info_on_saved_csv(sample_csv, capsys):
+    with patch("sys.argv", ["csl", "info", str(sample_csv)]):
+        main()
+    out = capsys.readouterr().out
+    assert "x [m]" in out
+    assert "y [N]" in out
+    assert "flag" in out
+
+
+def test_csl_plot_default_runs(sample_csv, mock_plot):
+    with patch("sys.argv", ["csl", "plot", str(sample_csv)]):
+        main()
+
+
+def test_csl_plot_time_flag_runs(sample_csv, mock_plot):
+    with patch(
+        "sys.argv",
+        ["csl", "plot", str(sample_csv), "-t", "x [m]", "y [N]"],
+    ):
+        main()
+
+
+def test_csl_plot_time_invalid_column_raises(sample_csv):
+    with patch(
+        "sys.argv",
+        ["csl", "plot", str(sample_csv), "-t", "nonexistent"],
+    ):
+        with pytest.raises(ValueError, match="Unknown columns"):
+            main()
+
+
+def test_csl_plot_xy_flag_runs(sample_csv, mock_plot):
+    with patch(
+        "sys.argv",
+        ["csl", "plot", str(sample_csv), "-x", "x [m]", "y [N]"],
+    ):
+        main()
+
+
+def test_csl_plot_single_column_raises(sample_csv):
+    with patch(
+        "sys.argv",
+        ["csl", "plot", str(sample_csv), "-x", "x [m]"],
+    ):
+        with pytest.raises(ValueError, match="requires at least 2 columns"):
+            main()
+
+
+def test_csl_plot_time_and_xy_together_raises(sample_csv):
+    with patch(
+        "sys.argv",
+        [
+            "csl",
+            "plot",
+            str(sample_csv),
+            "-t",
+            "x [m]",
+            "-x",
+            "x [m]",
+            "y [N]",
+        ],
+    ):
+        with pytest.raises(ValueError, match="Cannot use -t and -x together"):
+            main()
+
+
+def test_csl_no_subcommand_prints_help(capsys):
+    with patch("sys.argv", ["csl"]):
+        main()
+    out = capsys.readouterr().out
+    assert "csv-session-logger CLI" in out

csv_session_logger-0.1.0/tests/test_logger.py

@@ -0,0 +1,247 @@
+from unittest.mock import patch
+
+import pandas as pd
+import pytest
+
+from csv_session_logger import Logger
+
+
+# --- register() ---
+
+
+def test_register_single_key():
+    log = Logger(session="s", output_dir="unused")
+    log.register("x", unit="m")
+    assert "x" in log._buffer
+    assert log._buffer["x"]["unit"] == "m"
+    assert log._buffer["x"]["values"] == []
+
+
+def test_register_duplicate_key_raises():
+    log = Logger(session="s", output_dir="unused")
+    log.register("x")
+    with pytest.raises(ValueError, match="already registered"):
+        log.register("x")
+
+
+def test_register_list_of_keys_with_matching_units():
+    log = Logger(session="s", output_dir="unused")
+    log.register(["a", "b"], ["m", "N"])
+    assert log._buffer["a"]["unit"] == "m"
+    assert log._buffer["b"]["unit"] == "N"
+
+
+def test_register_list_of_keys_with_single_unit():
+    log = Logger(session="s", output_dir="unused")
+    log.register(["a", "b"], "rad")
+    assert log._buffer["a"]["unit"] == "rad"
+    assert log._buffer["b"]["unit"] == "rad"
+
+
+def test_register_mismatched_unit_list_raises():
+    log = Logger(session="s", output_dir="unused")
+    with pytest.raises(ValueError):
+        log.register(["a", "b"], ["m"])
+
+
+# --- log() ---
+
+
+def test_log_unregistered_key_raises():
+    log = Logger(session="s", output_dir="unused")
+    with pytest.raises(ValueError, match="not registered"):
+        log.log("x", 1.0)
+
+
+def test_log_stores_int_as_float():
+    log = Logger(session="s", output_dir="unused")
+    log.register("x")
+    log.log("x", 42)
+    assert log._buffer["x"]["values"] == [42.0]
+    assert isinstance(log._buffer["x"]["values"][0], float)
+
+
+def test_log_multiple_calls_accumulate_in_order():
+    log = Logger(session="s", output_dir="unused")
+    log.register("x")
+    with patch("csv_session_logger.logger.time.time") as mock_time:
+        mock_time.side_effect = [1.0, 2.0, 3.0]
+        log.log("x", 1.0)
+        log.log("x", 2.0)
+        log.log("x", 3.0)
+    assert log._buffer["x"]["values"] == [1.0, 2.0, 3.0]
+    assert log._buffer["x"]["t_wall"] == [1.0, 2.0, 3.0]
+
+
+# --- log_many() ---
+
+
+def test_log_many_shares_single_t_wall():
+    log = Logger(session="s", output_dir="unused")
+    log.register(["a", "b"])
+    with patch("csv_session_logger.logger.time.time", return_value=42.0):
+        log.log_many({"a": 1.0, "b": 2.0})
+    assert log._buffer["a"]["t_wall"] == [42.0]
+    assert log._buffer["b"]["t_wall"] == [42.0]
+
+
+def test_log_many_unregistered_key_raises():
+    log = Logger(session="s", output_dir="unused")
+    log.register("a")
+    with pytest.raises(ValueError, match="not registered"):
+        log.log_many({"a": 1.0, "b": 2.0})
+
+
+# --- save() ---
+
+
+def test_save_creates_session_timestamp_file(tmp_path):
+    log = Logger(session="my_run", output_dir=str(tmp_path))
+    log.register("x")
+    with patch("csv_session_logger.logger.time.time", return_value=100.0):
+        log.log("x", 1.0)
+    with patch.object(
+        log,
+        "_created_at",
+        "2025-06-01_12-00-00",
+    ):
+        path = log.save()
+    assert path == (tmp_path / "my_run_2025-06-01_12-00-00.csv").resolve()
+    assert path.exists()
+
+
+def test_save_csv_index_name_is_t_wall(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path))
+    log.register("x", unit="m")
+    with patch("csv_session_logger.logger.time.time", return_value=100.0):
+        log.log("x", 1.0)
+    path = log.save()
+    df = pd.read_csv(path, index_col="t_wall")
+    assert df.index.name == "t_wall"
+
+
+def test_save_column_headers_with_and_without_units(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path))
+    log.register("x", unit="m")
+    log.register("flag")
+    with patch("csv_session_logger.logger.time.time", return_value=100.0):
+        log.log_many({"x": 1.0, "flag": 0.0})
+    path = log.save()
+    df = pd.read_csv(path)
+    assert "x [m]" in df.columns
+    assert "flag" in df.columns
+
+
+def test_save_fill_none_leaves_nan(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path), fill="none")
+    log.register(["a", "b"])
+    with patch("csv_session_logger.logger.time.time") as mock_time:
+        mock_time.side_effect = [100.0, 101.0]
+        log.log("a", 1.0)
+        log.log("b", 2.0)
+    path = log.save()
+    df = pd.read_csv(path, index_col="t_wall")
+    assert pd.isna(df.loc[100.0, "b"])
+    assert pd.isna(df.loc[101.0, "a"])
+
+
+def test_save_fill_ffill_forward_fills_but_leading_nan_remains(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path), fill="ffill")
+    log.register(["a", "b"])
+    with patch("csv_session_logger.logger.time.time") as mock_time:
+        mock_time.side_effect = [100.0, 101.0]
+        log.log("a", 1.0)
+        log.log("b", 2.0)
+    path = log.save()
+    df = pd.read_csv(path, index_col="t_wall")
+    assert pd.isna(df.loc[100.0, "b"])
+    assert df.loc[101.0, "a"] == 1.0
+
+
+def test_save_fill_mean_interpolates(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path), fill="mean")
+    log.register(["a", "b"])
+    with patch("csv_session_logger.logger.time.time") as mock_time:
+        mock_time.side_effect = [100.0, 101.0, 102.0]
+        log.log("a", 0.0)
+        log.log("b", 0.0)  # only b at t=101; row at 101 has NaN for a before fill
+        log.log("a", 10.0)
+    path = log.save()
+    df = pd.read_csv(path, index_col="t_wall")
+    assert df.loc[101.0, "a"] == pytest.approx(5.0)
+
+
+def test_save_custom_filename(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path))
+    log.register("x")
+    with patch("csv_session_logger.logger.time.time", return_value=100.0):
+        log.log("x", 1.0)
+    path = log.save(filename="custom.csv")
+    assert path.name == "custom.csv"
+    assert path.exists()
+
+
+def test_save_filename_without_csv_extension_raises(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path))
+    log.register("x")
+    with patch("csv_session_logger.logger.time.time", return_value=100.0):
+        log.log("x", 1.0)
+    with pytest.raises(ValueError, match="must end with '.csv'"):
+        log.save(filename="noext")
+
+
+def test_save_empty_buffer_raises(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path))
+    log.register("x")
+    with pytest.raises(RuntimeError, match="Buffer is empty"):
+        log.save()
+
+
+# --- reset() ---
+
+
+def test_reset_clears_values_preserves_registration(tmp_path):
+    log = Logger(session="s", output_dir=str(tmp_path))
+    log.register("x", unit="m")
+    with patch("csv_session_logger.logger.time.time", return_value=100.0):
+        log.log("x", 1.0)
+    log.reset()
+    assert log._buffer["x"]["values"] == []
+    assert log._buffer["x"]["t_wall"] == []
+    assert log._buffer["x"]["unit"] == "m"
+
+
+def test_reset_changes_session_timestamp():
+    log = Logger(session="s", output_dir="unused")
+    log.register("x")
+    before = log._created_at
+    with patch("csv_session_logger.logger.datetime") as mock_dt:
+        mock_dt.now.return_value.strftime.return_value = "2099-01-01_00-00-00"
+        log.reset()
+    assert log._created_at == "2099-01-01_00-00-00"
+    assert log._created_at != before
+
+
+# --- summary() and __repr__ ---
+
+
+def test_summary_runs_with_output(capsys):
+    log = Logger(session="bench", output_dir="unused")
+    log.register("x", unit="m")
+    with patch("csv_session_logger.logger.time.time") as mock_time:
+        mock_time.side_effect = [10.0, 11.0]
+        log.log("x", 1.0)
+        log.log("x", 2.0)
+    log.summary()
+    out = capsys.readouterr().out
+    assert out.strip()
+    assert "bench" in out
+    assert "x [m]" in out
+
+
+def test_repr_non_empty():
+    log = Logger(session="bench", output_dir="unused")
+    log.register("x")
+    text = repr(log)
+    assert text
+    assert "bench" in text