mr-dapa 0.4.0__tar.gz

mr_dapa-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yang Siyuan
+
+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.

mr_dapa-0.4.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: mr-dapa
+Version: 0.4.0
+Summary: Multi-Robot Data Animation & Plotting Assistance
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: all
+Requires-Dist: ffmpeg-python; extra == "all"
+Dynamic: license-file

mr_dapa-0.4.0/README.md

@@ -0,0 +1,106 @@
+# mr-dapa — Multi-Robot Data Animation & Plotting Assistance
+
+Rapid visualization of multi-agent time-series data. Researchers have N robots' timestamped data (possibly async, possibly from different sources) and need to quickly generate static plots and animations.
+
+## Quick Start
+
+```bash
+pip install -e .
+python examples/minimal/generate_data.py
+python examples/minimal/main.py
+```
+
+## API Overview
+
+```python
+import mr_dapa as mrdp
+
+components = {
+    'x': {'title': 'X Position', 'class': 'LinesComponent', 'keys': ['x']},
+    'map': {'title': 'Map', 'class': 'MapComponent', 'limits': {"x": [-3, 7], "y": [-3, 7]}},
+}
+
+# Static plot — returns figure (no file saved)
+fig = mrdp.StaticGlobalPlotDrawer(files=['data.json'], components=components).draw(['x', 'map'])
+
+# Chain API for filtering
+mrdp.StaticGlobalPlotDrawer(files=['data.json'], components=components) \
+    .set_id_list([1, 3]) \
+    .set_time_range((0.2, 0.5)) \
+    .draw(['x'], save=True)                # save=True writes to file
+
+# Animation
+mrdp.AnimationDrawer(files=['data.json'], components=components) \
+    .draw(['x', 'map'], time_ratio=2, save=True)
+```
+
+### Draw Modes
+
+| Drawer | Behavior |
+|--------|----------|
+| `StaticGlobalPlotDrawer` | All robots in shared subplots |
+| `StaticSeparatePlotDrawer` | One figure per robot |
+| `StaticGroupPlotDrawer` | All robots, per-robot subplots in one figure |
+| `AnimationDrawer` | Time-based MP4 animation |
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `LinesComponent` | Time-series line plots |
+| `MapComponent` | 2D position map with trails |
+| `ScatterComponent` | Scatter/phase plot (x vs y) |
+| `FillComponent` | Filled area between values |
+
+### Adapters
+
+```python
+from mr_dapa import CSVAdapter, MultiFileAdapter, NumPyAdapter
+
+loader = mrdp.StaticGlobalPlotDrawer(files=['data.csv'], components=components, adapter=CSVAdapter())
+loader = mrdp.StaticGlobalPlotDrawer(files=['r1.json', 'r2.json'], components=components, adapter=MultiFileAdapter())
+```
+
+## Data Format
+
+Canonical JSON format (each robot has its own timestamp array — supports async data):
+
+```json
+[
+  {
+    "id": 1,
+    "timestamp": [0.0, 0.02, 0.04],
+    "values": [
+      {"name": "X Position", "alias": "x", "unit": "m", "value": [1.0, 1.1, 1.2]},
+      {"name": "Y Position", "alias": "y", "unit": "m", "value": [2.0, 2.1, 2.2]}
+    ]
+  }
+]
+```
+
+## Requirements
+
+- Python >= 3.9
+- numpy, matplotlib, tqdm
+- ffmpeg (for animation export)
+
+## Installation
+
+```bash
+pip install -e .
+pip install -e ".[dev]"   # includes pytest, ruff
+```
+
+## Testing
+
+```bash
+pytest tests/               # 145 tests
+pytest tests/ -v             # verbose
+pytest tests/ -k "adapter"   # filter by name
+```
+
+Test structure: `conftest.py` provides shared fixtures (sample_data, interpreter, components_config). Each `test_*.py` covers one module.
+
+## License
+
+MIT

