sdf-xarray 0.2.1__cp313-cp313-win_amd64.whl → 0.3.2__cp313-cp313-win_amd64.whl

sdf_xarray/__init__.py

@@ -1,13 +1,17 @@
+import contextlib
 import os
 import re
 from collections import Counter, defaultdict
 from collections.abc import Callable, Iterable
+from importlib.metadata import version
 from itertools import product
+from os import PathLike as os_PathLike
 from pathlib import Path
 from typing import ClassVar
 
 import numpy as np
 import xarray as xr
+from packaging.version import Version
 from xarray.backends import AbstractDataStore, BackendArray, BackendEntrypoint
 from xarray.backends.file_manager import CachingFileManager
 from xarray.backends.locks import ensure_lock
@@ -15,8 +19,24 @@ from xarray.core import indexing
 from xarray.core.utils import close_on_error, try_read_magic_number_from_path
 from xarray.core.variable import Variable
 
+# NOTE: Do not delete these lines, otherwise the "epoch" dataset and dataarray
+# accessors will not be imported when the user imports sdf_xarray
+import sdf_xarray.dataset_accessor
+import sdf_xarray.plotting  # noqa: F401
+
+# NOTE: This attempts to initialise with the "pint" accessor if the user
+# has installed the package
+with contextlib.suppress(ImportError):
+    import pint_xarray  # noqa: F401
+
 from .sdf_interface import Constant, SDFFile  # type: ignore  # noqa: PGH003
 
+# TODO Remove this once the new kwarg options are fully implemented
+if Version(version("xarray")) >= Version("2025.8.0"):
+    xr.set_options(use_new_combine_kwarg_defaults=True)
+
+PathLike = str | os_PathLike
+
 
 def _rename_with_underscore(name: str) -> str:
     """A lot of the variable names have spaces, forward slashes and dashes in them, which
@@ -47,14 +67,69 @@ def _process_latex_name(variable_name: str) -> str:
     return variable_name
 
 
-def combine_datasets(path_glob: Iterable | str, **kwargs) -> xr.Dataset:
-    """Combine all datasets using a single time dimension"""
+def _resolve_glob(path_glob: PathLike | Iterable[PathLike]):
+    """
+    Normalise input path_glob into a sorted list of absolute, resolved Path objects.
+    """
+
+    try:
+        p = Path(path_glob)
+        paths = list(p.parent.glob(p.name)) if p.name == "*.sdf" else list(p)
+    except TypeError:
+        paths = list({Path(p) for p in path_glob})
+
+    paths = sorted(p.resolve() for p in paths)
+    if not paths:
+        raise FileNotFoundError(f"No files matched pattern or input: {path_glob!r}")
+    return paths
+
+
+def purge_unselected_data_vars(ds: xr.Dataset, data_vars: list[str]) -> xr.Dataset:
+    """
+    If the user has exclusively requested only certain variables be
+    loaded in then we purge all other variables and dimensions
+    """
+    existing_data_vars = set(ds.data_vars.keys())
+    vars_to_keep = set(data_vars) & existing_data_vars
+    vars_to_drop = existing_data_vars - vars_to_keep
+    ds = ds.drop_vars(vars_to_drop)
+
+    existing_dims = set(ds.sizes)
+    dims_to_keep = set()
+    for var in vars_to_keep:
+        dims_to_keep.update(ds[var].coords._names)
+        dims_to_keep.update(ds[var].dims)
+
+    coords_to_drop = existing_dims - dims_to_keep
+    return ds.drop_dims(coords_to_drop)
+
+
+def combine_datasets(
+    path_glob: Iterable | str, data_vars: list[str], **kwargs
+) -> xr.Dataset:
+    """
+    Combine all datasets using a single time dimension, optionally extract
+    data from only the listed data_vars
+    """
+
+    if data_vars is not None:
+        return xr.open_mfdataset(
+            path_glob,
+            join="outer",
+            coords="different",
+            compat="no_conflicts",
+            combine="nested",
+            concat_dim="time",
+            preprocess=SDFPreprocess(data_vars=data_vars),
+            **kwargs,
+        )
 
     return xr.open_mfdataset(
         path_glob,
-        data_vars="minimal",
-        coords="minimal",
-        compat="override",
+        data_vars="all",
+        coords="different",
+        compat="no_conflicts",
+        join="outer",
         preprocess=SDFPreprocess(),
         **kwargs,
     )
@@ -65,6 +140,8 @@ def open_mfdataset(
     *,
     separate_times: bool = False,
     keep_particles: bool = False,
+    probe_names: list[str] | None = None,
+    data_vars: list[str] | None = None,
 ) -> xr.Dataset:
     """Open a set of EPOCH SDF files as one `xarray.Dataset`
 
