API Reference#

This section documents sofar objects and functions. Sofar contains functions for reading, writing and comparing SOFA files, functions to handle SOFA conventions, and two classes to handle data from SOFA files. The Sofa class is used to read and write entire SOFA files. To open a SOFA file without reading the entire file into memory, SofaStream enables partially reading data.

For examples on how to use sofar refer to the sofar and SOFA notebook and the documentation below.

Classes:

Sofa(convention[, mandatory, version, verify])

Create a new SOFA object.

SofaStream(filename)

Read desired data from SOFA-file directly from disk without loading entire file into memory.

Functions:

equals(sofa_a, sofa_b[, verbose, exclude])

Compare two SOFA objects against each other.

list_conventions()

List available SOFA conventions by printing to the console.

read_sofa(filename[, verify, verbose])

Read SOFA file from disk and convert it to SOFA object.

read_sofa_as_netcdf(filename)

Read corrupted SOFA data from disk.

update_conventions([conventions_path, ...])

Update SOFA conventions.

version()

Return version of sofar and SOFA conventions

write_sofa(filename, sofa[, compression])

Write a SOFA object to disk as a SOFA file.

class sofar.Sofa(convention, mandatory=False, version='latest', verify='auto')[source]#

Bases: object

Create a new SOFA object.

Parameters:
  • convention (str) – The name of the convention from which the SOFA file is created. See list_conventions.

  • mandatory (bool, optional) – If True, only the mandatory data of the convention will be returned. The default is False, which returns mandatory and optional data.

  • version (str, optional) – The version of the convention as a string, e.g., ' 2.0'. The default is 'latest'. Also see list_conventions.

  • verify (bool, optional) – Verify the SOFA object by calling verify. This helps to find potential errors in the default values and is thus recommended If creating a file does not work, try to call Sofa with verify=False. The default 'auto' defaults to True for stable conventions with versions of 1.0 or higher and to False otherwise.

Returns:

sofa – A SOFA object filled with the default values of the convention.

Return type:

Sofa

Examples

Create a new SOFA object with default values

import sofar as sf

# create SOFA object
sofa = sf.Sofa("SimpleFreeFieldHRIR")

Add data as a list

sofa.Data_IR = [1, 1]

Data can be entered as numbers, numpy arrays or lists. Note the following

  1. Lists are converted to numpy arrays with at least two dimensions, i.e., sofa.Data_IR is converted to a numpy array of shape (1, 2)

  2. Missing dimensions are appended when writing the SOFA object to disk, i.e., sofa.Data_IR is written as an array of shape (1, 2, 1) because the SOFA standard AES69 defines it as a three dimensional array with the dimensions (M: measurements, R: receivers, N: samples)

  3. 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.

  4. 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) but will be a scalar inside SOFA objects after reading from disk.

For more examples refer to the Quick tour of SOFA and sofar at https://sofar.readthedocs.io/en/stable/

Methods:

add_attribute(name, value)

Add custom attribute to the SOFA object.

add_missing([mandatory, optional, verbose])

Add missing data with default values.

add_variable(name, value, dtype, dimensions)

Add custom variable to the SOFA object, i.e., numeric or string arrays.

copy()

Return a copy of the SOFA object.

delete(name)

Delete variable or attribute from SOFA object.

get_dimension(dimension)

Get size of a SOFA dimension

info([info])

Print information about the convention of a SOFA object.

inspect([file, issue_handling])

Get information about data inside a SOFA object.

upgrade_convention([target, verify])

Upgrade Sofa data to newer conventions.

verify([issue_handling, mode])

Verify a SOFA object against the SOFA standard.

Attributes:

list_dimensions

Print the dimensions of the SOFA object

protected

If Sofa.protected is True, read only data can not be changed.

add_attribute(name, value)[source]#

Add custom attribute to the SOFA object.

Parameters:
  • name (str) – Name of the new attribute.

  • value (str) – value to be added.

Examples

import sofar as sf
sofa = sf.Sofa("GeneralTF")

# add GLOBAL and Variable attribute
sofa.add_attribute("GLOBAL_DateMeasured", "8.08.2021")
sofa.add_attribute("Data_Real_Units", "Pascal")
add_missing(mandatory=True, optional=True, verbose=True)[source]#

Add missing data with default values.

Data might be missing in SOFA objects if the creator did not include it or if a new data was suggested for a newer version of a SOFA convention. Use this function to add the data with its default values.

mandatoryBool

Add missing mandatory data. The default is True.

optionalBool

Add missing optional data. The default is True.

verboseBool

Print the information about added data to the console. The default is True.

add_variable(name, value, dtype, dimensions)[source]#

Add custom variable to the SOFA object, i.e., numeric or string arrays.

Parameters:
  • name (str) – Name of the new variable.

  • value (any) – value to be added (see dtype for restrictions).

  • dtype (str) –

    Type of the entry to be added in netCDF style:

    'double'

    Use this to store numeric data that can be provided as number list or numpy array.

    'string'

    Use this to store string variables as numpy string arrays of type 'U' or 'S'.

  • dimensions (str) – The shape of the new entry as a string. See list_dimensions.