mr_dapa-0.4.0/mr_dapa/__init__.py

@@ -0,0 +1,58 @@
+from .drawers.drawers import (
+    StaticGlobalPlotDrawer,
+    StaticSeparatePlotDrawer,
+    StaticGroupPlotDrawer,
+    AnimationDrawer,
+)
+
+from .components.components import (
+    LinesComponent,
+    MapComponent,
+    ScatterComponent,
+    FillComponent,
+)
+
+from .adapters import (
+    DataAdapter,
+    JSONAdapter,
+    MultiFileAdapter,
+    CSVAdapter,
+    NumPyAdapter,
+)
+
+from .registry import (
+    register_component,
+    unregister_component,
+    get_component_class,
+    list_components,
+)
+
+from .components.base import BaseComponent
+
+from .style import StyleConfig, get_style, get_palette
+
+__version__ = '0.4.0'
+
+__all__ = [
+    'StaticGlobalPlotDrawer',
+    'StaticSeparatePlotDrawer',
+    'StaticGroupPlotDrawer',
+    'AnimationDrawer',
+    'LinesComponent',
+    'MapComponent',
+    'ScatterComponent',
+    'FillComponent',
+    'BaseComponent',
+    'DataAdapter',
+    'JSONAdapter',
+    'MultiFileAdapter',
+    'CSVAdapter',
+    'NumPyAdapter',
+    'register_component',
+    'unregister_component',
+    'get_component_class',
+    'list_components',
+    'StyleConfig',
+    'get_style',
+    'get_palette',
+]

mr_dapa-0.4.0/mr_dapa/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .base import DataAdapter as DataAdapter
+from .json_adapter import JSONAdapter as JSONAdapter
+from .multi_file_adapter import MultiFileAdapter as MultiFileAdapter
+from .csv_adapter import CSVAdapter as CSVAdapter
+from .numpy_adapter import NumPyAdapter as NumPyAdapter

mr_dapa-0.4.0/mr_dapa/adapters/base.py

@@ -0,0 +1,7 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DataAdapter(Protocol):
+    def load(self, source) -> list[dict]:
+        ...

mr_dapa-0.4.0/mr_dapa/adapters/csv_adapter.py

@@ -0,0 +1,50 @@
+import csv
+
+
+class CSVAdapter:
+    def __init__(self, id_col='id', timestamp_col='timestamp', separator=','):
+        self.id_col = id_col
+        self.timestamp_col = timestamp_col
+        self.separator = separator
+
+    def load(self, source) -> list[dict]:
+        if not isinstance(source, str):
+            raise TypeError(f"CSVAdapter expects a file path, got {type(source)}")
+
+        robots = {}
+        with open(source, newline='') as f:
+            reader = csv.DictReader(f, delimiter=self.separator)
+            for row in reader:
+                robot_id = int(row[self.id_col])
+                if robot_id not in robots:
+                    robots[robot_id] = {'timestamps': [], 'values': {}}
+
+                ts = float(row[self.timestamp_col])
+                robots[robot_id]['timestamps'].append(ts)
+
+                for col in row:
+                    if col in (self.id_col, self.timestamp_col):
+                        continue
+                    if col not in robots[robot_id]['values']:
+                        robots[robot_id]['values'][col] = {'timestamps': [], 'value': []}
+                    robots[robot_id]['values'][col]['timestamps'].append(ts)
+                    robots[robot_id]['values'][col]['value'].append(float(row[col]))
+
+        result = []
+        for robot_id in sorted(robots.keys()):
+            r = robots[robot_id]
+            values = []
+            for name, v in r['values'].items():
+                values.append({
+                    'name': name,
+                    'alias': name,
+                    'unit': '',
+                    'timestamp': v['timestamps'],
+                    'value': v['value'],
+                })
+            result.append({
+                'id': robot_id,
+                'timestamp': r['timestamps'],
+                'values': values,
+            })
+        return result

