sal-xarray 0.1.0__py3-none-any.whl

sal_xarray/main.py

@@ -0,0 +1,116 @@
+"""Xarray SAL backend entrypoint."""
+
+import os
+import re
+from typing import Any, Iterable
+
+import numpy as np
+import xarray as xr
+from sal.client import SALClient
+
+from xarray.backends import BackendEntrypoint
+from xarray.backends.common import ReadBuffer
+from xarray.backends.common import AbstractDataStore
+
+
+class SALBackendEntrypoint(BackendEntrypoint):
+    """Xarray SAL backend entrypoint."""
+
+    def open_dataset(
+        self,
+        filename_or_obj: str
+        | os.PathLike[Any]
+        | ReadBuffer
+        | bytes
+        | memoryview
+        | AbstractDataStore,
+        *,
+        drop_variables: str | Iterable[str] | None = None,
+        host: str = "https://sal.jetdata.eu",
+    ) -> xr.Dataset:
+        """Open a SAL dataset given a signal name and shot number.
+
+        Parameters
+        ----------
+        filename_or_obj : str
+            SAL dataset specified as sal://pulse/<shot_number>/<signal_name>
+        drop_variables : str or list of str, optional
+            Variables to drop from the dataset (not used).
+        """
+
+        if not isinstance(filename_or_obj, str):
+            raise ValueError("SAL backend only supports string filenames.")
+
+        if "sal://" not in filename_or_obj:
+            raise ValueError("SAL dataset must start with the sal:// scheme")
+
+        name = filename_or_obj.replace("sal://", "")
+        match = re.search(r"sal://pulse/(\d+)/", filename_or_obj)
+
+        if not match:
+            raise ValueError(
+                "Invalid SAL URL format. Expected sal://pulse/<shot_number>/<signal_name>"
+            )
+
+        shot = int(match.group(1))
+        name = "/" + name
+
+        client = SALClient(host=host)
+        try:
+            signal = client.get(name)
+        except Exception as e:
+            raise RuntimeError(f"Failed to retrieve SAL signal '{name}': {e}") from e
+
+        data = self.parse_data(signal)
+        data.attrs["shot_id"] = shot
+
+        status = xr.DataArray(signal.mask.status, dims=data.dims, coords=data.coords)
+        status.attrs["description"] = signal.mask.description
+        status.attrs["flag_values"] = np.unique(signal.mask.status)
+        status.attrs["flag_meanings"] = signal.mask.key.tolist()
+
+        dataset = data.to_dataset(name="data")
+        dataset["status"] = status
+        return dataset
+
+    def parse_data(self, signal) -> xr.DataArray:
+        """Parse a SAL LeafReport into an xarray DataArray."""
+
+        dims = {}
+        for index, item in enumerate(signal.dimensions):
+            name = f"dim_{index}"
+            if item.temporal:
+                name = "time"
+            dim = xr.DataArray(item.data, dims=[name], name=name)
+            dim.attrs["description"] = item.description
+            dim.attrs["units"] = item.units
+
+            dims[dim.name] = dim
+
+        data = xr.DataArray(
+            signal.data,
+            dims=[d.name for d in dims.values()],
+            coords={d.name: d for d in dims.values()},
+        )
+
+        data.attrs["description"] = signal.description
+        data.attrs["units"] = signal.units
+        data.attrs["sal_name"] = name
+
+        return data
+
+    def open_datatree(self, filename_or_obj, *, drop_variables=None):
+        self.open_dataset(filename_or_obj, drop_variables=drop_variables)
+
+    def open_groups_as_dict(self, filename_or_obj, **kwargs):
+        """Open groups as a dictionary (not supported for SAL backend)."""
+        raise NotImplementedError("SAL backend does not support opening groups")
+
+    open_dataset_parameters = ["filename_or_obj", "drop_variables"]
+
+    def guess_can_open(self, filename_or_obj):
+        return filename_or_obj.startswith("sal://")
+
+    description = "Use SAL data in Xarray"
+
+    url = "https://github.com/samueljackson92/sal-xarray"