Examples

import sofar as sf
sofa = sf.Sofa("GeneralTF")

# add numeric data
sofa.add_variable("Temperature", 25.1, "double", "MI")

# add GLOBAL and Variable attribute
sofa.add_entry(
    "GLOBAL_DateMeasured", "8.08.2021", "attribute", None)
sofa.add_entry(
    "Temperature_Units", "degree Celsius", "attribute", None)

# add a string data
sofa.add_variable(
    "Comment", "Measured with wind screen", "string", "MS")
copy()[source]#

Return a copy of the SOFA object.

delete(name)[source]#

Delete variable or attribute from SOFA object.

Note that mandatory data can not be deleted. Check the sofar documentation for a complete list of optional variables and attributes.

Parameters:

name (str) – Name of the variable or attribute to be deleted

get_dimension(dimension)[source]#

Get size of a SOFA dimension

SOFA dimensions specify the shape of the data contained in a SOFA object. For a list of all dimensions see list_dimensions.

Parameters:

dimension (str) – The dimension as a string, e.g., 'N'.

Returns:

size – the size of the queried dimension.

Return type:

int

info(info='all')[source]#

Print information about the convention of a SOFA object.

Prints the variable type (attribute, double, string), shape, flags (mandatory, read only) and comment (if any) for each or selected entries.

Parameters:

info (str) –

Specifies the kind of information that is printed:

'all' 'mandatory' 'optional' 'read only' 'data'

Print the name, type, shape, and flags and comment for all or selected entries of the SOFA object. 'data' does not show entries of type attribute.

key

If key is the name of an object attribute, all information for attribute will be printed.

inspect(file=None, issue_handling='print')[source]#

Get information about data inside a SOFA object.

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.

  • issue_handling (str, optional) –

    Defines how issues detected during verification of the SOFA object are handled (see verify)

    'raise'

    Warnings and errors are raised if issues are detected

    'print'

    Issues are printed without raising warnings and errors

    'return'

    Issues are returned as string but neither raised nor printed

    'ignore'

    Issues are ignored, i.e., not raised, printed, or returned.

    The default is 'print'.

property list_dimensions#

Print the dimensions of the SOFA object

See inspect to see the shapes of the data inside the SOFA object and get_dimension to get the size/value of a specific dimensions as integer number.

The SOFA file 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 self.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.

property protected#

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.

upgrade_convention(target=None, verify='auto')[source]#

Upgrade Sofa data to newer conventions.

Calling this with the default arguments returns a list of possible conventions to which the data will be upgraded. If the data is up to date the list will be empty.

Parameters:
  • target (str, optional) – The convention and version to which the data should be upgraded as a string. For example 'SimpleFreeFieldHRIR_1.0' would upgrade the data to the SOFA-Convention SimpleFreeFieldHRIR version 1.0. The default is None which returns a list of possible conventions to which the data can be updated.

  • verify (bool, optional) – Flag to specify if the data should be verified after the upgrade using verify. The default 'auto' defaults to True for stable conventions with versions of 1.0 or higher and to False otherwise.

Returns:

target – List with available conventions to which the data can be updated. If the data is up to data, the list will be empty. target is only returned if target is None.

Return type:

list of strings

verify(issue_handling='raise', mode='write')[source]#

Verify a SOFA object against the SOFA standard.

This function updates the API, and checks the following

  • Are all mandatory data contained? If issue_handling is "raise" missing mandatory data raises an error. Otherwise mandatory data are added with their default value and a warning is given.

  • Are the names of variables and attributes in accordance to the SOFA standard?

  • Are the data types in accordance with the SOFA standard?

  • Are the dimensions of the variables consistent and in accordance to the SOFA standard?

  • Are the values of attributes consistent and in accordance to the SOFA standard?

A detailed set of validation rules can be found at pyfar/sofar

Note

verify is automatically called when you create a new SOFA object, read a SOFA file from disk, and write a SOFA file to disk (using the default parameters).

The API of a SOFA object consists of four parts, that are stored dictionaries in private attributes. This is required for writing data with write_sofa and should usually not be manipulated outside of verify

self._convention

The SOFA convention with default values, variable dimensions, flags and comments. These data are read from the official SOFA conventions contained in the SOFA Matlab/Octave API.

self._dimensions

The detected dimensions of the data inside the SOFA object.

self._api

The size of the dimensions (see py:func:~list_dimensions). This specifies the dimensions of the data inside the SOFA object.

self._custom

Stores information of custom variables that are not defined by the convention. The format is the same as in self._convention.

