sofar 1.0.0__tar.gz → 1.1.1__tar.gz

{sofar-1.0.0 → sofar-1.1.1}/CONTRIBUTING.rst

@@ -178,9 +178,12 @@ before building the documentation.
 Submodules
 ~~~~~~~~~~
 
-To update the submodules containing the conventions and verification rules run
+To update the submodule containing the conventions and verification rules run
 
-$ git submodule update --remote sofar/sofa_conventions
+$ git submodule update --init --recursive
+$ git submodule update --recursive --remote
+
+and then commit the changes
 
 
 Deploying

{sofar-1.0.0 → sofar-1.1.1}/HISTORY.rst

@@ -1,6 +1,18 @@
 History
 =======
 
+1.1.1 (2023-7-7)
+----------------
+* Fix deploying to PyPi.org
+
+1.1.0 (2023-7-7)
+----------------
+* Deprecate FreeFieldDirectivityTV 1.0 in favor of FreeFieldDirectivityTV 1.1 (according to sofaconventoins.org and AES69-2022)
+* Add `sofar.read_sofa_as_netcdf` for reading SOFA files with erroneous data
+* Document SOFA conventions on https://sofar.readthedocs.io/en/stable/resources/conventions.html. `Sofa.info()` will this be deprecated in sofar v1.3.0
+* `sofar.read_sofa` and `sofar.write_sofa` now accept filenames and path objects
+* Add testing for Python 3.11
+
 1.0.0 (2022-12-16)
 ------------------
 * Use SOFA conventions of version 2.1 from https://github.com/pyfar/sofa_conventions

{sofar-1.0.0 → sofar-1.1.1}/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.1
 Name: sofar
-Version: 1.0.0
+Version: 1.1.1
 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
-Download-URL: https://pypi.org/project/sofar/
 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
-Platform: UNKNOWN
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -20,6 +19,7 @@ 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
 Requires-Python: >=3.8
 License-File: LICENSE
 License-File: AUTHORS.rst
@@ -81,7 +81,5 @@ format*, Audio Engineering Society, Inc., New York, NY, USA.
 
 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,
+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
-
-

{sofar-1.0.0 → sofar-1.1.1}/README.rst

@@ -55,5 +55,5 @@ format*, Audio Engineering Society, Inc., New York, NY, USA.
 
 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,
+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

{sofar-1.0.0 → sofar-1.1.1}/setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.0.0
+current_version = 1.1.1
 commit = True
 tag = True
 

{sofar-1.0.0 → sofar-1.1.1}/setup.py

@@ -44,7 +44,8 @@ setup(
         'Programming Language :: Python :: 3',
         'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',
-        'Programming Language :: Python :: 3.10'
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11'
     ],
     description="Maybe the most complete python package for SOFA files so far",
     install_requires=requirements,
@@ -64,7 +65,7 @@ setup(
         "Documentation": "https://sofar.readthedocs.io/",
         "Source Code": "https://github.com/pyfar/sofar",
     },
-    version='1.0.0',
+    version='1.1.1',
     zip_safe=False,
     python_requires='>=3.8'
 )

{sofar-1.0.0 → sofar-1.1.1}/sofar/__init__.py

@@ -4,11 +4,11 @@
 
 __author__ = """The pyfar developers"""
 __email__ = 'info@pyfar.org'
-__version__ = '1.0.0'
+__version__ = '1.1.1'
 
 from .sofa import Sofa
 
