backscattermeter_analyzer 2.0.0__tar.gz → 2.1.1__tar.gz

{backscattermeter_analyzer-2.0.0 → backscattermeter_analyzer-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: backscattermeter_analyzer
-Version: 2.0.0
+Version: 2.1.1
 Summary: Tool to work on the backscattermeter at LAPP
 Project-URL: Documentation, https://git.linarphy.net/linarphy/backscattermeter_analyzer/wiki
 Project-URL: Homepage, https://git.linarphy.net/linarphy/backscattermeter_analyzer

{backscattermeter_analyzer-2.0.0 → backscattermeter_analyzer-2.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "backscattermeter_analyzer"
-version = "2.0.0"
+version = "2.1.1"
 description = "Tool to work on the backscattermeter at LAPP"
 authors = [{ name = "linarphy", email = "linarphy@linarphy.net" }]
 readme = "README.md"

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/__init__.py

@@ -0,0 +1,25 @@
+"""Entry-point package."""
+
+from .axis import Axis  # noqa: I001
+from .direction import Direction
+
+from .hardware import Backscattermeter, Camera, MotorJump, MotorPath
+from .io import register_measurement_hdf5
+
+from .characterize import DistanceRatio, DistanceResult
+from .utils import Distance, Measurement
+
+register_measurement_hdf5()
+
+__all__ = [
+    "Axis",
+    "Backscattermeter",
+    "Camera",
+    "Direction",
+    "Distance",
+    "DistanceRatio",
+    "DistanceResult",
+    "Measurement",
+    "MotorJump",
+    "MotorPath",
+]

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/characterize/__init__.py

@@ -0,0 +1,9 @@
+"""Sub-package focused on setup chacterization."""
+
+from .distance import Ratio as DistanceRatio
+from .distance import Result as DistanceResult
+
+__all__ = [
+    "DistanceRatio",
+    "DistanceResult",
+]

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/__init__.py

@@ -0,0 +1,15 @@
+"""I/O package."""
+
+from .hdf5 import register_measurement_hdf5
+from .registry import (
+    UnifiedIORegistry,
+    UnifiedReadWrite,
+    UnifiedReadWriteMethod,
+)
+
+__all__ = [
+    "UnifiedIORegistry",
+    "UnifiedReadWrite",
+    "UnifiedReadWriteMethod",
+    "register_measurement_hdf5",
+]

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/hdf5/__init__.py

@@ -0,0 +1,7 @@
+"""Sub-package for writing and parsing hdf5 files."""
+
+from .measurement import (
+    register_measurement as register_measurement_hdf5,
+)
+
+__all__ = ["register_measurement_hdf5"]

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/hdf5/measurement.py

@@ -0,0 +1,156 @@
+"""Hdf5 conversion for Measurement."""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from h5py import File, Group
+
+from backscattermeter_analyzer.hardware import Backscattermeter
+from backscattermeter_analyzer.io.registry.default import (
+    default_registry,
+)
+
+from .utils import (
+    group_to_timeseriesdict,
+    is_hdf5,
+    timeseriesdict_to_group,
+)
+
+if TYPE_CHECKING:
+    from backscattermeter_analyzer.utils.measurement.measurement import (  # noqa:E501,TC004
+        Measurement,
+    )
+
+
+def read(input_: Path | Group, path: str | None = None) -> Measurement:
+    """
+    Read a Measurement object from an HDF5 component/file.
+
+    Parameters
+    ----------
+    input_: Path | Group
+        If a string or a Path, the filename to read the table from.
+        If an h5py object, either the file or the group object to read
+        the Measurement from.
+    path: str | None
+        The path from which to read the table inside the HDF5 file.
+        This should be relative to the input if the input is a Group.
+
+    """
+    from backscattermeter_analyzer.utils.measurement.measurement import (  # noqa: PLC0415,E501
+        Measurement,
+    )
+
+    if isinstance(input_, Path):
+        input_ = File(input_)
+
+    # input_ is now a Group (a File is a Group)
+    if path is not None:
+        item = input_.get(path, default=None)
+        if item is None:
+            message = f"{path} is not a valid path in {input_}."
+            raise ValueError(message)
+        if not isinstance(item, Group):
+            message = (
+                f"{path} from {input_} is a {type(item)}, not a Group."
+            )
+            raise TypeError(message)
+    else:
+        item = input_
+
+    group_data = item.get("data", default=None)
+    if group_data is None:
+        message = f"No 'data' group in {path} from {input_}."
+        raise ValueError(message)
+    if not isinstance(group_data, Group):
+        message = f"'data' must be a group in {path} from {input_}."
+        raise TypeError(message)
+
+    measurement = Measurement(
+        data=group_to_timeseriesdict(group_data),
+        backscattermeter=Backscattermeter(),
+    )
+
+    if isinstance(input_, File):
+        input_.close()
+
+    return measurement
+
+
+def write(
+    measurement: Measurement,
+    output: Path | Group,
+    path: str | None = None,
+    *,
+    append: bool = False,
+    overwrite: bool = False,
+) -> None:
+    """
+    Write a Measurement object to an HDF5 file.
+
+    Parameters
+    ----------
+    measurement: Measurement
+        Measurement that is to be written to file.
+    output: Path | Group
+        If a Path, the path of the file to write the measurement to. If
+        a Group, the group object to write the measurement to, depending
+        on `path` value.
+    path: str | None
+        The path to which to write the table inside the HDF5 file.
+        This should be relative to the output Group (or the root Group
+        if output is a Path). Default to None.
+    append: bool
+        Whether to append the Measurement to an existing HDF5 file.
+        Default to False. This can delete a previous measurement.
+    overwrite: bool
+        Whether to overwrite any existing file without warning. Default
+        to False. If `append=True` and `overwrite=True`, then only the
+        group will be replaced.
+
+    """
+
+    if isinstance(output, Path):
+        if overwrite and not append:
+            output = File(output, mode="w")
+        elif append:
+            output = File(output, mode="r+")
+        else:
+            output = File(output, mode="x")
+
+    # output is now a Group (a File is a Group)
+    if path is not None:
+        item = output.get(path, default=None)
+        if item is None:
+            message = f"{path} is not a valid path in {output}."
+            raise ValueError(message)
+        if not isinstance(item, Group):
+            message = (
+                f"{path} from {output} is a {type(item)}, not a Group."
+            )
+            raise TypeError(message)
+    else:
+        item = output
+
+    element_number = len(item.keys())
+    if element_number != 0 and append:
+        item.clear()
+    elif element_number != 0 and not append:
+        message = f"{path} from {output} is not an empty group."
+        raise ValueError(message)
+
+    timeseriesdict_to_group(item, "data", measurement.data)
+
+    if isinstance(output, File):
+        output.close()
+
+
+def register_measurement() -> None:
+    """Register Measurement hdf5 conversion in Unified I/O."""
+    from backscattermeter_analyzer.utils.measurement.measurement import (  # noqa: PLC0415,E501
+        Measurement,
+    )
+
+    default_registry.register_identifier("hdf5", Measurement, is_hdf5)
+    default_registry.register_reader("hdf5", Measurement, read)
+    default_registry.register_writer("hdf5", Measurement, write)

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/hdf5/utils.py

@@ -0,0 +1,322 @@
+"""Utils."""
+
+from pathlib import Path
+from typing import Any, IO, Literal
+
+from astropy.io.misc.hdf5 import HDF5_SIGNATURE
+from astropy.units import Quantity
+from gwpy.detector.channel import Channel
+from gwpy.frequencyseries import FrequencySeries
+from gwpy.timeseries import TimeSeries, TimeSeriesDict
+from h5py import Dataset, Group
+from numpy import array, geomspace
+
+from backscattermeter_analyzer.io.registry.default import (
+    default_registry,
+)
+from backscattermeter_analyzer.scale import Scale
+
+
+def dataset_to_frequencyseries(dataset: Dataset) -> FrequencySeries:
+    """
+    Convert a hdf5 dataset to a FrequencySeries.
+
+    Parameters
+    ----------
+    dataset: Dataset
+        Dataset to convert.
+
+    Returns
+    -------
+    FrequencySeries
+        FrequencySeries.
+
+    """
+    unit = None
+    scale = Scale.LINEAR
+    if "units" in dataset.attrs:
+        unit = dataset.attrs["units"]
+
+    if "scale" in dataset.attrs:
+        scale = Scale(dataset.attrs["scale"])
+
+    if scale is Scale.LINEAR:
+        if "f0" not in dataset.attrs:
+            message = f"f0 not defined in dataset {dataset.name}"
+            raise ValueError(message)
+        if "df" not in dataset.attrs:
+            message = f"df not defined in dataset {dataset.name}"
+            raise ValueError(message)
+
+        f0 = Quantity(dataset.attrs["f0"])
+        df = Quantity(dataset.attrs["df"])
+
+        return FrequencySeries(
+            data=array(dataset),
+            unit=unit,
+            f0=f0,
+            df=df,
+        )
+
+    if "start" not in dataset.attrs:
+        message = f"start not defined in dataset {dataset.name}"
+        raise ValueError(message)
+    if "stop" not in dataset.attrs:
+        message = f"stop not defined in dataset {dataset.name}"
+        raise ValueError(message)
+    if "num" not in dataset.attrs:
+        message = f"num not defined in dataset {dataset.name}"
+        raise ValueError(message)
+
+    start = Quantity(dataset.attrs["start"])
+    stop = Quantity(dataset.attrs["stop"])
+    num = int(dataset.attrs["num"])
+
+    return FrequencySeries(
+        data=array(dataset),
+        unit=unit,
+        frequencies=geomspace(start=start, stop=stop, num=num),
+    )
+
+
+def dataset_to_timeseries(dataset: Dataset) -> TimeSeries:
+    """
+    Convert a hdf5 dataset to a TimeSeries.
+
+    Parameters
+    ----------
+    dataset: Dataset
+        Dataset to convert.
+
+    Returns
+    -------
+    TimeSeries
+        TimeSeries.
+
+    """
+    unit = None
+    scale = Scale.LINEAR
+    if "units" in dataset.attrs:
+        unit = dataset.attrs["units"]
+
+    if "scale" in dataset.attrs:
+        scale = Scale(dataset.attrs["scale"])
+
+    if scale is Scale.LINEAR:
+        if "t0" not in dataset.attrs:
+            message = f"t0 not defined in dataset {dataset.name}."
+            raise ValueError(message)
+
+        if "dt" not in dataset.attrs:
+            message = f"dt not defined in dataset {dataset.name}."
+            raise ValueError(message)
+
+        t0 = Quantity(dataset.attrs["t0"])
+        dt = Quantity(dataset.attrs["dt"])
+
+        return TimeSeries(
+            data=array(dataset),
+            unit=unit,
+            t0=t0,
+            dt=dt,
+        )
+
+    if "start" not in dataset.attrs:
+        message = f"start not defined in dataset {dataset.name}"
+        raise ValueError(message)
+    if "stop" not in dataset.attrs:
+        message = f"stop not defined in dataset {dataset.name}"
+        raise ValueError(message)
+    if "num" not in dataset.attrs:
+        message = f"num not defined in dataset {dataset.name}"
+        raise ValueError(message)
+
+    start = Quantity(dataset.attrs["start"])
+    stop = Quantity(dataset.attrs["stop"])
+    num = int(dataset.attrs["num"])
+
+    return TimeSeries(
+        data=array(dataset),
+        unit=unit,
+        times=Quantity(
+            geomspace(
+                start=start.to_value(unit="s"),
+                stop=stop.to_value(unit="s"),
+                num=num,
+            ),
+            "s",
+        ),
+    )
+
+
+def group_to_timeseriesdict(group: Group) -> TimeSeriesDict: # type: ignore[ty:invalid-type-form]
+    """
+    Convert a hdf5 group to a TimeSeriesDict.
+
+    Parameters
+    ----------
+    group: Group
+        Group to convert.
+
+    Returns
+    -------
+    TimeSeriesDict
+        TimeSeriesDict.
+
+    """
+    dict_data = {}
+    for name, dataset in group.items():
+        if not isinstance(dataset, Dataset):
+            continue
+
+        dict_data[name] = dataset_to_timeseries(dataset)
+
+    return TimeSeriesDict(dict_data)
+
+
+def frequencyseries_to_dataset(
+    store: Group, name: str, frequencyseries: FrequencySeries
+) -> Dataset:
+    """
+    Convert a FrequencySeries to an hdf5 dataset.
+
+    It adds the dataset to the `store`.
+
+    Parameters
+    ----------
+    store: Group
+        Hdf5 element which will store the dataset.
+    name: str
+        Name of the dataset.
+    frequencyseries: FrequencySeries
+        Data to store.
+
+    Returns
+    -------
+    Dataset
+        Created dataset.
+
+    """
+    dataset = store.create_dataset(name, data=frequencyseries.data)
+
+    if frequencyseries.unit is not None:
+        dataset.attrs["units"] = frequencyseries.unit.to_string()
+
+    try:
+        f0 = frequencyseries.f0
+        df = frequencyseries.df
+        dataset.attrs["scale"] = Scale.LINEAR
+        dataset.attrs["f0"] = f0.to_string()
+        dataset.attrs["df"] = df.to_string()
+    except AttributeError:
+        start = frequencyseries.f0
+        stop = frequencyseries.frequencies[-1]
+        num = len(frequencyseries.frequencies)
+        dataset.attrs["scale"] = Scale.LOG
+        dataset.attrs["start"] = start.to_string()
+        dataset.attrs["stop"] = stop.to_string()
+        dataset.attrs["num"] = num
+
+    return dataset
+
+
+def timeseries_to_dataset(
+    store: Group, name: str, timeseries: TimeSeries
+) -> Dataset:
+    """
+    Convert a TimeSeries to an hdf5 dataset.
+
+    It adds the dataset to the `store`.
+
+    Parameters
+    ----------
+    store: Group
+        Hdf5 element which will store the dataset.
+    name: str
+        Name of the dataset.
+    timeseries: TimeSeries
+        Data to store.
+
+    Returns
+    -------
+    Dataset
+        Created dataset.
+
+    """
+    dataset = store.create_dataset(name, data=timeseries.data)
+
+    if timeseries.unit is not None:
+        dataset.attrs["units"] = timeseries.unit.to_string()
+
+    try:
+        t0 = timeseries.t0
+        dt = timeseries.dt
+        dataset.attrs["scale"] = Scale.LINEAR.value
+        dataset.attrs["t0"] = t0.to_string()
+        dataset.attrs["dt"] = dt.to_string()
+    except AttributeError:
+        start = timeseries.t0
+        stop = timeseries.times[-1]
+        num = len(timeseries.times)
+        dataset.attrs["scale"] = Scale.LOG.value
+        dataset.attrs["start"] = start.to_string()
+        dataset.attrs["stop"] = stop.to_string()
+        dataset.attrs["num"] = num
+
+    return dataset
+
+
+def timeseriesdict_to_group(
+    store: Group, name: str, timeseriesdict: TimeSeriesDict # type: ignore[ty:invalid-type-form]
+) -> Group:
+    """
+    Convert a TimeSeriesDict to an hdf5 group.
+
+    It adds the group to the `store`.
+
+    Parameters
+    ----------
+    store: Group
+        Hdf5 element which will store the group.
+    name: str
+        Name of the group.
+    timeseriesdict: TimeSeriesDict
+        Data to store.
+
+    Returns
+    -------
+    Group
+        Created group.
+
+    """
+    group = store.create_group(name)
+
+    for key, timeseries in timeseriesdict.items():
+        channel = key
+        if isinstance(channel, Channel):
+            channel = str(key)
+        timeseries_to_dataset(group, channel, timeseries)
+
+    return group
+
+
+def is_hdf5(
+    origin: Literal["read", "write"],
+    path: Path | None,
+    fileobj: IO | None,
+    *args: Any,
+    **kwargs: Any,
+) -> bool:
+    """Check if data is hdf5."""
+
+    if fileobj is not None:
+        loc = fileobj.tell()
+        try:
+            signature = fileobj.read(8)
+        finally:
+            fileobj.seek(loc)
+        return signature == HDF5_SIGNATURE
+    if path is not None:
+        return path.suffix in ["hdf5", "h5"]
+
+    return isinstance(args[0], (Group, Dataset)) # File is a Group

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/registry/__init__.py

@@ -0,0 +1,16 @@
+"""Unified I/O Registry (see astropy)."""
+
+from .interface import UnifiedReadWrite, UnifiedReadWriteMethod
+from .unified_input_registry import UnifiedInputRegistry
+from .unified_io_registry import UnifiedIORegistry
+from .unified_io_registry_base import UnifiedIORegistryBase
+from .unified_output_registry import UnifiedOutputRegistry
+
+__all__ = [
+    "UnifiedIORegistry",
+    "UnifiedIORegistryBase",
+    "UnifiedInputRegistry",
+    "UnifiedOutputRegistry",
+    "UnifiedReadWrite",
+    "UnifiedReadWriteMethod",
+]

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/registry/default.py

@@ -0,0 +1,5 @@
+"""Contains and store default states."""
+
+from .unified_io_registry import UnifiedIORegistry
+
+default_registry = UnifiedIORegistry()

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/registry/interface/__init__.py

@@ -0,0 +1,9 @@
+"""Define interfaces for Unified I/O Registry."""
+
+from .unified_read_write import UnifiedReadWrite
+from .unified_read_write_method import UnifiedReadWriteMethod
+
+__all__ = [
+    "UnifiedReadWrite",
+    "UnifiedReadWriteMethod",
+]

backscattermeter_analyzer-2.1.1/src/backscattermeter_analyzer/io/registry/interface/unified_read_write.py

@@ -0,0 +1,108 @@
+"""UnifiedReadWrite class."""
+
+from dataclasses import dataclass, field
+from inspect import cleandoc
+from os import linesep
+from re import sub
+from sys import flags
+from typing import IO, Literal
+
+from rich.pager import Pager
+
+from backscattermeter_analyzer.io.registry.default import (
+    default_registry,
+)
+from backscattermeter_analyzer.io.registry.unified_io_registry import (
+    UnifiedIORegistry,
+)
+
+
+@dataclass
+class UnifiedReadWrite[T]:
+    """
+    Same goal than its astropy equivalent.
+
+    See astropy.io.registry.interface.UnifiedReadWrite
+    """
+
+    # Descriptor calling instance or None if no instance.
+    _instance: T | None
+    # Descriptor calling class (either owner class or instance class).
+    _class_: type[T]
+    # Method name (read or write).
+    _method_name: Literal["read", "write"]
+    # The IO Registry.
+    _registry: UnifiedIORegistry = field(init=False)
+
+    def __post_init__(self) -> None:
+        """Post-initialization process."""
+        self._registry = default_registry
+
+    def help(
+        self, format_: str | None = None, out: IO | None = None
+    ) -> None:
+        """
+        Output help documentation for the specified unified I/O format.
+
+        By default the help output is printed to the console via
+        pydoc.pager. Instead one can supplied a file handle object as
+        `out` and the output will be written to that handle.
+
+        Parameters
+        ----------
+        format_: str | None
+            Unified I/O format name, e.g. 'fits' or 'ascii.ecsv'
+        out: IO | None
+            Output destination. If None, stdout via a pager. Default to
+            None.
+
+        """
+        if flags.optimize >= 2:  # noqa:PLR2004
+            message = (
+                "The help method is not available under Python's"
+                " optimized mode."
+            )
+            raise RuntimeError(message)
+
+        class_ = self._class_
+        method_name = self._method_name
+
+        # Get reader or writer function associated with the registry
+        get_func = (
+            self._registry.get_reader
+            if method_name == "read"
+            else self._registry.get_writer
+        )
+        try:
+            if format_:
+                read_write_func = get_func(format_, class_)
+        except ValueError as err:
+            reader_doc = "ERROR: " + str(err)
+        else:
+            if format_:
+                # Format-specific
+                header = (
+                    f"{class_.__name__}.{method_name}(format_="
+                    f"'{format_}') documentation\n"
+                )
+                doc = read_write_func.__doc__
+            else:
+                # General docs
+                header = (
+                    f"{class_.__name__}.{method_name} general"
+                    " documentation\n"
+                )
+                doc = getattr(class_, method_name).__doc__
+
+            reader_doc = sub(".", "=", header)
+            reader_doc += header
+            reader_doc += sub(".", "=", header)
+            reader_doc += linesep
+            if doc is not None:
+                reader_doc += cleandoc(doc)
+
+        if out is None:
+            pager = Pager()
+            pager.show(reader_doc)
+        else:
+            out.write(reader_doc)