sofar 1.1.4__py2.py3-none-any.whl → 1.2.0__py2.py3-none-any.whl

sofar/sofastream.py

@@ -0,0 +1,296 @@
+from netCDF4 import Dataset
+import numpy as np
+
+
+class SofaStream():
+    """
+    Read desired data from SOFA-file directly from disk without loading entire
+    file into memory.
+
+    :class:`SofaStream` opens a SOFA-file and retrieves only the requested
+    data.
+
+    If you want to use all the data from a SOFA-file use :class:`Sofa`
+    class and :func:`read_sofa` function instead.
+
+    Parameters
+    ----------
+    filename : str
+        Full path to a SOFA-file
+
+    Returns
+    --------
+    sofa_stream : SofaStream
+        A SofaStream object which reads directly from the file.
+
+    Examples
+    --------
+    Get an attribute from a SOFA-file:
+
+        >>> import sofar as sf
+        >>> filename = "path/to/file.sofa"
+        >>> with sf.SofaStream(filename) as file:
+        >>>     data = file.GLOBAL_RoomType
+        >>>     print(data)
+        free field
+
+    Get a variable from a SOFA-file:
+
+        >>> with SofaStream(filename) as file:
+        >>>     data = file.Data_IR
+        >>>     print(data)
+        <class 'netCDF4._netCDF4.Variable'>
+        float64 Data.IR(M, R, N)
+        unlimited dimensions:
+        current shape = (11950, 2, 256)
+        filling on, default _FillValue of 9.969209968386869e+36 used
+
+    What is returned is a `netCDF-variable`. To access the values (in this
+    example the IRs) the variable needs to be sliced:
+
+        >>> with SofaStream(filename) as file:
+        >>>     data = file.Data_IR
+        >>>     # get all values
+        >>>     all_irs = data[:]
+        >>>     print(all_irs.shape)
+        (11950, 2, 256)
+        >>>     # get data from first channel
+        >>>     specific_irs = data[:,0,:]
+        >>>     print(specific_irs.shape)
+        (11950, 256)
+    """
+
+    def __init__(self, filename):
+        """Initialize a new SofaStream object (see documentation above)"""
+        self._filename = filename
+
+    def __enter__(self):
+        """
+        Executed when entering a ``with`` statement
+        (see documentation above).
+        """
+        self._file = Dataset(self._filename, mode="r")
+        return self
+
+    def __exit__(self, *args):
+        """
+        Executed when exiting a ``with`` statement
+        (see documentation above).
+        """
+        self._file.close()
+
+    def __getattr__(self, name):
+        """
+        Executed when accessing data within a with statement
+        (see documentation above)."""
+        # get netCDF4-attributes and -variable-keys from SOFA-file
+        dset_variables = np.array([key for key in self._file.variables.keys()])
+        dset_attributes = np.asarray(self._file.ncattrs())
+
+        # remove delimiter from passed sofar-attribute
+        name_netcdf = name.replace(
+            'GLOBAL_', '').replace('Data_', 'Data.')
+
+        # Handle variable-attributes (e.g. '_Units' and '_Type')
+        var_attr = None
+        if "_" in name_netcdf:
+            name_netcdf, var_attr = name_netcdf.split('_')
+
+        # get value if passed attribute points to a netCDF4-variable
+        if name_netcdf in dset_variables:
+            # get variable from SOFA-file
+            self._data = self._file.variables[name_netcdf]
+            if var_attr is not None:
+                self._data = getattr(self._data, var_attr)
+
+        # get value if passed attribute points to a netCDF4-attribute
+        elif name_netcdf in dset_attributes:
+            # get attribute value from SOFA-file
+            self._data = self._file.getncattr(name_netcdf)
+
+        else:
+            raise AttributeError(f"{name} is not contained in SOFA-file")
+
+        return self._data
+
+    @property
+    def list_dimensions(self):
+        """
+        Print the dimensions of the SOFA-file
+
+        See :py:func:`~SofaStream.inspect` to see the shapes of the data inside
+        the SOFA-file and :py:func:`~SofaStream.get_dimension` to get the
+        size/value of a specific dimensions as integer number.
+
+        The SOFA standard defines the following dimensions that are used
+        to define the shape of the data entries:
+
+        M
+            number of measurements
+        N
+            number of samples, frequencies, SOS coefficients
+            (depending on GLOBAL_DataType)
+        R
+            Number of receivers or SH coefficients
+            (depending on ReceiverPosition_Type)
+        E
+            Number of emitters or SH coefficients
+            (depending on EmitterPosition_Type)
+        S
+            Maximum length of a string in a string array
+        C
+            Size of the coordinate dimension. This is always three.
+        I
+            Single dimension. This is always one.
+
+        """
+        dim = self._file.dimensions
+
+        # get verbose description for dimesion N
+        if self._file.getncattr('DataType').startswith("FIR"):
+            N_verbose = "samples"
+        elif self._file.getncattr('DataType').startswith("TF"):
+            N_verbose = "frequencies"
+        elif self._file.getncattr('DataType').startswith("SOS"):
+            N_verbose = "SOS coefficients"
+
+        # get verbose description for dimensions R and E
+        R_verbose = (
+            "receiver spherical harmonics coefficients"
+            if 'harmonic'
+            in self._file.variables['ReceiverPosition'].getncattr('Type')
+            else "receiver"
+            )
+        E_verbose = (
+            "emitter spherical harmonics coefficients"
+            if 'harmonic'
+            in self._file.variables['EmitterPosition'].getncattr('Type')
+            else "emitter"
+            )
+
+        dimensions = {
+            "M": "measurements",
+            "N": N_verbose,
+            "R": R_verbose,
+            "E": E_verbose,
+            "S": "maximum string length",
+            "C": "coordinate dimensions, fixed",
+            "I": "single dimension, fixed"}
+
+        info_str = ""
+        for key, value in dim.items():
+            value = value.size
+            dim_info = dimensions[key] if key in dimensions \
+                else "custom dimension"
+
+            info_str += f"{key} = {value} {dim_info}" + '\n'
+
+        print(info_str)
+
+    def get_dimension(self, dimension):
+        """
+        Get size of a SOFA dimension
+
+        SOFA dimensions specify the shape of the data contained in a SOFA-file.
+        For a list of all dimensions see :py:func:`~list_dimensions`, for more
+        information about the data contained in a SOFA-file use
+        :py:func:`~inspect`.
+
+        Parameters
+        ----------
+        dimension : str
+            The dimension as a string, e.g., ``'N'``.
+
+        Returns
+        -------
+        size : int
+            the size of the queried dimension.
+        """
+
+        # get dimensons from SOFA-file
+        dims = self._file.dimensions
+
+        if dimension not in dims.keys():
+            raise ValueError((
+                f"{dimension} is not a valid dimension. "
+                "See Sofa.list_dimensions for a list of valid dimensions."))
+
+        return dims[dimension].size
+
+    def inspect(self, file=None):
+        """
+        Get information about the data inside a SOFA-file
+
+        Prints the values of all attributes and variables with six or less
+        entries and the shapes and type of all numeric and string variables.
+        When printing the values of arrays, single dimensions are discarded for
+        easy of display, i.e., an array of shape (1, 3, 2) will be displayed as
+        an array of shape (3, 2).
+
+        Parameters
+        ----------
+        file : str
+            Full path of a file under which the information is to be stored in
+            plain text. The default ``None`` only print the information to the
+            console.
+        """
+
+        # Header of inspect-print
+        info_str = (
+            f"{self._file.getncattr('SOFAConventions')} "
+            f"{self._file.getncattr('SOFAConventionsVersion')} "
+            f"(SOFA version {self._file.getncattr('Version')})\n")
+        info_str += "-" * len(info_str) + "\n"
+
+        # information for attributes
+        for attr in self._file.ncattrs():
+
+            value = self._file.getncattr(attr)
+            sofar_attr = f"GLOBAL_{attr}"
+            info_str += sofar_attr + ' : ' + str(value) + '\n'
+
+        # information for variables
+        for key in self._file.variables.keys():
+            # get values, shape and dimensions
+            data = self._file[key]
+            shape = data.shape
+            dimensions = data.dimensions
+
+            # add variable name to info-string
+            info_str += key.replace('.', '_') + ' : '
+
+            # pad shape if required (trailing single dimensions are
+            # discarded following the numpy default)
+            while len(shape) < len(dimensions):
+                shape += (1, )
+
+            # add value for scalars
+            if data.size == 1:
+                info_str += str(data[:][0]) + '\n'
+
+            # Handle multidimensional data
+            else:
+                # make verbose shape, e.g., '(M=100, R=2, N=128, '
+                shape_verbose = "("
+                for s, d in zip(shape, dimensions):
+                    shape_verbose += f"{d}={s}, "
+
+                # add shape information
+                info_str += shape_verbose[:-2] + ")\n"
+                # add value information if not too much
+                if data.size < 7:
+                    info_str += "  " + \
+                        str(np.squeeze(data[:])).replace("\n", "\n  ") + "\n"
+
+            # Add variable-attributes to info string (e.g. 'Type' or 'Units)
+            for att_ in [a for a in self._file[key].ncattrs()]:
+                info_str += (key.replace('.', '_') + f'_{att_} : '
+                             + getattr(data, att_) + '\n')
+
+        # write to text file
+        if file is not None:
+            with open(file, 'w') as f_id:
+                f_id.write(info_str + "\n")
+
+        # print to console
+        print(info_str)