mr_dapa-0.4.0/mr_dapa/adapters/json_adapter.py

@@ -0,0 +1,11 @@
+import json
+
+
+class JSONAdapter:
+    def load(self, source) -> list[dict]:
+        if isinstance(source, str):
+            with open(source) as f:
+                return json.load(f)
+        if isinstance(source, list):
+            return source
+        raise TypeError(f"JSONAdapter expects a file path or list, got {type(source)}")

mr_dapa-0.4.0/mr_dapa/adapters/multi_file_adapter.py

@@ -0,0 +1,16 @@
+import json
+
+
+class MultiFileAdapter:
+    def load(self, source) -> list[dict]:
+        if isinstance(source, list) and len(source) > 0 and isinstance(source[0], str):
+            merged = []
+            for path in source:
+                with open(path) as f:
+                    data = json.load(f)
+                if isinstance(data, list):
+                    merged.extend(data)
+                else:
+                    merged.append(data)
+            return merged
+        raise TypeError(f"MultiFileAdapter expects a list of file paths, got {type(source)}")

mr_dapa-0.4.0/mr_dapa/adapters/numpy_adapter.py

@@ -0,0 +1,34 @@
+import numpy as np
+
+
+class NumPyAdapter:
+    def load(self, source) -> list[dict]:
+        if not isinstance(source, dict):
+            raise TypeError(f"NumPyAdapter expects a dict, got {type(source)}")
+
+        result = []
+        for robot_id, robot_data in source.items():
+            robot_id = int(robot_id)
+            timestamp = robot_data.get('timestamp')
+            if timestamp is not None:
+                timestamp = np.asarray(timestamp).tolist()
+
+            values = []
+            for key, arr in robot_data.get('values', {}).items():
+                val_arr = np.asarray(arr).tolist()
+                ts = timestamp if timestamp is not None else list(range(len(val_arr)))
+                if isinstance(ts, np.ndarray):
+                    ts = ts.tolist()
+                values.append({
+                    'name': key,
+                    'alias': key,
+                    'unit': robot_data.get('units', {}).get(key, ''),
+                    'timestamp': ts,
+                    'value': val_arr,
+                })
+
+            entry = {'id': robot_id, 'values': values}
+            if timestamp is not None:
+                entry['timestamp'] = timestamp
+            result.append(entry)
+        return result

mr_dapa-0.4.0/mr_dapa/components/base.py

@@ -0,0 +1,30 @@
+class BaseComponent:
+    FIGSIZE = (6, 6)
+    expand = True
+    required_config_keys: dict[str, type] = {}
+
+    def __init__(self, ax, interpreter, title="", mode='static', **kwargs):
+        self.ax = ax
+        self.interpreter = interpreter
+        self.title = title
+        self.mode = mode
+        self.kwargs = kwargs
+
+    @classmethod
+    def validate_config(cls, name: str, config: dict) -> None:
+        for key, expected_type in cls.required_config_keys.items():
+            if key not in config:
+                raise ValueError(
+                    f"Component '{name}' ({cls.__name__}): missing required key '{key}'"
+                )
+            if expected_type is not None and not isinstance(config[key], expected_type):
+                raise ValueError(
+                    f"Component '{name}' ({cls.__name__}): key '{key}' must be "
+                    f"{expected_type.__name__}, got {type(config[key]).__name__}"
+                )
+
+    def _initialize(self):
+        raise NotImplementedError
+
+    def update(self, timestamp):
+        return []

mr_dapa-0.4.0/mr_dapa/components/components.py

@@ -0,0 +1,5 @@
+from .base import BaseComponent as BaseComponent
+from .lines import LinesComponent as LinesComponent
+from .map import MapComponent as MapComponent
+from .scatter import ScatterComponent as ScatterComponent
+from .fill import FillComponent as FillComponent

mr_dapa-0.4.0/mr_dapa/components/fill.py