-from .io import read_sofa, write_sofa
+from .io import read_sofa, read_sofa_as_netcdf, write_sofa
 
 from .utils import (list_conventions,
                     equals,
@@ -21,6 +21,7 @@ __all__ = ['Sofa',
            'update_conventions',
            'list_conventions',
            'read_sofa',
+           'read_sofa_as_netcdf',
            'write_sofa',
            'equals',
            'version']

{sofar-1.0.0 → sofar-1.1.1}/sofar/io.py

@@ -3,7 +3,8 @@ import os
 import numpy as np
 from netCDF4 import Dataset, chartostring, stringtochar
 import warnings
-import packaging
+import pathlib
+from packaging.version import parse
 import sofar as sf
 from .utils import _verify_convention_and_version, _atleast_nd
 
@@ -18,8 +19,7 @@ def read_sofa(filename, verify=True, verbose=True):
     Parameters
     ----------
     filename : str
-        The filename. '.sofa' is appended to the filename, if it is not
-        explicitly given.
+        The full path to the sofa data.
     verify : bool, optional
         Verify and update the SOFA object by calling :py:func:`~Sofa.verify`.
         This helps to find potential errors in the default values and is thus
@@ -32,7 +32,7 @@ def read_sofa(filename, verify=True, verbose=True):
     Returns
     -------
     sofa : Sofa
-        The SOFA object filled with the default values of the convention.
+        Object containing the data from `filename`.
 
     Notes
     -----
@@ -52,9 +52,63 @@ def read_sofa(filename, verify=True, verbose=True):
        will be a scalar inside SOFA objects after reading from disk.
     """
 
+    return _read_netcdf(filename, verify, verbose, mode="sofa")
+
+
+def read_sofa_as_netcdf(filename):
+    """
+    Read corrupted SOFA data from disk.
+
+    .. note::
+        `read_sofa_as_netcdf` is intended to read and fix corrupted SOFA data
+        that could not be read by :py:func:`~read_sofa`. The recommend workflow
+        is
+
+        - Try to read the data with `read_sofa` and ``verify=True``
+        - If this fails, try the above with ``verify=False``
+        - If this fails, use `read_sofa_as_netcdf`
+
+        The SOFA object  returned by `read_sofa_as_netcdf` may not work
+        correctly before the issues with the data were fixed, i.e., before the
+        data are in agreement with the SOFA standard AES-69.
+
+    Numeric data is returned as floats or numpy float arrays unless they have
+    missing data, in which case they are returned as numpy masked arrays.
+
+    Parameters
+    ----------
+    filename : str
+        The full path to the NetCDF data.
+
+    Returns
+    -------
+    sofa : Sofa
+        Object containing the data from `filename`.
+
+    Notes
+    -----
+
+    1. Missing dimensions are appended when writing the SOFA object to disk.
+       E.g., if ``sofa.Data_IR`` is of shape (1, 2) it is written as an array
+       of shape (1, 2, 1) because the SOFA standard AES69-2020 defines it as a
+       three dimensional array with the dimensions (`M: measurements`,
+       `R: receivers`, `N: samples`)
+    2. When reading data from a SOFA file, array data is always returned as
+       numpy arrays and singleton trailing dimensions are discarded (numpy
+       default). I.e., ``sofa.Data_IR`` will again be an array of shape (1, 2)
+       after writing and reading to and from disk.
+    3. One dimensional arrays with only one element will be converted to scalar
+       values. E.g. ``sofa.Data_SamplingRate`` is stored as an array of shape
+       (1, ) inside SOFA files (according to the SOFA standard AES69-2020) but
+       will be a scalar inside SOFA objects after reading from disk.
+    """
+    return _read_netcdf(filename, False, False, mode="netcdf")
+
+
+def _read_netcdf(filename, verify, verbose, mode):
+
     # check the filename
-    if not filename.endswith('.sofa'):
-        raise ValueError("Filename must end with .sofa")
+    filename = pathlib.Path(filename).with_suffix('.sofa')
     if not os.path.isfile(filename):
         raise ValueError(f"{filename} does not exist")
 
@@ -68,29 +122,25 @@ def read_sofa(filename, verify=True, verbose=True):
     # open new NETCDF4 file for reading
     with Dataset(filename, "r", format="NETCDF4") as file:
 
-        # get convention name and version
-        convention = getattr(file, "SOFAConventions")
-        all_attr.append("GLOBAL_SOFAConventions")
-        version_in = getattr(file, "SOFAConventionsVersion")
-        all_attr.append("GLOBAL_SOFAConventionsVersion")
+        if mode == "sofa":
+            # get convention name and version
+            convention = getattr(file, "SOFAConventions")
+            version = getattr(file, "SOFAConventionsVersion")
 
-        # check if convention and version exist
-        version_out = _verify_convention_and_version(
-            version_in, version_in, convention)
+            # check if convention and version exist
+            _verify_convention_and_version(version, convention)
 
-        # get SOFA object with default values
-        sofa = sf.Sofa(convention, version=version_out, verify=verify)
+            # get SOFA object with default values
+            sofa = sf.Sofa(convention, version=version, verify=verify)
+        else:
+            sofa = sf.Sofa(None)
 
         # allow writing read only attributes
-        sofa._protected = False
+        sofa.protected = False
 
         # load global attributes
         for attr in file.ncattrs():
 
-            if attr in ["SOFAConventionsVersion", "SOFAConventions"]:
-                # convention and version were already set above
-                continue
-
             value = getattr(file, attr)
             all_attr.append(f"GLOBAL_{attr}")
 
@@ -98,7 +148,7 @@ def read_sofa(filename, verify=True, verbose=True):
                 sofa._add_custom_api_entry(
                     f"GLOBAL_{attr}", value, None, None, "attribute")
                 custom.append(f"GLOBAL_{attr}")
-                sofa._protected = False
+                sofa.protected = False
             else:
                 setattr(sofa, f"GLOBAL_{attr}", value)
 
@@ -117,7 +167,7 @@ def read_sofa(filename, verify=True, verbose=True):
                 sofa._add_custom_api_entry(var.replace(".", "_"), value, None,
                                            dimensions, dtype)
                 custom.append(var.replace(".", "_"))
-                sofa._protected = False
+                sofa.protected = False
 
             # load variable attributes
             for attr in [a for a in file[var].ncattrs() if a not in skip]:
@@ -130,7 +180,7 @@ def read_sofa(filename, verify=True, verbose=True):
                         var.replace(".", "_") + "_" + attr, value, None,
                         None, "attribute")
                     custom.append(var.replace(".", "_") + "_" + attr)
-                    sofa._protected = False
+                    sofa.protected = False
                 else:
                     setattr(sofa, var.replace(".", "_") + "_" + attr, value)
 
@@ -142,7 +192,7 @@ def read_sofa(filename, verify=True, verbose=True):
             delattr(sofa, attr)
 
     # do not allow writing read only attributes any more
-    sofa._protected = True
+    sofa.protected = True
 
     # notice about custom entries
     if custom and verbose:
@@ -206,20 +256,23 @@ def _write_sofa(filename: str, sofa: sf.Sofa, compression=4, verify=True):
     """
 
     # check the filename
-    if not filename.endswith('.sofa'):
-        raise ValueError("Filename must end with .sofa")
-
-    # check if the latest version is used for writing and warn otherwise
-    # if case required for writing SOFA test data that violates the conventions
-    if sofa.GLOBAL_SOFAConventions != "invalid-value":
-        latest = sf.Sofa(sofa.GLOBAL_SOFAConventions)
-        latest = latest.GLOBAL_SOFAConventionsVersion
-        current = sofa.GLOBAL_SOFAConventionsVersion
-
-        if packaging.version.parse(current) < packaging.version.parse(latest):
-            warnings.warn(("Writing SOFA object with outdated Convention "
-                           f"version {current}. Use version='latest' to write "
-                           f"data with version {latest}."))
+    filename = pathlib.Path(filename).with_suffix('.sofa')
+
+    if verify:
+        # check if the latest version is used for writing and warn otherwise
+        # if case required for writing SOFA test data that violates the
+        # conventions
+        if sofa.GLOBAL_SOFAConventions != "invalid-value":
+            latest = sf.Sofa(sofa.GLOBAL_SOFAConventions)
+            latest = latest.GLOBAL_SOFAConventionsVersion
+            current = sofa.GLOBAL_SOFAConventionsVersion
+
+            if parse(current) < parse(latest):
+                warnings.warn((
+                    "Writing SOFA object with outdated Convention "
+                    f"version {current}. It is recommend to upgrade "
+                    " data with Sofa.upgrade_convention() before "
+                    "writing to disk if possible."))
 
     # setting the netCDF compression parameter
     use_zlib = compression != 0

{sofar-1.0.0 → sofar-1.1.1}/sofar/sofa.py

@@ -89,35 +89,43 @@ class Sofa():
         """See class docstring"""
 
         # get convention
-        self._convention = self._load_convention(convention, version)
+        if convention is not None:
+            self._convention = self._load_convention(convention, version)
 
-        # update read only attributes
-        self._read_only_attr = [
-            key for key in self._convention.keys()
-            if self._read_only(self._convention[key]["flags"])]
+            # update read only attributes
+            self._read_only_attr = [
+                key for key in self._convention.keys()
+                if self._read_only(self._convention[key]["flags"])]
 
-        # add attributes with default values
-        self._convention_to_sofa(mandatory)
+            # add attributes with default values
+            self._convention_to_sofa(mandatory)
 
-        # add and update the API
-        # (mandatory=False can not be verified because some conventions have
-        # default values that have optional variables as dependencies)
-        if verify and not mandatory:
-            self.verify(mode="read")
+            # add and update the API
+            # (mandatory=False can not be verified because some conventions
+            # have default values that have optional variables as dependencies)
+            if verify and not mandatory:
+                self.verify(mode="read")
 
-        self._protected = True
+            self.protected = True
+        else:
+            verify = False
+            self._convention = {}
 
     def __setattr__(self, name: str, value):
         # don't allow new attributes to be added outside the class
-        if self._protected and not hasattr(self, name):
+        if self.protected and not hasattr(self, name):
             raise TypeError(f"{name} is an invalid attribute")
 
         # don't allow setting read only attributes
-        if name in self._read_only_attr and self._protected:
-            raise TypeError(f"{name} is a read only attribute")
+        if name in self._read_only_attr and self.protected:
+            raise TypeError((
+                f"{name} is a read only attribute. Iy you know what you are "
+                "doing, you can set Sofa.protected = False to write read "
+                "only data (e.g., to repair corrupted SOFA data)."))
 
         # convert to numpy array or scalar
-        if not isinstance(value, (str, dict, np.ndarray)):
+        if not isinstance(value, (str, dict, np.ndarray)) \
+                and name != "protected":
             value = np.atleast_2d(value)
             if value.size == 1:
                 value = value.flatten()[0]
@@ -129,7 +137,7 @@ class Sofa():
         if not hasattr(self, name):
             raise TypeError(f"{name} is not an attribute")
         # delete anything if not frozen, delete non mandatory
-        if not self._protected or \
+        if not self.protected or \
                 not self._mandatory(self._convention[name]["flags"]):
             super().__delattr__(name)
 
@@ -287,9 +295,17 @@ class Sofa():
                 attribute will be printed.
         """
 
+        # warn for upcoming deprecation
+        warnings.warn((
+            'Sofa.info() will be deprecated in sofar 1.3.0 The conventions are'
+            ' now documented at '
+            'https://sofar.readthedocs.io/en/stable/resources/conventions.html'),  # noqa
+            UserWarning)
+
         # update the private attribute `_convention` to make sure the required
         # meta data is in place
-        self._update_convention(version="match")
+        if not hasattr(self, "_convention"):
+            self._reset_convention()
 
         # list of all attributes
         keys = [k for k in self.__dict__.keys() if not k.startswith("_")]
@@ -461,13 +477,13 @@ class Sofa():
         """
 
         # initialize
-        self._update_convention(version="match")
+        self._reset_convention()
         added = "Added the following missing data with their default values:\n"
 
         # current data
         keys = [key for key in self.__dict__.keys() if not key.startswith("_")]
 
-        self._protected = False
+        self.protected = False
 
         # loop data in convention
         for key in self._convention.keys():
@@ -480,7 +496,7 @@ class Sofa():
                 added += f"- {key} "
                 added += f"({'mandatory' if is_mandatory else 'optional'})\n"
 
-        self._protected = True
+        self.protected = True
 
         if verbose:
             if "-" in added:
@@ -510,7 +526,7 @@ class Sofa():
 
         dimensions : str
             The shape of the new entry as a string. See
-            ``self.info('dimensions')``.
+            :py:func:`~Sofa.list_dimensions`.
 
         Examples
         --------
@@ -565,9 +581,10 @@ class Sofa():
         """
         Delete variable or attribute from SOFA object.
 
-        Note that mandatory data can not be deleted. Call
-        :py:func:`Sofa.info("optional") <sofar.sofar.Sofa.info>` to list all
-        optional variables and attributes.
+        Note that mandatory data can not be deleted. Check the
+        `sofar documentation
+        <https://sofar.readthedocs.io/en/stable/resources/conventions.html>`_
+        for a complete list of optional variables and attributes.
 
         Parameters
         ----------
@@ -576,6 +593,26 @@ class Sofa():
         """
         delattr(self, name)
 
+    @property
+    def protected(self):
+        """
+        If Sofa.protected is ``True``, read only data can not be changed. Only
+        change this to ``False`` if you know what you are doing, e.g., if you
+        need to repair corrupted SOFA data.
+        """
+        return self._protected
+
+    @protected.setter
+    def protected(self, value: bool):
+        """
+        If Sofa.protected is ``True``, read only data can not be changed. Only
+        change this to ``False`` if you know what you are doing, e.g., if you
+        need to repair corrupted SOFA data.
+        """
+        if not isinstance(value, bool):
+            raise ValueError("Sofa.protected can only be True or False")
+        self._protected = value
+
     def _add_entry(self, name, value, dtype, dimensions):
         """
         Add custom data to a SOFA object. See add_variable and add_attribute
@@ -633,7 +670,7 @@ class Sofa():
             double, string, or attribute
         """
         # create custom API if it not exists
-        self._protected = False
+        self.protected = False
 
         # lower case letters to indicate custom dimensions
         if dimensions is not None:
@@ -652,11 +689,11 @@ class Sofa():
                 "type": dtype,
                 "default": None,
                 "comment": ""}