sal_xarray-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: sal-xarray
+Version: 0.1.0
+Summary: SAL backend for xarray
+Author-email: Samuel Jackson <samuel.jackson@ukaea.uk>
+Maintainer-email: Samuel Jackson <samuel.jackson@ukaea.uk>
+Project-URL: repository, https://github.com/samueljackson92/sal-xarray
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2
+Requires-Dist: sal>=1.2.5
+Requires-Dist: xarray>=2025.12.0
+Dynamic: license-file
+
+# sal-xarray
+
+An xarray backend for SAL (Simple Access Layer) that enables seamless integration of SAL data sources with the xarray ecosystem.
+
+## Overview
+
+sal-xarray provides a backend plugin for xarray that allows you to access SAL data sources using xarray's familiar API. It automatically handles the conversion of SAL signals to xarray DataArrays and Datasets, making it easy to work with SAL data in scientific Python workflows.
+## Features
+
+- **xarray Integration**: Access SAL data using xarray's `open_dataset` function
+- **Automatic Conversion**: Converts SAL signals to xarray DataArrays with proper coordinates and metadata
+- **Status Mask Handling**: Includes status mask data alongside signal data
+- **URI-based Access**: Simple URI scheme (`sal://pulse/<shot_number>/<signal_name>`) for accessing data
+
+## Installation 
+
+```bash
+pip install sal-xarray
+```
+
+Or using `uv`:
+
+```bash
+uv pip install sal-xarray
+```
+
+## Usage
+
+Open a SAL dataset using xarray:
+
+```python
+import xarray as xr
+
+# Open a SAL signal by name and shot number
+ds = xr.open_dataset("sal://pulse/87737/ppf/signal/jetppf/magn/ipla", engine="sal")
+
+# Access the data
+data = ds["data"]
+status = ds["status"]
+
+# The dataset includes time coordinates
+time = ds["time"]
+
+# Access metadata
+units = ds["data"].attrs["units"]
+signal_name = ds["data"].attrs["sal_name"]
+```
+
+The URI format is: `sal://pulse/<shot_number>/<signal_name>`
+
+## Data Structure
+
+When you open a SAL dataset, sal-xarray creates an xarray Dataset with:
+- **data**: The signal data as a DataArray
+- **status**: The status data as a DataArray
+- **time**: Time coordinates (dimension)
+- **attrs**: Metadata including units and SAL signal name
+
+## Development
+
+### Setup
+
+Clone the repository and install development dependencies:
+
+```bash
+git clone https://github.com/samueljackson92/sal-xarray.git
+cd sal-xarray
+uv sync
+```
+
+### Running Tests
+
+```bash
+uv run pytest tests/
+```
+
+### Code Quality
+
+The project uses ruff for linting and formatting, and pylint for additional checks:
+
+```bash
+# Run ruff
+uv run ruff check sal_xarray tests
+uv run ruff format sal_xarray tests
+
+# Run pylint
+uv run pylint sal_xarray
+
+# Run ty
+uv run ty check sal_xarray
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. Tests pass for any new functionality
+2. Code follows the project's style guidelines (ruff and pylint)
+3. Documentation is updated as needed
+
+## License
+
+MIT License

sal_xarray-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sal_xarray/main.py,sha256=dQNLmfYTj6Buy-Jkv_nx_Hejv7wa2-DpvXDOOK-iqlA,3764
+sal_xarray-0.1.0.dist-info/licenses/LICENSE,sha256=N_v8bcUerdJcYVvboaEnKJxOrcnAddHaM3na6KFy0B0,1071
+sal_xarray-0.1.0.dist-info/METADATA,sha256=ZCG7NqT0ATsCGVDuLcgX-HDeo2_JddLx2HMkYCfCcJA,3140
+sal_xarray-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sal_xarray-0.1.0.dist-info/entry_points.txt,sha256=CwN-BKTBiu1MTuXPfRGTNf3XjLVr5AG32nMqFInaVpw,61
+sal_xarray-0.1.0.dist-info/top_level.txt,sha256=USvgVet1x_Qj3I8NUxJ95ZzGK2at3Mq98KT948Ltr7k,11
+sal_xarray-0.1.0.dist-info/RECORD,,

sal_xarray-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sal_xarray-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xarray.backends]
+sal = sal_xarray.main:SALBackendEntrypoint

sal_xarray-0.1.0.dist-info/licenses/LICENSE

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

sal_xarray-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sal_xarray