Parameters:
  • issue_handling (str, optional) –

    Defines how detected issues are handled

    'raise'

    Warnings and errors are raised if issues are detected

    'print'

    Issues are printed without raising warnings and errors

    'return'

    Issues are returned as string but neither raised nor printed

    The default is 'raise'.

  • mode (str, optional) –

    The SOFA standard is more strict for writing data than for reading data.

    'write'

    All units (e.g. ‘meter’) must be written be lower case.

    'read'

    Units can contain upper case letters (e.g. ‘Meter’)

    The default is 'write'

Returns:

issues – Detected issues as a string. None if no issues were detected. Note that this is only returned if issue_handling='return' (see above)

Return type:

str, None

class sofar.SofaStream(filename)[source]#

Bases: object

Read desired data from SOFA-file directly from disk without loading entire file into memory.

SofaStream opens a SOFA-file and retrieves only the requested data.

If you want to use all the data from a SOFA-file use Sofa class and read_sofa function instead.

Parameters:

filename (str) – Full path to a SOFA-file

Returns:

sofa_stream – A SofaStream object which reads directly from the file.

Return type:

SofaStream

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)

Methods:

get_dimension(dimension)

Get size of a SOFA dimension

inspect([file])

Get information about the data inside a SOFA-file

Attributes:

list_dimensions

Print the dimensions of the SOFA-file

get_dimension(dimension)[source]#

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 list_dimensions, for more information about the data contained in a SOFA-file use inspect.

Parameters:

dimension (str) – The dimension as a string, e.g., 'N'.

Returns:

size – the size of the queried dimension.

Return type:

int

inspect(file=None)[source]#

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.

property list_dimensions#

Print the dimensions of the SOFA-file

See inspect to see the shapes of the data inside the SOFA-file and 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.

sofar.equals(sofa_a, sofa_b, verbose=True, exclude=None)[source]#

Compare two SOFA objects against each other.

Parameters:
  • sofa_a (Sofa) – SOFA object

  • sofa_b (Sofa) – SOFA object

  • verbose (bool, optional) – Print differences to the console. The default is True.

  • exclude (str, optional) –

    Specify what fields should be excluded from the comparison

    'GLOBAL'

    Exclude all global attributes, i.e., fields starting with ‘GLOBAL:’

    'DATE'

    Exclude date attributes, i.e., fields that contain ‘Date’

    'ATTR'

    Exclude all attributes, i.e., fields that contain ‘:’

    The default is None, which does not exclude anything.

Returns:

is_identicalTrue if sofa_a and sofa_b are identical, False otherwise.

Return type:

bool

sofar.list_conventions()[source]#

List available SOFA conventions by printing to the console.

sofar.read_sofa(filename, verify='auto', verbose=True)[source]#

Read SOFA file from disk and convert it to SOFA object.

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.

If you want to read only parts of the data of a large sofa file use SofaStream instead.

Parameters:
  • filename (str) – The full path to the sofa data.

  • verify (bool, optional) – Verify and update the SOFA object by calling verify. This helps to find potential errors in the default values and is thus recommended. If reading a file does not work, try to call Sofa with verify=False. The default is 'auto' defaults to True for stable conventions with versions of 1.0 or higher and to False otherwise.

  • verbose (bool, optional) – Print the names of detected custom variables and attributes. The default is True

Returns:

sofa – Object containing the data from filename.

Return type:

Sofa

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 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) but will be a scalar inside SOFA objects after reading from disk.

sofar.read_sofa_as_netcdf(filename)[source]#

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 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 – Object containing the data from filename.

Return type:

Sofa

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 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) but will be a scalar inside SOFA objects after reading from disk.

sofar.update_conventions(conventions_path=None, assume_yes=False)[source]#

Update SOFA conventions.

SOFA convention define what data is stored in a SOFA file and how it is stored. Updating makes sure that sofar is using the latest conventions. This is done in three steps

  1. Download official SOFA conventions as csv files from https://www.sofaconventions.org/conventions/ and https://www.sofaconventions.org/conventions/deprecated/.

  2. Notify which conventions would be added or updated.

  3. 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 and their paths see list_conventions.

Note

If the official convention contain errors, calling this function might break sofar. If this is the case sofar must be re-installed, e.g., by running pip install --force-reinstall sofar. Be sure that you want to do this.

Parameters:
  • conventions_path (str, optional) – Path to the folder where the conventions are saved. The default is 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.

  • assume_yes (bool, optional) –

    False

    Updating the conventions must be confirmed by typing “y”.

    True

    The conventions are updated without confirmation.

    The default is False

sofar.version()[source]#

Return version of sofar and SOFA conventions

sofar.write_sofa(filename: str, sofa: Sofa, compression=4)[source]#

Write a SOFA object to disk as a SOFA file.

Parameters:
  • filename (str) – The filename. ‘.sofa’ is appended to the filename, if it is not explicitly given.

  • sofa (object) – The SOFA object that is written to disk

  • compression (int) – The level of compression with 0 being no compression and 9 being the best compression. The default of 9 optimizes the file size but increases the time for writing files to disk.

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 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) but will be a scalar inside SOFA objects after reading from disk.