sofar/update_conventions.py

@@ -1,10 +1,12 @@
 import contextlib
 import os
+import shutil
 import re
 import glob
 import json
 import requests
 from bs4 import BeautifulSoup
+from tempfile import TemporaryDirectory
 
 
 def update_conventions(conventions_path=None, assume_yes=False):
@@ -20,9 +22,9 @@ def update_conventions(conventions_path=None, assume_yes=False):
         https://www.sofaconventions.org/conventions/ and
         https://www.sofaconventions.org/conventions/deprecated/.
     2.
-        Convert csv files to json files to be read by sofar.
+        Notify which conventions would be added or updated.
     3.
-        Notify which conventions were newly added or updated.
+        Convert csv files to json files to be read by sofar.
 
     The csv and json files are stored at sofar/conventions. Sofar works only on
     the json files. To get a list of all currently available SOFA conventions
@@ -41,28 +43,16 @@ def update_conventions(conventions_path=None, assume_yes=False):
         ``None``, which saves the conventions inside the sofar package.
         Conventions saved under a different path can not be used by sofar. This
         parameter was added mostly for testing and debugging.
-    response : bool, optional
+    assume_yes : bool, optional
 
-        ``True``
-            Updating the conventions must be confirmed by typing "y".
         ``False``
+            Updating the conventions must be confirmed by typing "y".
+        ``True``
             The conventions are updated without confirmation.
 
