fullplot 0.1.0__tar.gz → 0.1.1__tar.gz

{fullplot-0.1.0 → fullplot-0.1.1}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.1
+
+### Added
+
+* Added shared `TimeAxis.window(...)`, `clear_window()`, and `windowed(...)` support so every trace using the same time axis follows one common data window.
+* Added `TimeAxis.full_values`, `raw_count`, `raw_duration`, `raw_dt_array`, `window_range`, and `has_window` for working with the original and active time ranges.
+* Added `Trace.raw_y` so the original y-data remains available when a shared `TimeAxis` is windowed.
+* Added `xlim`, `ylim`, and `y2lim` plotting arguments for display-only axis limits.
+
+### Changed
+
+* Shared `TimeAxis` windowing now propagates automatically through attached traces, HDF5 trace extraction, and direct HDF5 plotting.
+* `TimeAxis.count`, `duration`, `dt_array`, and related active-axis properties now describe the current window, while the new `raw_*` properties describe the complete source axis.
+* Trace constructors that use a `TimeAxis` preserve the complete source-length data so windows can be changed or cleared later.
+
 ## 0.1.0
 
 ### Added

{fullplot-0.1.0 → fullplot-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fullplot
-Version: 0.1.0
+Version: 0.1.1
 Summary: A documented HDF5 plotting, trace-processing, and map-generation package for engineering simulation and test data.
 Keywords: hdf5,plotting,engineering,simulation,test-data,map-generation,scientific-computing
 Author: Saaketh Ramoju
@@ -60,48 +60,14 @@ FullPlot does **not** require a special FullFlow file format. If your HDF5 file
 
 ---
 
-## Repository status for 0.1.0
-
-FullPlot 0.1.0 is prepared as the first publish-ready public release of the package.
-
-There is no separate official documentation site yet, so the repository is intentionally documentation-heavy:
-
-* `README.md` is the primary user guide.
-* `CHANGELOG.md` records release-level changes and bug fixes.
-* `PUBLISHING.md` records the build, smoke-test, artifact-inspection, and upload checklist.
-* `THIRD_PARTY_LICENSES.md` records dependency and license notes.
-* `examples/` contains detailed runnable examples.
-* Public classes, functions, properties, and exceptions include docstrings so `help(fullplot.Trace)`, IDE inspection, and future generated API docs are useful immediately.
-
-The 0.1.0 release focuses on documentation, packaging, smoke testing, public API docstrings, and fixing obvious publish-blocking bugs. The core plotting, trace, and map-generation model is intentionally small.
-
----
-
 ## Installation
 
 ```bash
-pip install fullplot
+pip3 install fullplot
 ```
 
 FullPlot requires Python 3.11 or newer.
 
-For local development from the repository:
-
-```bash
-python -m venv .venv
-source .venv/bin/activate
-python -m pip install --upgrade pip
-python -m pip install -e .
-python -m pytest
-```
-
-With `uv`:
-
-```bash
-uv sync --dev
-uv run pytest
-```
-
 ---
 
 ## Quick start
@@ -255,7 +221,7 @@ The main classes are:
 | --- | --- |
 | `H5File` | Lightweight handle for one HDF5 file and root group. Created with `fplt.open(...)`. |
 | `Trace` | Reusable one-dimensional x/y data object. Used for raw data, filtered data, generated limits, commands, and derived traces. |
-| `TimeAxis` | Shared shiftable time basis. Several traces can share one time axis and be shifted together. |
+| `TimeAxis` | Shared shiftable and windowable time basis. Several traces can share one axis and follow the same alignment/window. |
 | `Axis` | Independent variable definition for rectangular-grid map generation. |
 
 Important exceptions are:
@@ -405,7 +371,7 @@ Shift the shared time axis so raw test time 95 seconds becomes model time zero:
 time.zero_at(95.0)
 ```
 
-All three traces now report shifted x-values because they share the same `TimeAxis` object.
+All three traces shift because they share the same `TimeAxis` object.
 
 Use `align(...)` when matching a raw data time to a model time:
 
@@ -413,33 +379,59 @@ Use `align(...)` when matching a raw data time to a model time:
 time.align(data_time=95.0, model_time=0.0)
 ```
 
+Window the shared time axis when every attached trace should use the same section of the test:
+
+```python
+time.window(start=2.0, stop=6.5)
+
+pc.x      # only 2.0 ... 6.5 s
+pc.y      # matching PCMC samples
+oipt.y    # matching OIPT samples
+fipt.y    # matching FIPT samples
+```
+
+The original arrays are preserved. Restore the full range with:
+
+```python
+time.clear_window()
+```
+
+Or create an independently windowed copy:
+
+```python
+mainstage_time = time.windowed(2.0, 6.5)
+```
+
 Useful `TimeAxis` attributes:
 
 ```python
-time.raw        # original samples
-time.values     # shifted samples
-time.value      # alias for values
-time.time       # alias for values
-time.zero       # current zero offset
-time.dt         # median sample spacing
-time.dt_array   # array of adjacent spacings
-time.duration   # raw time span
-time.is_uniform # approximate uniform-spacing check
+time.raw          # original unshifted samples
+time.full_values  # all shifted samples before windowing
+time.values       # shifted samples in the active window
+time.zero         # current zero offset
+time.count        # active sample count
+time.raw_count    # original sample count
+time.duration     # active time span
+time.raw_duration # original time span
+time.window_range # (start, stop)
+time.has_window   # whether a shared window is active
 ```
 
+For a trace that uses a shared `TimeAxis`, `trace.raw_y` gives the original y-array while `trace.y` follows the active time window.
+
 ---
 
 ## Missing values and windows
 
 FullPlot preserves non-finite y-values such as `NaN`. This is deliberate. Missing test-data samples should appear as gaps in plots instead of being connected by a misleading line.
 
-Create a windowed trace:
+Use `TimeAxis.window(...)` when several traces should be cropped together. Use `Trace.window(...)` when only one trace should be valid over part of the otherwise unchanged time axis:
 
 ```python
 startup = pc.window(start=0.0, stop=3.0, name="Startup Window")
 ```
 
-`Trace.window(...)` keeps the full time axis and replaces values outside the window with `NaN`. This is useful when a solver or comparison routine should know that the trace only provides valid data inside a specific interval.
+`Trace.window(...)` keeps its current x-axis and replaces y-values outside the interval with `NaN`. This is useful when a solver or comparison routine should treat one signal as unavailable outside that interval.
 
 Remove missing samples when you explicitly need compact finite data:
 
@@ -564,6 +556,7 @@ Trace metadata is stored as HDF5 attributes when possible.
 * HDF5 datasets and `Trace` objects in the same plot,
 * custom labels,
 * log x/y axes,
+* display-only `xlim`, `ylim`, and `y2lim` limits,
 * dark and light themes,
 * saving to PNG, SVG, PDF, or any Matplotlib-supported output,
 * returning Matplotlib objects for custom edits.
@@ -581,6 +574,9 @@ fig, axes = run.plot(
     ylabel="Pressure [psia]",
     y2label="Command [-]",
     title="Pressure and Valve Command",
+    xlim=(2.0, 8.0),
+    ylim=(0.0, 500.0),
+    y2lim=(-0.1, 1.1),
     theme="light",
     save="pressure_command.svg",
     show=False,
@@ -603,42 +599,227 @@ For trace-only plotting:
 fplt.plot([pc, pc_filtered, redline])
 ```
 
+Plot limits only change what is displayed; they do not window or modify the underlying trace data:
+
+```python
+fplt.plot([pc, oipt], xlim=(2.0, 6.5))
+```
+
 ---
 
-## Multidimensional datasets
+## Multidimensional datasets, axes, and slices
+
+FullPlot can plot and trace 2D or higher-dimensional datasets by selecting one dimension to vary and holding the other dimensions fixed.
+
+The two key arguments are:
 
-FullPlot can expand a 2D or higher-dimensional dataset into several line traces.
+| Argument | Meaning |
+| --- | --- |
+| `axis` | The dataset dimension that remains as the plotted line direction. |
+| `slice` | A dictionary of `{dimension_index: fixed_index}` values used to hold the other dimensions fixed. |
+
+For a dataset with shape:
 
-Use `axis` to choose which dimension becomes the line direction:
+```text
+(chamber_pressure, mixture_ratio, expansion_ratio, ambient_pressure, nfz)
+```
+
+the dimension numbers are:
+
+```text
+axis 0 -> chamber_pressure
+axis 1 -> mixture_ratio
+axis 2 -> expansion_ratio
+axis 3 -> ambient_pressure
+axis 4 -> nfz
+```
+
+So this call plots a line that varies along chamber pressure:
 
 ```python
 run.plot(
-    x="time",
-    y="pressure_grid",
-    axis=-1,
+    x="axes/chamber_pressure",
+    y="outputs/thrust_coefficient",
+    axis=0,
+    slice={
+        1: 12,  # fixed mixture_ratio index
+        2: 10,  # fixed expansion_ratio index
+        3: 3,   # fixed ambient_pressure index
+        4: 0,   # fixed nfz index
+    },
+    xlabel="Chamber Pressure [Pa]",
+    ylabel="Thrust Coefficient [-]",
 )
 ```
 
-Use `slice` to reduce higher-dimensional arrays before plotting:
+The dimension selected by `axis` is the dimension that becomes the line. The dimensions listed in `slice` are reduced to one fixed index.
+
+### Creating traces from multidimensional data
+
+`trace(...)` accepts the same `axis` and `slice` arguments as `plot(...)`. This makes it possible to create reusable traces from multidimensional map data and then plot them together.
 
 ```python
-run.plot(
-    x="time",
-    y="pressure_3d",
-    slice={0: 1},
-    axis=-1,
+import fullplot as fplt
+
+psia_to_pa = 6894.75728
+
+file = fplt.open("sizer_lookups.h5")
+result = file.at("/engine_lookup")
+
+pc_psia = result.read("axes/chamber_pressure") / psia_to_pa
+
+cf_eps_4 = result.trace(
+    y="outputs/thrust_coefficient",
+    x=pc_psia,
+    axis=0,
+    slice={
+        1: 12,  # mixture_ratio index
+        2: 8,   # expansion_ratio index
+        3: 3,   # ambient_pressure index
+        4: 0,   # nfz index
+    },
+    name="eps = 4",
+)
+
+cf_eps_6 = result.trace(
+    y="outputs/thrust_coefficient",
+    x=pc_psia,
+    axis=0,
+    slice={
+        1: 12,
+        2: 14,
+        3: 3,
+        4: 0,
+    },
+    name="eps = 6",
+)
+
+result.plot(
+    y=[cf_eps_4, cf_eps_6],
+    xlabel="Chamber Pressure [psia]",
+    ylabel="Thrust Coefficient [-]",
+    title="Thrust Coefficient vs Chamber Pressure",
 )
 ```
 
-The same idea applies to maps. A 3D dataset can become a 2D heat map after slicing:
+This is equivalent to manually extracting:
 
 ```python
-run.map(
-    z="temperature_3d",
-    slice={0: 2},
+cf[:, 12, 8, 3, 0]   # eps = 4 trace
+cf[:, 12, 14, 3, 0]  # eps = 6 trace
+```
+
+but keeps the plotting workflow trace-based.
+
+### Selecting nearest physical values
+
+`slice` uses integer indices, not physical axis values. If you want to select the nearest value on an axis, use a small helper:
+
+```python
+import numpy as np
+
+
+def nearest_index(values, target):
+    values = np.asarray(values, dtype=float)
+    return int(np.argmin(np.abs(values - target)))
+```
+
+Example:
+
+```python
+mr = result.read("axes/mixture_ratio")
+eps = result.read("axes/expansion_ratio")
+pamb_psia = result.read("axes/ambient_pressure") / psia_to_pa
+nfz = result.read("axes/nfz")
+
+mr_i = nearest_index(mr, 2.5)
+pamb_i = nearest_index(pamb_psia, 14.7)
+nfz_i = nearest_index(nfz, 0)
+
+traces = []
+
+for target_eps in [2, 4, 6, 8, 10]:
+    eps_i = nearest_index(eps, target_eps)
+
+    traces.append(
+        result.trace(
+            y="outputs/thrust_coefficient",
+            x=pc_psia,
+            axis=0,
+            slice={
+                1: mr_i,
+                2: eps_i,
+                3: pamb_i,
+                4: nfz_i,
+            },
+            name=f"eps = {eps[eps_i]:.1f}",
+        )
+    )
+
+result.plot(
+    y=traces,
+    xlabel="Chamber Pressure [psia]",
+    ylabel="Thrust Coefficient [-]",
+    title="Thrust Coefficient vs Chamber Pressure",
+)
+```
+
+### Common slicing patterns
+
+For a dataset ordered as:
+
+```text
+(chamber_pressure, mixture_ratio, expansion_ratio, ambient_pressure, nfz)
+```
+
+these are common one-dimensional traces:
+
+```python
+cf[:, mr_i, eps_i, pamb_i, nfz_i]      # vary chamber pressure
+cf[pc_i, :, eps_i, pamb_i, nfz_i]      # vary mixture ratio
+cf[pc_i, mr_i, :, pamb_i, nfz_i]       # vary expansion ratio
+cf[pc_i, mr_i, eps_i, :, nfz_i]        # vary ambient pressure
+cf[pc_i, mr_i, eps_i, pamb_i, :]       # vary nfz
+```
+
+The matching FullPlot arguments are:
+
+```python
+# Vary chamber pressure.
+axis=0
+slice={1: mr_i, 2: eps_i, 3: pamb_i, 4: nfz_i}
+
+# Vary mixture ratio.
+axis=1
+slice={0: pc_i, 2: eps_i, 3: pamb_i, 4: nfz_i}
+
+# Vary expansion ratio.
+axis=2
+slice={0: pc_i, 1: mr_i, 3: pamb_i, 4: nfz_i}
+```
+
+### Slicing for heat maps
+
+For heat maps, leave two dimensions unsliced. For example, to plot thrust coefficient as a function of mixture ratio and chamber pressure, hold expansion ratio, ambient pressure, and `nfz` fixed:
+
+```python
+result.map(
+    z="outputs/thrust_coefficient",
+    x="axes/mixture_ratio",
+    y="axes/chamber_pressure",
+    slice={
+        2: eps_i,
+        3: pamb_i,
+        4: nfz_i,
+    },
+    xlabel="Mixture Ratio [-]",
+    ylabel="Chamber Pressure [Pa]",
+    zlabel="Thrust Coefficient [-]",
 )
 ```
 
+Use `xscale="log"`, `yscale="log"`, or `zscale="log"` only when the displayed values on that axis are positive.
+
 ---
 
 ## Heat maps
@@ -917,40 +1098,19 @@ This is deliberate. The package is meant to be a simple bridge between HDF5 engi
 
 ---
 
-## Development checks
+# Documentation
 
-Useful local checks:
+Full documentation:
 
-```bash
-python -m compileall -q src tests examples
-python -m pytest -q
-uv build
-```
+https://saakethramoju.github.io/softwares/fullplot/
 
-A minimal smoke test:
+Source code:
 
-```python
-import tempfile
-from pathlib import Path
-
-import h5py
-import numpy as np
-import fullplot as fplt
-
-with tempfile.TemporaryDirectory() as tmp:
-    filename = Path(tmp) / "demo.h5"
+https://github.com/saakethramoju/FullPlot
 
-    with h5py.File(filename, "w") as h5:
-        h5["time"] = np.linspace(0.0, 1.0, 11)
-        h5["pressure"] = np.linspace(100.0, 200.0, 11)
+PyPI:
 
-    run = fplt.open(filename)
-    time = run.time("time")
-    pressure = run.trace("pressure", x=time)
-    redline = fplt.Trace.constant("redline", x=time, y=250.0, role="redline")
-    run.plot(x="time", y="pressure", show=False)
-    fplt.plot([pressure, redline], show=False)
-```
+https://pypi.org/project/fullplot/
 
 ---