-        self._update_convention(version="match")
+            self._convention[key] = self._custom[key]
 
         # add attribute to object
         setattr(self, key, value)
-        self._protected = True
+        self.protected = True
 
     def upgrade_convention(self, target=None, verify=True):
         """
@@ -687,7 +724,7 @@ class Sofa():
         """
 
         # check input ---------------------------------------------------------
-        self._update_convention(version="match")
+        self._reset_convention()
 
         # get deprecations and information about Sofa object
         _, _, deprecations, upgrade = self._verification_rules()
@@ -763,7 +800,7 @@ class Sofa():
                 "GLOBAL_Version",
                 "GLOBAL_DataType"]
 
-        self._protected = False
+        self.protected = False
         for key in keys:
             setattr(self, key, self._convention[key]["default"])
 
@@ -813,7 +850,7 @@ class Sofa():
 
         # check for missing mandatory data
         self.add_missing(True, False)
-        self._protected = True
+        self.protected = True
 
         # display general message
         if upgrade["message"] is not None:
@@ -908,7 +945,7 @@ class Sofa():
 
         # ---------------------------------------------------------------------
         # 0. update the convention
-        self._update_convention("match")
+        self._reset_convention()
 
         # ---------------------------------------------------------------------
         # 1. check if the mandatory attributes are contained