@@ -0,0 +1,147 @@
+import numpy as np
+
+from .base import BaseComponent
+
+
+class FillComponent(BaseComponent):
+    FIGSIZE = (6, 6)
+    expand = True
+    required_config_keys = {'keys': list}
+
+    def __init__(self, ax, interpreter, title="", keys=None, mode='static', **kwargs):
+        super().__init__(ax, interpreter, title=title, mode=mode, **kwargs)
+        self.keys = keys or []
+        self.units = self.interpreter.get_units(self.keys)
+        self.single_unit = len(self.units) == 1
+
+        self.lines = {}
+        self.fill_collections = {}
+        self.markers = {}
+        self.value_texts = {}
+        self.vline = None
+        self.y_limits = None
+
+        self._initialize()
+
+    def _initialize(self):
+        self.ax.set_title(self.title)
+        self.ax.set_xlabel("Time (s)")
+        ylabel = "Values" + ((" (" + self.units[0] + ")") if self.single_unit else "")
+        self.ax.set_ylabel(ylabel)
+
+        fill_color = self.kwargs.get('fill_color', 'blue')
+        fill_alpha = self.kwargs.get('fill_alpha', 0.2)
+
+        for frame in self.interpreter.data:
+            upper_data = None
+            lower_data = None
+
+            for value in frame["values"]:
+                if value["alias"] in self.keys or value["name"] in self.keys:
+                    if upper_data is None:
+                        upper_data = value
+                    else:
+                        lower_data = value
+
+            if upper_data is not None and lower_data is not None:
+                label_suffix = f", Robot #{frame['id']}" if len(self.interpreter.id_list) > 1 else ""
+                line_upper, = self.ax.plot(
+                    upper_data["timestamp"], upper_data["value"],
+                    label=upper_data["alias"] + label_suffix, alpha=0.7
+                )
+                line_lower, = self.ax.plot(
+                    lower_data["timestamp"], lower_data["value"],
+                    label=lower_data["alias"] + label_suffix, alpha=0.7
+                )
+                self.lines[f"{frame['id']}-upper"] = line_upper
+                self.lines[f"{frame['id']}-lower"] = line_lower
+
+                fill = self.ax.fill_between(
+                    upper_data["timestamp"],
+                    upper_data["value"],
+                    lower_data["value"],
+                    color=fill_color,
+                    alpha=fill_alpha
+                )
+                self.fill_collections[frame['id']] = fill
+
+            elif upper_data is not None:
+                label_suffix = f", Robot #{frame['id']}" if len(self.interpreter.id_list) > 1 else ""
+                line, = self.ax.plot(
+                    upper_data["timestamp"], upper_data["value"],
+                    label=upper_data["alias"] + label_suffix
+                )
+                self.lines[f"{frame['id']}-single"] = line
+
+                fill = self.ax.fill_between(
+                    upper_data["timestamp"],
+                    upper_data["value"], 0,
+                    color=fill_color,
+                    alpha=fill_alpha
+                )
+                self.fill_collections[frame['id']] = fill
+
+        if len(self.lines) > 1:
+            self.ax.legend(loc='best')
+
+        if self.mode == "animation":
+            self._animation_setup()
+
+    def _animation_setup(self):
+        self.y_limits = self.ax.get_ylim()
+        self.vline = self.ax.plot(
+            [self.interpreter.time_range[0], self.interpreter.time_range[1]],
+            [self.y_limits[0], self.y_limits[1]],
+            'r--', alpha=0.3
+        )[0]
+
+        marker_style = dict(marker='*', color='red', alpha=0.7, markersize=10)
+        text_style = dict(
+            color='red', alpha=0.8, fontsize=9,
+            bbox=dict(facecolor='white', alpha=0.3, edgecolor='none')
+        )
+
+        for label_key, line in self.lines.items():
+            marker, = self.ax.plot([np.nan], [np.nan], **marker_style)
+            self.markers[label_key] = marker
+
+            text = self.ax.text(
+                np.nan, np.nan, '', **text_style,
+                verticalalignment='center',
+                horizontalalignment='left'
+            )
+            self.value_texts[label_key] = text
+
+    def update(self, timestamp):
+        artists = []
+
+        if self.vline is not None:
+            self.vline.set_data([timestamp, timestamp], self.y_limits)
+            artists.append(self.vline)
+
+        timespan = self.interpreter.time_range[1] - self.interpreter.time_range[0]
+        time_offset = timespan * 0.015
+        x_limits = self.ax.get_xlim()
+
+        for label_key, line in self.lines.items():
+            if label_key not in self.markers:
+                continue
+            index = np.searchsorted(line.get_xdata(), timestamp)
+
+            self.markers[label_key].set_data([timestamp], [line.get_ydata()[index]])
+            artists.append(self.markers[label_key])
+
+            if timestamp < (x_limits[0] + x_limits[1]) / 2:
+                self.value_texts[label_key].set_horizontalalignment('left')
+                self.value_texts[label_key].set_position(
+                    (timestamp + time_offset, line.get_ydata()[index])
+                )
+            else:
+                self.value_texts[label_key].set_horizontalalignment('right')
+                self.value_texts[label_key].set_position(
+                    (timestamp - time_offset, line.get_ydata()[index])
+                )
+            self.value_texts[label_key].set_text(f"{line.get_ydata()[index]:.4f}")
+            artists.append(self.value_texts[label_key])
+
+        return artists