@@ -94,20 +171,36 @@ def open_mfdataset(
         different output frequencies
     keep_particles :
         If ``True``, also load particle data (this may use a lot of memory!)
+    probe_names :
+        List of EPOCH probe names
+    data_vars :
+        List of data vars to load in (If not specified loads in all variables)
     """
 
-    # TODO: This is not very robust, look at how xarray.open_mfdataset does it
-    if isinstance(path_glob, str):
-        path_glob = Path().glob(path_glob)
-
-    # Coerce to list because we might need to use the sequence multiple times
-    path_glob = sorted(list(path_glob))  # noqa: C414
+    path_glob = _resolve_glob(path_glob)
 
     if not separate_times:
-        return combine_datasets(path_glob, keep_particles=keep_particles)
+        return combine_datasets(
+            path_glob,
+            data_vars=data_vars,
+            keep_particles=keep_particles,
+            probe_names=probe_names,
+        )
+
+    _, var_times_map = make_time_dims(path_glob)
+
+    all_dfs = []
+    for f in path_glob:
+        ds = xr.open_dataset(f, keep_particles=keep_particles, probe_names=probe_names)
+
+        # If the data_vars are specified then only load them in and disregard the rest.
+        # If there are no remaining data variables then skip adding the dataset to list
+        if data_vars is not None:
+            ds = purge_unselected_data_vars(ds, data_vars)
+            if not ds.data_vars:
+                continue
 
-    time_dims, var_times_map = make_time_dims(path_glob)
-    all_dfs = [xr.open_dataset(f, keep_particles=keep_particles) for f in path_glob]
+        all_dfs.append(ds)
 
     for df in all_dfs:
         for da in df:
@@ -124,7 +217,11 @@ def open_mfdataset(
                 )
 
     return xr.combine_by_coords(
-        all_dfs, data_vars="minimal", combine_attrs="drop_conflicts"
+        all_dfs,
+        coords="different",
+        combine_attrs="drop_conflicts",
+        join="outer",
+        compat="no_conflicts",
     )
 
 
@@ -207,14 +304,23 @@ class SDFDataStore(AbstractDataStore):
         "drop_variables",
         "keep_particles",
         "lock",
+        "probe_names",
     )
 
-    def __init__(self, manager, drop_variables=None, keep_particles=False, lock=None):
+    def __init__(
+        self,
+        manager,
+        drop_variables=None,
+        keep_particles=False,
+        lock=None,
+        probe_names=None,
+    ):
         self._manager = manager
         self._filename = self.ds.filename
         self.drop_variables = drop_variables
         self.keep_particles = keep_particles
         self.lock = ensure_lock(lock)
+        self.probe_names = probe_names
 
     @classmethod
     def open(
@@ -223,6 +329,7 @@ class SDFDataStore(AbstractDataStore):
         lock=None,
         drop_variables=None,
         keep_particles=False,
+        probe_names=None,
     ):
         if isinstance(filename, os.PathLike):
             filename = os.fspath(filename)
@@ -233,6 +340,7 @@ class SDFDataStore(AbstractDataStore):
             lock=lock,
             drop_variables=drop_variables,
             keep_particles=keep_particles,
+            probe_names=probe_names,
         )
 
     def _acquire(self, needs_lock=True):
@@ -249,9 +357,18 @@ class SDFDataStore(AbstractDataStore):
     def load(self):  # noqa: PLR0912, PLR0915
         # Drop any requested variables
         if self.drop_variables:
+            # Build a mapping from underscored names to real variable names
+            name_map = {_rename_with_underscore(var): var for var in self.ds.variables}
+
             for variable in self.drop_variables:
-                # TODO: nicer error handling
-                self.ds.variables.pop(variable)
+                key = _rename_with_underscore(variable)
+                original_name = name_map.get(key)
+
+                if original_name is None:
+                    raise KeyError(
+                        f"Variable '{variable}' not found (interpreted as '{key}')."
+                    )
+                self.ds.variables.pop(original_name)
 
         # These two dicts are global metadata about the run or file
         attrs = {**self.ds.header, **self.ds.run_info}
@@ -306,6 +423,8 @@ class SDFDataStore(AbstractDataStore):
             # Had some problems with these variables, so just ignore them for now
             if "cpu" in key.lower():
                 continue
+            if "boundary" in key.lower():
+                continue
             if "output file" in key.lower():
                 continue
 
@@ -332,7 +451,28 @@ class SDFDataStore(AbstractDataStore):
 
             if value.is_point_data:
                 # Point (particle) variables are 1D
-                var_coords = (f"ID_{_process_grid_name(key, _grid_species_name)}",)
+
+                # Particle data does not maintain a fixed dimension size
+                # throughout the simulation. An example of a particle name comes
+                # in the form of `Particles/Px/Ion_H` which is then modified
+                # using `_process_grid_name()` into `Ion_H`. This is fine as the
+                # other components of the momentum (`Py`, `Pz`) will have the same
+                # size as they represent the same bunch of particles.
+
+                # Probes however have names in the form of `Electron_Front_Probe/Px`
+                # which are changed to just `Px`; this is fine when there is only one
+                # probe in the system but when there are multiple they will have
+                # conflicting sizes so we can't keep the names as simply `Px` so we
+                # instead set their dimension as the full name `Electron_Front_Probe_Px`.
+                is_probe_name_match = self.probe_names is not None and any(
+                    name in key for name in self.probe_names
+                )
+                name_processor = (
+                    _rename_with_underscore
+                    if is_probe_name_match
+                    else _grid_species_name
+                )
+                var_coords = (f"ID_{_process_grid_name(key, name_processor)}",)
             else:
                 # These are DataArrays
 
@@ -399,6 +539,7 @@ class SDFEntrypoint(BackendEntrypoint):
         *,
         drop_variables=None,
         keep_particles=False,
+        probe_names=None,
     ):
         if isinstance(filename_or_obj, Path):
             # sdf library takes a filename only
@@ -409,6 +550,7 @@ class SDFEntrypoint(BackendEntrypoint):
             filename_or_obj,
             drop_variables=drop_variables,
             keep_particles=keep_particles,
+            probe_names=probe_names,
         )
         with close_on_error(store):
             return store.load()
@@ -417,6 +559,7 @@ class SDFEntrypoint(BackendEntrypoint):
         "filename_or_obj",
         "drop_variables",
         "keep_particles",
+        "probe_names",
     ]
 
     def guess_can_open(self, filename_or_obj):
@@ -428,14 +571,47 @@ class SDFEntrypoint(BackendEntrypoint):
 
     description = "Use .sdf files in Xarray"
 
-    url = "https://epochpic.github.io/documentation/visualising_output/python.html"
+    url = "https://epochpic.github.io/documentation/visualising_output/python_beam.html"
 
 
 class SDFPreprocess:
-    """Preprocess SDF files for xarray ensuring matching job ids and sets time dimension"""
+    """Preprocess SDF files for xarray ensuring matching job ids and sets
+    time dimension.
+
+    This class is used as a 'preprocess' function within ``xr.open_mfdataset``. It
+    performs three main duties on each individual file's Dataset:
+
+    1. Checks for a **matching job ID** across all files to ensure dataset consistency.
+    2. **Filters** the Dataset to keep only the variables specified in `data_vars`
+       and their required coordinates.
+    3. **Expands dimensions** to include a single 'time' coordinate, preparing the
+       Dataset for concatenation.
+
+    EPOCH can output variables at different intervals, so some SDF files
+    may not contain the requested variable. We combine this data into one
+    dataset by concatenating across the time dimension.
 
-    def __init__(self):
+    The combination is performed using ``join="outer"`` (in the calling ``open_mfdataset`` function),
+    meaning that the final combined dataset will contain the variable across the
+    entire time span, with NaNs filling the time steps where the variable was absent in
+    the individual file.
+
+    With large SDF files, this filtering method will save on memory consumption when
+    compared to loading all variables from all files before concatenation.
+
+    Parameters
+    ----------
+    data_vars :
+        A list of data variables to load in (If not specified loads
+        in all variables)
+    """
+
+    def __init__(
+        self,
+        data_vars: list[str] | None = None,
+    ):
         self.job_id: int | None = None
+        self.data_vars = data_vars
 
     def __call__(self, ds: xr.Dataset) -> xr.Dataset:
         if self.job_id is None:
@@ -446,17 +622,23 @@ class SDFPreprocess:
                 f"Mismatching job ids (got {ds.attrs['jobid1']}, expected {self.job_id})"
             )
 
-        ds = ds.expand_dims(time=[ds.attrs["time"]])
+        # If the user has exclusively requested only certain variables be
+        # loaded in then we purge all other variables and coordinates
+        if self.data_vars:
+            ds = purge_unselected_data_vars(ds, self.data_vars)
+
+        time_val = ds.attrs.get("time", np.nan)
+        ds = ds.expand_dims(time=[time_val])
         ds = ds.assign_coords(
             time=(
                 "time",
-                [ds.attrs["time"]],
+                [time_val],
                 {"units": "s", "long_name": "Time", "full_name": "time"},
             )
         )
         # Particles' spartial coordinates also evolve in time
         for coord, value in ds.coords.items():
             if value.attrs.get("point_data", False):
-                ds.coords[coord] = value.expand_dims(time=[ds.attrs["time"]])
+                ds.coords[coord] = value.expand_dims(time=[time_val])
 
         return ds

sdf_xarray/_version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.1'
-__version_tuple__ = version_tuple = (0, 2, 1)
+__version__ = version = '0.3.2'
+__version_tuple__ = version_tuple = (0, 3, 2)
+
+__commit_id__ = commit_id = 'g331520e50'

sdf_xarray/dataset_accessor.py

@@ -0,0 +1,73 @@
+from typing import Union
+
+import xarray as xr
+
+
+@xr.register_dataset_accessor("epoch")
+class EpochAccessor:
+    def __init__(self, xarray_obj: xr.Dataset):
+        # The xarray object is the Dataset, which we store as self._ds
+        self._ds = xarray_obj
+
+    def rescale_coords(
+        self,
+        multiplier: float,
+        unit_label: str,
+        coord_names: Union[str, list[str]],
+    ) -> xr.Dataset:
+        """
+        Rescales specified X and Y coordinates in the Dataset by a given multiplier
+        and updates the unit label attribute.
+
+        Parameters
+        ----------
+        multiplier : float
+            The factor by which to multiply the coordinate values (e.g., 1e6 for meters to microns).
+        unit_label : str
+            The new unit label for the coordinates (e.g., "µm").
+        coord_names : str or list of str
+            The name(s) of the coordinate variable(s) to rescale.
+            If a string, only that coordinate is rescaled.
+            If a list, all listed coordinates are rescaled.
+
+        Returns
+        -------
+        xr.Dataset
+            A new Dataset with the updated and rescaled coordinates.
+
+        Examples
+        --------
+        # Convert X, Y, and Z from meters to microns
+        >>> ds_in_microns = ds.epoch.rescale_coords(1e6, "µm", coord_names=["X_Grid", "Y_Grid", "Z_Grid"])
+
+        # Convert only X to millimeters
+        >>> ds_in_mm = ds.epoch.rescale_coords(1000, "mm", coord_names="X_Grid")
+        """
+
+        ds = self._ds
+        new_coords = {}
+
+        if isinstance(coord_names, str):
+            # Convert single string to a list
+            coords_to_process = [coord_names]
+        elif isinstance(coord_names, list):
+            # Use the provided list
+            coords_to_process = coord_names
+        else:
+            coords_to_process = list(coord_names)
+
+        for coord_name in coords_to_process:
+            if coord_name not in ds.coords:
+                raise ValueError(
+                    f"Coordinate '{coord_name}' not found in the Dataset. Cannot rescale."
+                )
+
+            coord_original = ds[coord_name]
+
+            coord_rescaled = coord_original * multiplier
+            coord_rescaled.attrs = coord_original.attrs.copy()
+            coord_rescaled.attrs["units"] = unit_label
+
+            new_coords[coord_name] = coord_rescaled
+
+        return ds.assign_coords(new_coords)

sdf_xarray/plotting.py

@@ -10,60 +10,82 @@ if TYPE_CHECKING:
     from matplotlib.animation import FuncAnimation
 
 
-def get_frame_title(data: xr.DataArray, frame: int, display_sdf_name: bool) -> str:
+def get_frame_title(
+    data: xr.DataArray,
+    frame: int,
+    display_sdf_name: bool = False,
+    title_custom: str | None = None,
+) -> str:
     """Generate the title for a frame"""
-    sdf_name = f", {frame:04d}.sdf" if display_sdf_name else ""
+    # Adds custom text to the start of the title, if specified
+    title_custom = "" if title_custom is None else f"{title_custom}, "
+    # Adds the time and associated units to the title
     time = data["time"][frame].to_numpy()
-    return f"t = {time:.2e}s{sdf_name}"
 
+    time_units = data["time"].attrs.get("units", False)
+    time_units_formatted = f" [{time_units}]" if time_units else ""
+    title_time = f"time = {time:.2e}{time_units_formatted}"
 
-def calculate_window_velocity_and_edges(
-    data: xr.DataArray, x_axis_coord: str
-) -> tuple[float, tuple[float, float], np.ndarray]:
-    """Calculate the moving window's velocity and initial edges.
+    # Adds sdf name to the title, if specifed
+    title_sdf = f", {frame:04d}.sdf" if display_sdf_name else ""
+    return f"{title_custom}{title_time}{title_sdf}"
 
-    1. Finds a lineout of the target atribute in the x coordinate of the first frame
-    2. Removes the NaN values to isolate the simulation window
-    3. Produces the index size of the window, indexed at zero
-    4. Uses distance moved and final time of the simulation to calculate velocity and initial xlims
-    """
-    time_since_start = data["time"].values - data["time"].values[0]
-    initial_window_edge = (0, 0)
-    target_lineout = data.values[0, :, 0]
-    target_lineout_window = target_lineout[~np.isnan(target_lineout)]
-    x_grid = data[x_axis_coord].values
-    window_size_index = target_lineout_window.size - 1
 
-    velocity_window = (x_grid[-1] - x_grid[window_size_index]) / time_since_start[-1]
-    initial_window_edge = (x_grid[0], x_grid[window_size_index])
-    return velocity_window, initial_window_edge, time_since_start
+def calculate_window_boundaries(
+    data: xr.DataArray, xlim: tuple[float, float] | False = False
+) -> np.ndarray:
+    """Calculate the bounderies a moving window frame. If the user specifies xlim, this will
+    be used as the initial bounderies and the window will move along acordingly.
+    """
+    x_grid = data["X_Grid_mid"].values
+    x_half_cell = (x_grid[1] - x_grid[0]) / 2
+    N_frames = data["time"].size
 
+    # Find the window bounderies by finding the first and last non-NaN values in the 0th lineout
+    # along the x-axis.
+    window_boundaries = np.zeros((N_frames, 2))
+    for i in range(N_frames):
+        # Check if data is 1D
+        if data.ndim == 2:
+            target_lineout = data[i].values
+        # Check if data is 2D
+        if data.ndim == 3:
+            target_lineout = data[i, :, 0].values
+        x_grid_non_nan = x_grid[~np.isnan(target_lineout)]
+        window_boundaries[i, 0] = x_grid_non_nan[0] - x_half_cell
+        window_boundaries[i, 1] = x_grid_non_nan[-1] + x_half_cell
 
-def compute_global_limits(data: xr.DataArray) -> tuple[float, float]:
-    """Remove all NaN values from the target data to calculate the 1st and 99th percentiles,
-    excluding extreme outliers.
-    """
-    values_no_nan = data.values[~np.isnan(data.values)]
-    global_min = np.percentile(values_no_nan, 1)
-    global_max = np.percentile(values_no_nan, 99)
-    return global_min, global_max
+    # User's choice for initial window edge supercides the one calculated
+    if xlim:
+        window_boundaries = window_boundaries + xlim - window_boundaries[0]
+    return window_boundaries
 
 
-def is_1d(data: xr.DataArray) -> bool:
-    """Check if the data is 1D."""
-    return len(data.shape) == 2
+def compute_global_limits(
+    data: xr.DataArray,
+    min_percentile: float = 0,
+    max_percentile: float = 100,
+) -> tuple[float, float]:
+    """Remove all NaN values from the target data to calculate the global minimum and maximum of the data.
+    User defined percentiles can remove extreme outliers.
+    """
 
+    # Removes NaN values, needed for moving windows
+    values_no_nan = data.values[~np.isnan(data.values)]
 
-def is_2d(data: xr.DataArray) -> bool:
-    """Check if the data is 2D or 3D."""
-    return len(data.shape) == 3
+    # Finds the global minimum and maximum of the plot, based on the percentile of the data
+    global_min = np.percentile(values_no_nan, min_percentile)
+    global_max = np.percentile(values_no_nan, max_percentile)
+    return global_min, global_max
 
 
-def generate_animation(
+def animate(
     data: xr.DataArray,
+    fps: float = 10,
+    min_percentile: float = 0,
+    max_percentile: float = 100,
+    title: str | None = None,
     display_sdf_name: bool = False,
-    fps: int = 10,
-    move_window: bool = False,
     ax: plt.Axes | None = None,
     **kwargs,
 ) -> FuncAnimation:
@@ -71,17 +93,18 @@ def generate_animation(
 
     Parameters
     ---------
-    dataset
-        The dataset containing the simulation data
-    target_attribute
-        The attribute to plot for each timestep
-    display_sdf_name
-        Display the sdf file name in the animation title
+    data
+        The dataarray containing the target data
     fps
         Frames per second for the animation (default: 10)
-    move_window
-        If the simulation has a moving window, the animation will move along
-        with it (default: False)
+    min_percentile
+        Minimum percentile of the data (default: 0)
+    max_percentile
+        Maximum percentile of the data (default: 100)
+    title
+        Custom title to add to the plot.
+    display_sdf_name
+        Display the sdf file name in the animation title
     ax
         Matplotlib axes on which to plot.
     kwargs
@@ -89,18 +112,28 @@ def generate_animation(
 
     Examples
     --------
-    >>> generate_animation(dataset["Derived_Number_Density_Electron"])
+    >>> dataset["Derived_Number_Density_Electron"].epoch.animate()
     """
-    import matplotlib.pyplot as plt
-    from matplotlib.animation import FuncAnimation
+    import matplotlib.pyplot as plt  # noqa: PLC0415
+    from matplotlib.animation import FuncAnimation  # noqa: PLC0415
+
+    kwargs_original = kwargs.copy()
 
     if ax is None:
         _, ax = plt.subplots()
 
     N_frames = data["time"].size
-    global_min, global_max = compute_global_limits(data)
+    global_min, global_max = compute_global_limits(data, min_percentile, max_percentile)
 
-    if is_2d(data):
+    # Initialise plot and set y-limits for 1D data
+    if data.ndim == 2:
+        kwargs.setdefault("x", "X_Grid_mid")
+        plot = data.isel(time=0).plot(ax=ax, **kwargs)
+        ax.set_title(get_frame_title(data, 0, display_sdf_name, title))
+        ax.set_ylim(global_min, global_max)
+
+    # Initilise plot and set colour bar for 2D data
+    if data.ndim == 3:
         kwargs["norm"] = plt.Normalize(vmin=global_min, vmax=global_max)
         kwargs["add_colorbar"] = False
         # Set default x and y coordinates for 2D data if not provided
@@ -109,44 +142,32 @@ def generate_animation(
 
         # Initialize the plot with the first timestep
         plot = data.isel(time=0).plot(ax=ax, **kwargs)
-        ax.set_title(get_frame_title(data, 0, display_sdf_name))
+        ax.set_title(get_frame_title(data, 0, display_sdf_name, title))
 
         # Add colorbar
-        long_name = data.attrs.get("long_name")
-        units = data.attrs.get("units")
-        plt.colorbar(plot, ax=ax, label=f"{long_name} [${units}$]")
-
-    # Initialise plo and set y-limits for 1D data
-    if is_1d(data):
-        plot = data.isel(time=0).plot(ax=ax, **kwargs)
-        ax.set_title(get_frame_title(data, 0, display_sdf_name))
-        ax.set_ylim(global_min, global_max)
+        if kwargs_original.get("add_colorbar", True):
+            long_name = data.attrs.get("long_name")
+            units = data.attrs.get("units")
+            plt.colorbar(plot, ax=ax, label=f"{long_name} [${units}$]")
 
+    # check if there is a moving window by finding NaNs in the data
+    move_window = np.isnan(np.sum(data.values))
     if move_window:
-        window_velocity, window_initial_edge, time_since_start = (
-            calculate_window_velocity_and_edges(data, kwargs["x"])
-        )
-
-    # User's choice for initial window edge supercides the one calculated
-    if "xlim" in kwargs:
-        window_initial_edge = kwargs["xlim"]
+        window_boundaries = calculate_window_boundaries(data, kwargs.get("xlim", False))
 
     def update(frame):
         # Set the xlim for each frame in the case of a moving window
         if move_window:
-            kwargs["xlim"] = (
-                window_initial_edge[0] + window_velocity * time_since_start[frame],
-                window_initial_edge[1] * 0.99
-                + window_velocity * time_since_start[frame],
-            )
+            kwargs["xlim"] = window_boundaries[frame]
 
         # Update plot for the new frame
         ax.clear()
+
         data.isel(time=frame).plot(ax=ax, **kwargs)
-        ax.set_title(get_frame_title(data, frame, display_sdf_name))
+        ax.set_title(get_frame_title(data, frame, display_sdf_name, title))
 
-        # # Update y-limits for 1D data
-        if is_1d(data):
+        # Update y-limits for 1D data
+        if data.ndim == 2:
             ax.set_ylim(global_min, global_max)
 
     return FuncAnimation(
@@ -181,4 +202,4 @@ class EpochAccessor:
         >>> ani = ds["Electric_Field_Ey"].epoch.animate()
         >>> ani.save("myfile.mp4")
         """
-        return generate_animation(self._obj, *args, **kwargs)
+        return animate(self._obj, *args, **kwargs)

sdf_xarray/sdf_interface.pyx

@@ -39,7 +39,7 @@ cdef class Block:
 
 @dataclasses.dataclass
 cdef class Variable(Block):
-    units: tuple[str] | None
+    units: str | None
     mult: float | None
     grid: str | None
     grid_mid: str | None

{sdf_xarray-0.2.1.dist-info → sdf_xarray-0.3.2.dist-info}/METADATA

@@ -1,42 +1,23 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: sdf-xarray
-Version: 0.2.1
+Version: 0.3.2
 Summary: Provides a backend for xarray to read SDF files as created by the EPOCH plasma PIC code.
-Author-Email: Peter Hill <peter.hill@york.ac.uk>, Joel Adams <joel.adams@york.ac.uk>, Shaun Doherty <shaun.doherty@york.ac.uk>
-License: Copyright 2024, Peter Hill, Joel Adams, epochpic team
-         
-         Redistribution and use in source and binary forms, with or without
-         modification, are permitted provided that the following conditions are
-         met:
-         
-         1. Redistributions of source code must retain the above copyright
-         notice, this list of conditions and the following disclaimer.
-         
-         2. Redistributions in binary form must reproduce the above copyright
-         notice, this list of conditions and the following disclaimer in the
-         documentation and/or other materials provided with the distribution.
-         
-         3. Neither the name of the copyright holder nor the names of its
-         contributors may be used to endorse or promote products derived from
-         this software without specific prior written permission.
-         
-         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-         “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-         LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-         A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-         HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-         SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-         LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-         DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-         THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-         (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-         
-Requires-Python: >=3.10
+Author-Email: Peter Hill <peter.hill@york.ac.uk>, Joel Adams <joel.adams@york.ac.uk>, Shaun Doherty <shaun.doherty@york.ac.uk>, Chris Herdman <chris.herdman@york.ac.uk>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.10
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: xarray>=2024.1.0
 Requires-Dist: dask>=2024.7.1
-Requires-Dist: cython>=3.0
 Provides-Extra: docs
 Requires-Dist: sphinx>=5.3; extra == "docs"
 Requires-Dist: sphinx_autodoc_typehints>=1.19; extra == "docs"
@@ -52,6 +33,7 @@ Requires-Dist: myst-parser; extra == "docs"
 Provides-Extra: test
 Requires-Dist: pytest>=3.3.0; extra == "test"
 Requires-Dist: dask[complete]; extra == "test"
+Requires-Dist: matplotlib; extra == "test"
 Provides-Extra: lint
 Requires-Dist: ruff; extra == "lint"
 Provides-Extra: build
@@ -66,14 +48,22 @@ Description-Content-Type: text/markdown
 
 # sdf-xarray
 
-![PyPI](https://img.shields.io/pypi/v/sdf-xarray?color=blue)
+![Dynamic TOML Badge](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fepochpic%2Fsdf-xarray%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&query=%24.project.requires-python&label=python&logo=python)
+[![Available on PyPI](https://img.shields.io/pypi/v/sdf-xarray?color=blue&logo=pypi)](https://pypi.org/project/sdf-xarray/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15351323.svg)](https://doi.org/10.5281/zenodo.15351323)
 ![Build/Publish](https://github.com/epochpic/sdf-xarray/actions/workflows/build_publish.yml/badge.svg)
 ![Tests](https://github.com/epochpic/sdf-xarray/actions/workflows/tests.yml/badge.svg)
+[![Read the Docs](https://img.shields.io/readthedocs/sdf-xarray?logo=readthedocs&link=https%3A%2F%2Fsdf-xarray.readthedocs.io%2F)](https://sdf-xarray.readthedocs.io)
+[![Formatted with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+
 
 sdf-xarray provides a backend for [xarray](https://xarray.dev) to read SDF files as created by
 [EPOCH](https://epochpic.github.io) using the [SDF-C](https://github.com/epochpic/SDF_C) library.
 Part of [BEAM](#broad-epoch-analysis-modules-beam) (Broad EPOCH Analysis Modules).
 
+> [!IMPORTANT]
+> To install this package make sure you are using one of the Python versions listed above.
+
 ## Installation
 
 Install from PyPI with:

{sdf_xarray-0.2.1.dist-info → sdf_xarray-0.3.2.dist-info}/RECORD

@@ -6,19 +6,20 @@ include/SDFC_14.4.7/sdf_list_type.h,sha256=Quu8v0-SEsQuJpGtEZnm09tAyXqWNitx0sXl5
 include/SDFC_14.4.7/sdf_vector_type.h,sha256=dbKjhzRRsvhzrnTwVjtVlvnuisEnRMKY-vvdm94ok_Q,1595
 include/SDFC_14.4.7/stack_allocator.h,sha256=L7U9vmGiVSw3VQLIv9EzTaVq7JbFxs9aNonKStTkUSg,1335
 include/SDFC_14.4.7/uthash.h,sha256=rIyy_-ylY6S_7WaZCCC3VtvXaC9q37rFyA0f1U9xc4w,63030
-lib/SDFC_14.4.7/sdfc.lib,sha256=FFlajqQZVDNaOzVyuWTv2XcFS7DHOiwDut_EhSSKyi0,350698
+lib/SDFC_14.4.7/sdfc.lib,sha256=bsw4ROxRHCvBtvwXUBfOyhycWZyUPTNrejvZ-qIHPKQ,350158
 lib/SDFC_14.4.7/SDFCConfig.cmake,sha256=IOA1eusC-KvUK4LNTEiOAmEdaPH1ZvNvbYPgiG1oZio,802
 lib/SDFC_14.4.7/SDFCConfigVersion.cmake,sha256=pN7Qqyf04s3izw7PYQ0XK6imvmhaVegSdR_nEl3Ok_o,2830
 lib/SDFC_14.4.7/SDFCTargets-release.cmake,sha256=G4zdx5PyjePigeD_a6rmZAxbk7L8Nf0klUnV78Lm2fI,828
 lib/SDFC_14.4.7/SDFCTargets.cmake,sha256=OVt1Gm8n7Ew4fiTmA9yHoef3vIIGwsXUZfqeG9p9Bys,4152
-sdf_xarray/__init__.py,sha256=BL9yrZKdmN9u8gUHFsfdlMbSPPtGkqkUKldKhs6XKXI,17407
-sdf_xarray/_version.py,sha256=cTPlZaUCc20I4ZWsDjY35UftpFNRgfDaDBgkWxfIQmg,532
+sdf_xarray/__init__.py,sha256=obgAD4Aecvvpd8GkxLIAiIagSaY0bFVP2Q397N48_5g,24201
+sdf_xarray/_version.py,sha256=bmLiJYnZTISDv_NDGANk6QDMSY0XTk0CwXXKhbOvW3Y,746
 sdf_xarray/csdf.pxd,sha256=ADPjAuHsodAvdOz96Z_XlFF7VL3KmVaXcTifWDP3rK0,4205
-sdf_xarray/plotting.py,sha256=pCKZ01sAT0VLEhnWrX6LN5OSJnzcIkRA3joN7f62giM,6238
-sdf_xarray/sdf_interface.cp313-win_amd64.pyd,sha256=KQqvS-YMfNROpaQs-kt9ivhmcio2V3oP1I9djAMxo1U,378368
-sdf_xarray/sdf_interface.pyx,sha256=3XRFlrC1e_HkJrU8-i3fMz8DlyUxZgt9wTx_QkGE_TQ,11982
-sdf_xarray-0.2.1.dist-info/METADATA,sha256=gfR0XGC6e0b1WFgTdVMf1nfL4AsICdVCDQCOsjZC2kY,7989
-sdf_xarray-0.2.1.dist-info/WHEEL,sha256=xwjTh-mFvAONxbW8av7jDNts8DLqzqCA-klxw1kaHPA,106
-sdf_xarray-0.2.1.dist-info/entry_points.txt,sha256=gP7BIQpXNg6vIf7S7p-Rw_EJZTC1X50BsVTkK7dA7g0,57
-sdf_xarray-0.2.1.dist-info/licenses/LICENCE,sha256=aHWuyELjtzIL1jTXFHTbI3tr9vyVyhnw3I9_QYPdEX8,1515
-sdf_xarray-0.2.1.dist-info/RECORD,,
+sdf_xarray/dataset_accessor.py,sha256=TvnVMBefnT1d94Bkllhd-__O3ittzpaVjZKfze-3WQ4,2484
+sdf_xarray/plotting.py,sha256=PnbEspR4XkA5SHkpoFKA2G7BYj5J3mVgR1TEeGol6Vw,7041
+sdf_xarray/sdf_interface.cp313-win_amd64.pyd,sha256=VLbOR703pDE3NdsnV-_8qQyLKelRmW2taohOVqeWG68,359936
+sdf_xarray/sdf_interface.pyx,sha256=PFC6upg14OZBqiGInLgBoxztIIKBk-HOh3WC9Ro4YUw,11975
+sdf_xarray-0.3.2.dist-info/METADATA,sha256=xvADFsOdsd5EzaZbVYGOUgmEMe4RzrTDF9IbyijadqE,7624
+sdf_xarray-0.3.2.dist-info/WHEEL,sha256=vkL3wTIkhjZa3RmEXX20hldNp6Q8qtwRjrXW6K5sw_Q,106
+sdf_xarray-0.3.2.dist-info/entry_points.txt,sha256=gP7BIQpXNg6vIf7S7p-Rw_EJZTC1X50BsVTkK7dA7g0,57
+sdf_xarray-0.3.2.dist-info/licenses/LICENCE,sha256=aHWuyELjtzIL1jTXFHTbI3tr9vyVyhnw3I9_QYPdEX8,1515
+sdf_xarray-0.3.2.dist-info/RECORD,,

{sdf_xarray-0.2.1.dist-info → sdf_xarray-0.3.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: scikit-build-core 0.11.1
+Generator: scikit-build-core 0.11.6
 Root-Is-Purelib: false
 Tag: cp313-cp313-win_amd64