@@ -921,9 +958,9 @@ class Sofa():
 
                 if issue_handling != "raise":
                     # add missing data with default value
-                    self._protected = False
+                    self.protected = False
                     setattr(self, key, self._convention[key]["default"])
-                    self._protected = True
+                    self.protected = True
 
                 # prepare to raise warning
                 missing += "- " + key + "\n"
@@ -1104,10 +1141,10 @@ class Sofa():
         # 4. Get dimensions (E, R, M, N, S, c, I, and custom)
 
         # initialize required API fields
-        self._protected = False
+        self.protected = False
         self._dimensions = {}
         self._api = {}
-        self._protected = True
+        self.protected = True
 
         # get keys for checking the dimensions (all SOFA variables)
         keys = [key for key in self.__dict__.keys()
@@ -1548,49 +1585,36 @@ class Sofa():
         """Return a copy of the SOFA object."""
         return deepcopy(self)
 
-    def _update_convention(self, version):
+    def _reset_convention(self):
         """
-        Add SOFA convention to SOFA object in private attribute `_convention`.
-        If The object already contains a convention, it will be overwritten.
-
-        Parameters
-        ----------
-        version : str
-            ``'latest'``
-                Use the latest API and upgrade the SOFA file if required.
-            ``'match'``
-                Match the version of the sofa file.
-            str
-                Version string, e.g., ``'1.0'``.
+        - Add SOFA convention to SOFA object in private attribute
+          `_convention`. If The object already contains a convention, it will
+          be overwritten.
+        - If the SOFA object contains custom entries, check if any of the
+          custom entries part of the convention. If yes, delete the entry from
+          self._custom
+        - If the SOFA objects contains custom entries, add entries from
+          self._custom to self._convention
         """
 
         # verify convention and version
         c_current = self.GLOBAL_SOFAConventions
         v_current = str(self.GLOBAL_SOFAConventionsVersion)
 
-        v_new = _verify_convention_and_version(
-                version, v_current, c_current)
+        _verify_convention_and_version(v_current, c_current)
 
         # load and add convention and version
         convention = self._load_convention(
-            c_current, v_new)
+            c_current, v_current)
         self._convention = convention
 