-        The default is ``True``
+        The default is ``False``
     """
 
-    if not assume_yes:
-        # these lines were only tested manually. I was too lazy to write a test
-        # coping with keyboard input
-        print(("Are you sure that you want to update the conventions? "
-               "Read the documentation before continuing. "
-               "If updateing breaks sofar it has to be re-installed"
-               "(y/n)"))
-        response = input()
-        if response != "y":
-            print("Updating the conventions was canceled.")
-            return
-
     # url for parsing and downloading the convention files
     urls = ("https://www.sofaconventions.org/conventions/",
             "https://www.sofaconventions.org/conventions/deprecated/")
@@ -93,80 +83,113 @@ def update_conventions(conventions_path=None, assume_yes=False):
     if not os.path.isdir(os.path.join(conventions_path, "deprecated")):
         os.mkdir(os.path.join(conventions_path, "deprecated"))
 
-    # Loop and download conventions if they changed
+    # Loop and download conventions to temporary directory if they changed
     updated = False
-    for convention in conventions:
 
-        # exclude these conventions
-        if convention.startswith(("General_", "GeneralString_")):
-            continue
-
-        # get filename and url
-        is_standardized = convention in standardized
-        standardized_csv = os.path.join(conventions_path, convention)
-        deprecated_csv = os.path.join(
-                conventions_path, "deprecated", convention)
-        url = (
-            f"{urls[0]}/{convention}"
-            if is_standardized
-            else f"{urls[1]}/{convention}"
-        )
+    update = []
+    deprecate = []
 
-        # download SOFA convention definitions to package directory
-        data = requests.get(url)
-        # remove windows style line breaks and trailing tabs
-        data = data.content.replace(b"\r\n", b"\n").replace(b"\t\n", b"\n")
-
-        # check if convention needs to be added or updated
-        if is_standardized and not os.path.isfile(standardized_csv):
-            # add new standardized convention
-            updated = True
-            with open(standardized_csv, "wb") as file:
-                file.write(data)
-            print(f"- added convention: {convention[:-4]}")
-        if is_standardized and os.path.isfile(standardized_csv):
-            # check for update of a standardized convention
-            with open(standardized_csv, "rb") as file:
-                data_current = b"".join(file.readlines())
-                data_current = data_current.replace(
-                    b"\r\n", b"\n").replace(b"\t\n", b"\n")
-            if data_current != data:
+    with TemporaryDirectory() as temp:
+        os.mkdir(os.path.join(temp, 'deprecated'))
+        for convention in conventions:
+
+            # exclude these conventions
+            if convention.startswith(("General_", "GeneralString_")):
+                continue
+
+            # get filename and url
+            is_standardized = convention in standardized
+            standardized_csv = os.path.join(conventions_path, convention)
+            deprecated_csv = os.path.join(
+                    conventions_path, "deprecated", convention)
+            url = (
+                f"{urls[0]}/{convention}"
+                if is_standardized
+                else f"{urls[1]}/{convention}"
+            )
+
+            # download SOFA convention definitions to package directory
+            data = requests.get(url)
+            # remove windows style line breaks and trailing tabs
+            data = data.content.replace(b"\r\n", b"\n").replace(b"\t\n", b"\n")
+
+            # check if convention needs to be added or updated
+            if is_standardized and not os.path.isfile(standardized_csv):
+                # add new standardized convention
+                updated = True
+                with open(os.path.join(temp, convention), "wb") as file:
+                    file.write(data)
+                print(f"- add convention: {convention[:-4]}")
+                update.append(convention)
+            if is_standardized and os.path.isfile(standardized_csv):
+                # check for update of a standardized convention
+                with open(standardized_csv, "rb") as file:
+                    data_current = b"".join(file.readlines())
+                    data_current = data_current.replace(
+                        b"\r\n", b"\n").replace(b"\t\n", b"\n")
+                if data_current != data:
+                    updated = True
+                    with open(os.path.join(temp, convention), "wb") as file:
+                        file.write(data)
+                    print(f"- update convention: {convention[:-4]}")
+                    update.append(convention)
+            elif not is_standardized and os.path.isfile(standardized_csv):
+                # deprecate standardized convention
                 updated = True
-                with open(standardized_csv, "wb") as file:
+                with open(os.path.join(temp, 'deprecated', convention), "wb") \
+                        as file:
                     file.write(data)
-                print(f"- updated convention: {convention[:-4]}")
-        elif not is_standardized and os.path.isfile(standardized_csv):
-            # deprecate standardized convention
-            updated = True
-            with open(deprecated_csv, "wb") as file:
-                file.write(data)
-            os.remove(standardized_csv)
-            os.remove(f"{standardized_csv[:-3]}json")
-            print(f"- deprecated convention: {convention[:-4]}")
-        elif not is_standardized and os.path.isfile(deprecated_csv):
-            # check for update of a deprecated convention
-            with open(deprecated_csv, "rb") as file:
-                data_current = b"".join(file.readlines())
-                data_current = data_current.replace(
-                    b"\r\n", b"\n").replace(b"\t\n", b"\n")
-            if data_current != data:
+                print(f"- deprecate convention: {convention[:-4]}")
+                deprecate.append(convention)
+            elif not is_standardized and os.path.isfile(deprecated_csv):
+                # check for update of a deprecated convention
+                with open(deprecated_csv, "rb") as file:
+                    data_current = b"".join(file.readlines())
+                    data_current = data_current.replace(
+                        b"\r\n", b"\n").replace(b"\t\n", b"\n")
+                if data_current != data:
+                    updated = True
+                    with open(os.path.join(temp, 'deprecated', convention),
+                              "wb") as file:
+                        file.write(data)
+                    print(f"- update deprecated convention: {convention[:-4]}")
+                    update.append(os.path.join('deprecated', convention))
+            elif not is_standardized and not os.path.isfile(deprecated_csv):
+                # add new deprecation
                 updated = True
-                with open(deprecated_csv, "wb") as file:
+                with open(os.path.join(temp, 'deprecated', convention), "wb") \
+                        as file:
                     file.write(data)
-                print(f"- updated deprecated convention: {convention[:-4]}")
-        elif not is_standardized and not os.path.isfile(deprecated_csv):
-            # add new deprecation
-            updated = True
-            with open(deprecated_csv, "wb") as file:
-                file.write(data)
-            print(f"- added deprecated convention: {convention[:-4]}")
-
-    if updated:
-        # compile json files from csv file
-        _compile_conventions(conventions_path)
-        print("... done.")
-    else:
-        print("... conventions already up to date.")
+                print(f"- add deprecated convention: {convention[:-4]}")
+                update.append(os.path.join('deprecated', convention))
+
+        if updated and not assume_yes:
+            # these lines were only tested manually. I was too lazy to write a
+            # test coping with keyboard input
+            print(("\nDo you want to update the conventions above? (y/n)\n"
+                   "Read the documentation before continuing. "
+                   "If updating breaks sofar it has to be re-installed"))
+            response = input()
+            if response != "y":
+                print("\nUpdating the conventions was canceled.")
+                return
+
+        if updated:
+            for convention in update:
+                shutil.copy(os.path.join(temp, convention),
+                            os.path.join(conventions_path, convention))
+            for convention in deprecate:
+                os.remove(os.path.join(conventions_path, convention))
+                os.remove(
+                    os.path.join(conventions_path, f"{convention[:-3]}json"))
+                shutil.copy(
+                    os.path.join(temp, 'deprecated', convention),
+                    os.path.join(conventions_path, 'deprecated', convention))
+            # compile json files from csv file
+            _compile_conventions(conventions_path)
+            print("... done.")
+        else:
+            print("... conventions already up to date.")
 
 
 def _compile_conventions(conventions_path=None):

sofar/utils.py

@@ -143,7 +143,7 @@ def equals(sofa_a, sofa_b, verbose=True, exclude=None):
         ``'GLOBAL'``
             Exclude all global attributes, i.e., fields starting with 'GLOBAL:'
         ``'DATE'``
-            Exclude date attributs, i.e., fields that contain 'Date'
+            Exclude date attributes, i.e., fields that contain 'Date'
         ``'ATTR'``
             Exclude all attributes, i.e., fields that contain ':'
 

{sofar-1.1.4.dist-info → sofar-1.2.0.dist-info}/LICENSE

@@ -1,4 +1,6 @@
-Copyright (c) [2021] [The pyfar developers]
+MIT License
+
+Copyright (c) 2021, The pyfar developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -17,3 +19,4 @@ 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.
+

sofar-1.2.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.1
+Name: sofar
+Version: 1.2.0
+Summary: Maybe the most complete python package for SOFA files so far
+Home-page: https://pyfar.org/
+Download-URL: https://pypi.org/project/sofar/
+Author: The pyfar developers
+Author-email: info@pyfar.org
+License: MIT license
+Project-URL: Bug Tracker, https://github.com/pyfar/sofar/issues
+Project-URL: Documentation, https://sofar.readthedocs.io/
+Project-URL: Source Code, https://github.com/pyfar/sofar
+Keywords: sofar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: netCDF4
+Requires-Dist: numpy>=1.14.0
+Requires-Dist: beautifulsoup4
+Requires-Dist: requests
+Requires-Dist: packaging
+
+<h1 align="center">
+<img src="https://github.com/pyfar/gallery/raw/main/docs/resources/logos/pyfar_logos_fixed_size_sofar.png" width="300">
+</h1><br>
+
+[![PyPI version](https://badge.fury.io/py/sofar.svg)](https://badge.fury.io/py/sofar)
+[![Documentation Status](https://readthedocs.org/projects/sofar/badge/?version=latest)](https://sofar.readthedocs.io/en/latest/?badge=latest)
+[![CircleCI](https://circleci.com/gh/pyfar/sofar.svg?style=shield)](https://circleci.com/gh/pyfar/sofar)
+
+Sofar is maybe the most complete Python package for the SOFA file format so
+far. SOFA files store spatially distributed acoustic data such as impulse
+responses or transfer functions. They are defined by the AES69-2022 standard
+(see references). These are the key features of sofar
+
+- Read, edit, and write SOFA files
+- Add custom attributes to SOFA files
+- Full Verification of the content of a SOFA files against AES69-2022
+- Upgrade data that uses outdated SOFA conventions
+- Open license allows unrestricted use
+- sofar is tested using continuous integration on
+- Uses a complete definition of the AES69-2022 standard (see references) maintained at [sofa_conventions](https://github.com/pyfar/sofa_conventions)
+
+Getting Started
+===============
+
+The [sofar and SOFA notebook](https://pyfar-gallery.readthedocs.io/en/latest/gallery/interactive/sofar_introduction.html)
+gives an overview of the most important sofar functionality and is a good starting point. For processing and visualizing data
+inside SOFA files, we recommend the [pyfar package](https://pyfar.readthedocs.io) that can read SOFA files through
+`pyfar.io.read_sofa` and the in-depth examples contained in the
+[pyfar example gallery](https://pyfar-gallery.readthedocs.io/en/latest/examples_gallery.html). Check out
+[read the docs](https://sofar.readthedocs.io) for a complete documentation of sofar. A more detailed introduction to the SOFA
+file format is given by Majdak et. al. 2022 (see references below). All information is also bundled at [pyfar.org](https://pyfar.org).
+
+Installation
+============
+
+Use pip to install sofar
+
+    pip install sofar
+
+
+(Requires Python >= 3.8)
+
+If the installation fails, please check out the [help section](https://pyfar-gallery.readthedocs.io/en/latest/help).
+
+Contributing
+============
+
+Refer to the [contribution guidelines](https://sofar.readthedocs.io/en/stable/contributing.html) for more information.
+
+References
+==========
+
+AES69-2022: *AES standard for file exchange - Spatial acoustic data file
+format*, Audio Engineering Society, Inc., New York, NY, USA.
+(https://www.aes.org/publications/standards/search.cfm?docID=99)
+
+P. Majdak, F. Zotter, F. Brinkmann, J. De Muynke, M. Mihocic, and M.
+Noisternig, "Spatially Oriented Format for Acoustics 2.1: Introduction and
+Recent Advances", *J. Audio Eng. Soc.*, vol. 70, no. 7/8, pp. 565-584,
+Jul. 2022. DOI: https://doi.org/10.17743/jaes.2022.0026