mr_dapa-0.4.0/mr_dapa/components/lines.py

@@ -0,0 +1,162 @@
+import numpy as np
+
+from .base import BaseComponent
+
+
+class LinesComponent(BaseComponent):
+    required_config_keys = {'keys': list}
+
+    def __init__(self, ax, interpreter, title="", keys=None, mode='static', **kwargs):
+        super().__init__(ax, interpreter, title=title, mode=mode, **kwargs)
+        self.keys = keys or []
+        self.units = self.interpreter.get_units(self.keys)
+        self.single_unit = len(self.units) == 1
+
+        self.lines = {}
+        self.markers = {}
+        self.value_texts = {}
+        self.vline = None
+        self.y_limits = None
+
+        self._initialize()
+
+    def _make_label(self, robot_id, name):
+        return f"{robot_id}-{name}"
+
+    def _initialize(self):
+        self.ax.set_title(self.title)
+        self.ax.set_xlabel("Time (s)")
+        ylabel = "Values" + ((" (" + self.units[0] + ")") if self.single_unit else "")
+        self.ax.set_ylabel(ylabel)
+
+        if 'bounds' in self.kwargs:
+            for b in self.kwargs['bounds']:
+                self.ax.axhline(b, color='black', linestyle='--', alpha=0.3)
+
+        if 'range' in self.kwargs:
+            self.ax.axhspan(self.kwargs['range'][0], self.kwargs['range'][1], alpha=0.1, color='grey')
+
+        if 'show_zero_line' in self.kwargs and self.kwargs.get('show_zero_line', True):
+            self.ax.axhline(0, color='black', alpha=0.3, linestyle='--')
+
+        if 'milestones' in self.kwargs:
+            for m in self.kwargs['milestones']:
+                self.ax.axvline(m, color='grey', alpha=0.3, linestyle='--')
+
+        if 'bars' in self.kwargs:
+            for bar in self.kwargs['bars']:
+                self.ax.axhline(bar, color='black', linestyle='--', alpha=0.3)
+
+        marker_style = dict(marker='*', color='red', alpha=0.7, markersize=10)
+        text_style = dict(
+            color='red', alpha=0.8, fontsize=9,
+            bbox=dict(facecolor='white', alpha=0.3, edgecolor='none')
+        )
+
+        for robot in self.interpreter.data:
+            for value in robot["values"]:
+                if value["alias"] not in self.keys and value["name"] not in self.keys:
+                    continue
+                marker, = self.ax.plot([np.nan], [np.nan], **marker_style)
+                self.markers[self._make_label(robot["id"], value["name"])] = marker
+
+                text = self.ax.text(
+                    np.nan, np.nan, '', **text_style,
+                    verticalalignment='center',
+                    horizontalalignment='left'
+                )
+                self.value_texts[self._make_label(robot["id"], value["name"])] = text
+
+        for frame in self.interpreter.data:
+            for value in frame["values"]:
+                if value["alias"] not in self.keys and value["name"] not in self.keys:
+                    continue
+                label = value["name"] if self.mode == "separate" else value["alias"]
+                if not self.single_unit:
+                    label += f"({value['unit']})"
+                if len(self.interpreter.id_list) > 1:
+                    label += f", Robot #{frame['id']}"
+                line, = self.ax.plot(
+                    value["timestamp"], value["value"], label=label
+                )
+                self.lines[self._make_label(frame['id'], value["name"])] = line
+
+        if self.kwargs.get('fill', False):
+            for frame in self.interpreter.data:
+                for value in frame["values"]:
+                    if value["alias"] not in self.keys and value["name"] not in self.keys:
+                        continue
+                    self.ax.fill_between(
+                        value["timestamp"], value["value"], 0, alpha=0.15
+                    )
+
+        if self.kwargs.get('show_min', False):
+            for frame in self.interpreter.data:
+                for value in frame["values"]:
+                    if value["alias"] not in self.keys and value["name"] not in self.keys:
+                        continue
+                    min_idx = np.argmin(value["value"])
+                    min_x = value["timestamp"][min_idx]
+                    min_y = value["value"][min_idx]
+                    self.ax.annotate(
+                        f'min: {min_y:.2f}',
+                        xy=(min_x, min_y),
+                        xytext=(5, 5),
+                        textcoords='offset points',
+                        fontsize=8,
+                        color='blue',
+                        alpha=0.7
+                    )
+
+        if len(self.lines) > 1:
+            self.ax.legend(loc='best')
+
+        if self.mode == "animation":
+            self._animation_setup()
+
+    def _animation_setup(self):
+        self.y_limits = self.ax.get_ylim()
+        self.vline = self.ax.plot(
+            [self.interpreter.time_range[0], self.interpreter.time_range[1]],
+            [self.y_limits[0], self.y_limits[1]],
+            'r--', alpha=0.3
+        )[0]
+
+    def update(self, timestamp):
+        artists = []
+
+        if self.vline is not None:
+            self.vline.set_data([timestamp, timestamp], self.y_limits)
+            artists.append(self.vline)
+
+        timespan = self.interpreter.time_range[1] - self.interpreter.time_range[0]
+        time_offset = timespan * 0.015
+        x_limits = self.ax.get_xlim()
+
+        for label, line in self.lines.items():
+            index = np.searchsorted(line.get_xdata(), timestamp)
+
+            self.markers[label].set_data([timestamp], [line.get_ydata()[index]])
+            artists.append(self.markers[label])
+
+            if timestamp < (x_limits[0] + x_limits[1]) / 2:
+                self.value_texts[label].set_horizontalalignment('left')
+                self.value_texts[label].set_position(
+                    (timestamp + time_offset, line.get_ydata()[index])
+                )
+            else:
+                self.value_texts[label].set_horizontalalignment('right')
+                self.value_texts[label].set_position(
+                    (timestamp - time_offset, line.get_ydata()[index])
+                )
+
+            if len(self.lines) > 1:
+                self.value_texts[label].set_text(f"{label}: {line.get_ydata()[index]:.4f}")
+            else:
+                self.value_texts[label].set_text(f"{line.get_ydata()[index]:.4f}")
+            artists.append(self.value_texts[label])
+
+        if len(self.lines) > 1:
+            self.ax.legend(loc='best')
+
+        return artists