ltpda 0.2.2__tar.gz → 0.2.3__tar.gz

{ltpda-0.2.2 → ltpda-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ltpda
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python fork of pyda (Hewitson et al.) — LTPDA-style signal processing with repository integration.
 License-File: LICENSE.md
 Author: Simon Barke
@@ -691,6 +691,38 @@ band = Sxx.split_by_frequency(freqs=[0.1, 1.0])
 
 ---
 
+### plotinfo — per-object style metadata
+
+`set_plotinfo()` attaches persistent style and legend metadata to any ltpda object.
+`iplot()` reads it automatically, with explicit `iplot()` kwargs taking priority.
+
+```python
+ts.set_plotinfo(color='steelblue', linewidth=2.5, linestyle='--')
+ts.iplot()   # steelblue dashed line, width 2.5 — no extra kwargs
+
+# Legend and error-bar control per object
+sig.set_plotinfo(include_in_legend=False)   # plotted but unlabelled
+calib.set_plotinfo(show_errors=True)        # error bars without ShowErrors=True kwarg
+
+# Marker style
+ts.set_plotinfo(marker='o', markersize=6, markerfacecolor='white', markeredgecolor='steelblue')
+```
+
+Full parameter list: `color`, `linestyle`, `linewidth`, `marker`, `markersize`,
+`markerfacecolor`, `markeredgecolor`, `fillmarkers`, `include_in_legend`, `show_errors`.
+
+**Priority chain for each style field** — `iplot()` kwarg → `plotinfo` field → object
+loose attribute (`obj.color`, `obj.linestyle`, …) → matplotlib default colour cycle.
+
+**Repository interoperability** — plotinfo survives XML round-trips between Python and MATLAB:
+- Python retrieve of a MATLAB AO: `<Style>` XML is parsed; `obj._plotinfo.color` is set to a
+  matplotlib hex string (`'#ff0000'`), all other fields populated from the XML attributes.
+- Python submit: `<Style>` is generated with the exact Java color encoding MATLAB expects
+  (`Color.getRGB()` signed 32-bit decimal).
+  MATLAB retrieves a fully styled AO with the correct color, linestyle, marker, etc.
+
+---
+
 ### File I/O
 
 Objects are serialised to HDF5 with a versioned format. The file extension is `.ltpda`.
@@ -957,6 +989,74 @@ The following open issues are tracked upstream at
 
 ## Version history
 
+### 0.2.3
+
+- `iplot()` — intelligent plot method mimicking MATLAB's `ao.iplot`:
+  - Smart data-type dispatch: `TSData` → linear axes; `FSData` → log-log with automatic
+    magnitude/phase subplots for complex data.
+  - `Arrangement='stacked'` (default) overlays all objects on the same axes.
+  - `Arrangement='subplots'` stacks each object in its own subplot row (single figure).
+  - `Arrangement='single'` opens one figure per object.
+  - `XScales` / `YScales` — per-axis scale override (`'log'` or `'lin'`);
+    a single string applies to all axes.
+  - `XRanges` / `YRanges` — per-axis `[min, max]` limits.
+  - `LineColors`, `LineStyles`, `LineWidths`, `Markers`, `MarkerSizes` — per-object
+    style control; shorter lists cycle; `['all', value]` applies one value to every trace.
+  - `MarkerFaceColor`, `MarkerEdgeColor` — independent marker fill and border colours;
+    same `['all', colour]` shorthand supported.
+  - `Legends='off'` suppresses legends; `Legends=['a', 'b']` overrides labels;
+    `LegendLocation` accepts MATLAB location strings (`'NorthEast'`, `'Best'`, …);
+    `LegendFontSize` controls font size; `ShowDescriptions=True` appends the object's
+    `.description` attribute to the legend label.
+  - `Titles` — per-subplot title strings (one per object in subplots/single arrangements).
+  - `XLabels` / `YLabels` — override axis label names; data units are still appended.
+  - `FigureNames` — set the figure suptitle / window title.
+  - `complexPlotType` — controls complex-data display: `'absdeg'` (magnitude + phase in °,
+    default), `'absrad'` (magnitude + phase in rad), `'realimag'` (real + imaginary parts).
+  - `ShowErrors=True` renders error bars from `ddata`; `ErrorBarType='bar'` (default)
+    or `'area'` (shaded band). Explicit per-object bounds via `YerrL`, `YerrU`,
+    `XerrL`, `XerrU`. `AUTOERRORS=False` disables automatic `ddata` detection.
+  - All keyword names match MATLAB's `iplot` exactly for zero relearning cost.
+- `plotinfo` — per-object style metadata that `iplot()` reads automatically.
+  `set_plotinfo(color, linestyle, linewidth, marker, markersize, markerfacecolor,
+  markeredgecolor, fillmarkers, include_in_legend, show_errors)` attaches a `PlotInfo`
+  to any ltpda object. Priority chain: `iplot()` kwarg > plotinfo field > object loose
+  attribute > matplotlib default. Full MATLAB XML round-trip: Python reads MATLAB
+  `<Style>` XML on retrieve (all color, linestyle, marker fields parsed into matplotlib
+  equivalents); Python emits exact MATLAB-compatible `<Style>` on submit (Java
+  `Color.getRGB()` decimal encoding).
+- Richer Python AO processing history — Python history nodes are now as informative
+  as MATLAB's and produce distinct per-operation groups in the MATLAB history browser:
+  - Each operation type gets its own blue cluster label instead of the generic
+    `Python/ltpda` bucket: `ao.ao (Python)` for constructors, `ao.psd (Python)` for
+    spectral estimates, `ao.plus (Python)` for arithmetic, etc.
+  - Constructor params are fully recorded: `FS`, `NSECS`, `YUNITS`, `WAVEFORM` (for
+    `randn` / `sinewave`), `A0`, `F0`, `PHI` (for `sinewave`), `DISTRIBUTION` / `SIGMA`
+    (for `randn`).
+  - DSP functions (`psd`, `logpsd`, `mscohere`, `cohere`, `cpsd`, `tfe`) now record a
+    history node that chains back to the input time-series, capturing `WINDOW`, `NAVS`,
+    `PERCENT_OVERLAP`, `NFFT`, `SCALE`, `DETREND_ORDER` (and `PSLL`, `OLAP`, `BMIN`,
+    `LMIN`, `JDES`, `KDES` for `logpsd`). Previously these functions produced no history
+    at all.
+  - `NoiseGen.generateNoise()` records `NSECS`, `FS`, `MODEL`, `YUNITS`.
+  - `__pow__` records `EXPONENT`.
+- `set_description(text)` — explicit setter on all ltpda objects (mirrors MATLAB's
+  `setDescription`). The `description` property remains directly assignable; this method
+  adds a consistent `set_*` style for use alongside `set_yaxis_name`, `set_plotinfo`, etc.
+- Bug fixes:
+  - History `context` attribute was silently dropped when Python read a MATLAB-serialized history
+    node from XML and re-submitted it. MATLAB's history browser uses `context` to render "blue tag"
+    cluster labels; losing it caused all pre-existing history steps to appear untagged after a
+    Python round-trip. Fixed by adding a `_context` field to `HistoryNode` and preserving the
+    attribute through the full read → write cycle.
+  - `proctime` on history nodes drifted by the system UTC offset on every Python round-trip.
+    `_parse_history_root` was creating naive datetimes via `datetime.utcfromtimestamp()`, which
+    `datetime.timestamp()` (in the serialiser) then treated as local time. Switched to
+    UTC-aware datetimes (`datetime.fromtimestamp(..., tz=timezone.utc)`) throughout.
+  - AO `UUID` was not preserved on retrieve: `_parse_ao` discarded the `UUID` attribute from
+    the `<ao>` element, so every re-submit generated a fresh random UUID. Now stamped onto
+    `obj.id` after parsing.
+
 ### 0.2.2
 
 - First pypi.org release

{ltpda-0.2.2 → ltpda-0.2.3}/README.md

@@ -665,6 +665,38 @@ band = Sxx.split_by_frequency(freqs=[0.1, 1.0])
 
 ---
 
+### plotinfo — per-object style metadata
+
+`set_plotinfo()` attaches persistent style and legend metadata to any ltpda object.
+`iplot()` reads it automatically, with explicit `iplot()` kwargs taking priority.
+
+```python
+ts.set_plotinfo(color='steelblue', linewidth=2.5, linestyle='--')
+ts.iplot()   # steelblue dashed line, width 2.5 — no extra kwargs
+
+# Legend and error-bar control per object
+sig.set_plotinfo(include_in_legend=False)   # plotted but unlabelled
+calib.set_plotinfo(show_errors=True)        # error bars without ShowErrors=True kwarg
+
+# Marker style
+ts.set_plotinfo(marker='o', markersize=6, markerfacecolor='white', markeredgecolor='steelblue')
+```
+
+Full parameter list: `color`, `linestyle`, `linewidth`, `marker`, `markersize`,
+`markerfacecolor`, `markeredgecolor`, `fillmarkers`, `include_in_legend`, `show_errors`.
+
+**Priority chain for each style field** — `iplot()` kwarg → `plotinfo` field → object
+loose attribute (`obj.color`, `obj.linestyle`, …) → matplotlib default colour cycle.
+
+**Repository interoperability** — plotinfo survives XML round-trips between Python and MATLAB:
+- Python retrieve of a MATLAB AO: `<Style>` XML is parsed; `obj._plotinfo.color` is set to a
+  matplotlib hex string (`'#ff0000'`), all other fields populated from the XML attributes.
+- Python submit: `<Style>` is generated with the exact Java color encoding MATLAB expects
+  (`Color.getRGB()` signed 32-bit decimal).
+  MATLAB retrieves a fully styled AO with the correct color, linestyle, marker, etc.
+
+---
+
 ### File I/O
 
 Objects are serialised to HDF5 with a versioned format. The file extension is `.ltpda`.
@@ -931,6 +963,74 @@ The following open issues are tracked upstream at
 
 ## Version history
 
+### 0.2.3
+
+- `iplot()` — intelligent plot method mimicking MATLAB's `ao.iplot`:
+  - Smart data-type dispatch: `TSData` → linear axes; `FSData` → log-log with automatic
+    magnitude/phase subplots for complex data.
+  - `Arrangement='stacked'` (default) overlays all objects on the same axes.
+  - `Arrangement='subplots'` stacks each object in its own subplot row (single figure).
+  - `Arrangement='single'` opens one figure per object.
+  - `XScales` / `YScales` — per-axis scale override (`'log'` or `'lin'`);
+    a single string applies to all axes.
+  - `XRanges` / `YRanges` — per-axis `[min, max]` limits.
+  - `LineColors`, `LineStyles`, `LineWidths`, `Markers`, `MarkerSizes` — per-object
+    style control; shorter lists cycle; `['all', value]` applies one value to every trace.
+  - `MarkerFaceColor`, `MarkerEdgeColor` — independent marker fill and border colours;
+    same `['all', colour]` shorthand supported.
+  - `Legends='off'` suppresses legends; `Legends=['a', 'b']` overrides labels;
+    `LegendLocation` accepts MATLAB location strings (`'NorthEast'`, `'Best'`, …);
+    `LegendFontSize` controls font size; `ShowDescriptions=True` appends the object's
+    `.description` attribute to the legend label.
+  - `Titles` — per-subplot title strings (one per object in subplots/single arrangements).
+  - `XLabels` / `YLabels` — override axis label names; data units are still appended.
+  - `FigureNames` — set the figure suptitle / window title.
+  - `complexPlotType` — controls complex-data display: `'absdeg'` (magnitude + phase in °,
+    default), `'absrad'` (magnitude + phase in rad), `'realimag'` (real + imaginary parts).
+  - `ShowErrors=True` renders error bars from `ddata`; `ErrorBarType='bar'` (default)
+    or `'area'` (shaded band). Explicit per-object bounds via `YerrL`, `YerrU`,
+    `XerrL`, `XerrU`. `AUTOERRORS=False` disables automatic `ddata` detection.
+  - All keyword names match MATLAB's `iplot` exactly for zero relearning cost.
+- `plotinfo` — per-object style metadata that `iplot()` reads automatically.
+  `set_plotinfo(color, linestyle, linewidth, marker, markersize, markerfacecolor,
+  markeredgecolor, fillmarkers, include_in_legend, show_errors)` attaches a `PlotInfo`
+  to any ltpda object. Priority chain: `iplot()` kwarg > plotinfo field > object loose
+  attribute > matplotlib default. Full MATLAB XML round-trip: Python reads MATLAB
+  `<Style>` XML on retrieve (all color, linestyle, marker fields parsed into matplotlib
+  equivalents); Python emits exact MATLAB-compatible `<Style>` on submit (Java
+  `Color.getRGB()` decimal encoding).
+- Richer Python AO processing history — Python history nodes are now as informative
+  as MATLAB's and produce distinct per-operation groups in the MATLAB history browser:
+  - Each operation type gets its own blue cluster label instead of the generic
+    `Python/ltpda` bucket: `ao.ao (Python)` for constructors, `ao.psd (Python)` for
+    spectral estimates, `ao.plus (Python)` for arithmetic, etc.
+  - Constructor params are fully recorded: `FS`, `NSECS`, `YUNITS`, `WAVEFORM` (for
+    `randn` / `sinewave`), `A0`, `F0`, `PHI` (for `sinewave`), `DISTRIBUTION` / `SIGMA`
+    (for `randn`).
+  - DSP functions (`psd`, `logpsd`, `mscohere`, `cohere`, `cpsd`, `tfe`) now record a
+    history node that chains back to the input time-series, capturing `WINDOW`, `NAVS`,
+    `PERCENT_OVERLAP`, `NFFT`, `SCALE`, `DETREND_ORDER` (and `PSLL`, `OLAP`, `BMIN`,
+    `LMIN`, `JDES`, `KDES` for `logpsd`). Previously these functions produced no history
+    at all.
+  - `NoiseGen.generateNoise()` records `NSECS`, `FS`, `MODEL`, `YUNITS`.
+  - `__pow__` records `EXPONENT`.
+- `set_description(text)` — explicit setter on all ltpda objects (mirrors MATLAB's
+  `setDescription`). The `description` property remains directly assignable; this method
+  adds a consistent `set_*` style for use alongside `set_yaxis_name`, `set_plotinfo`, etc.
+- Bug fixes:
+  - History `context` attribute was silently dropped when Python read a MATLAB-serialized history
+    node from XML and re-submitted it. MATLAB's history browser uses `context` to render "blue tag"
+    cluster labels; losing it caused all pre-existing history steps to appear untagged after a
+    Python round-trip. Fixed by adding a `_context` field to `HistoryNode` and preserving the
+    attribute through the full read → write cycle.
+  - `proctime` on history nodes drifted by the system UTC offset on every Python round-trip.
+    `_parse_history_root` was creating naive datetimes via `datetime.utcfromtimestamp()`, which
+    `datetime.timestamp()` (in the serialiser) then treated as local time. Switched to
+    UTC-aware datetimes (`datetime.fromtimestamp(..., tz=timezone.utc)`) throughout.
+  - AO `UUID` was not preserved on retrieve: `_parse_ao` discarded the `UUID` attribute from
+    the `<ao>` element, so every re-submit generated a fresh random UUID. Now stamped onto
+    `obj.id` after parsing.
+
 ### 0.2.2
 
 - First pypi.org release