-        if v_current != v_new:
-            self._protected = False
-            self.GLOBAL_SOFAConventionsVersion = v_new
-            self._protected = True
-
-        # feedback in case of up/downgrade
-        if float(v_current) < float(v_new):
-            warnings.warn(("Upgraded SOFA object from "
-                           f"version {v_current} to {v_new}"))
-        elif float(v_current) > float(v_new):
-            warnings.warn(("Downgraded SOFA object from "
-                           f"version {v_current} to {v_new}"))
-
-        # check if custom fields can be added
         if hasattr(self, "_custom"):
+            # check of custom fields can be removed
+            for key in self._convention:
+                if key in self._custom:
+                    del self._custom[key]
+
+            # check if custom fields can be added
             for key in self._custom:
                 self._convention[key] = self._custom[key]
 
@@ -1684,7 +1708,7 @@ class Sofa():
 
         # write API and date specific fields (some read only)
         now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-        self._protected = False
+        self.protected = False
         self.GLOBAL_DateCreated = now
         self.GLOBAL_DateModified = now
         self.GLOBAL_APIName = "sofar SOFA API for Python (pyfar.org)"
@@ -1694,7 +1718,7 @@ class Sofa():
             f"{platform.python_version()} "
             f"[{platform.python_implementation()} - "
             f"{platform.python_compiler()}]")
-        self._protected = True
+        self.protected = True
 
     @staticmethod
     def _get_size_and_shape_of_string_var(value, key):