sofar documentation

This is the official sofar documentation. For examples on how to use sofa refer to the Quick tour of SOFA and sofar.

Classes:

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

Create a new SOFA object.

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, version, verbose])

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

write_sofa(filename, sofa[, version, ...])

Write a SOFA object to disk as a SOFA file.
class sofar.sofar.Sofa(convention, mandatory=False, version='latest', verify=True)[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 is True.

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-2020 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-2020) 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/latest/

Methods:

add_attribute(name, value)

Add custom attribute to the SOFA object.

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.

verify([version, issue_handling])

Verify a SOFA object against the SOFA standard.

Attributes:

list_dimensions

Print the dimensions of the SOFA object
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 attribtue
sofa.add_attribute("GLOBAL_DateMeasured", "8.08.2021")
sofa.add_attribute("Data_Real_Units", "Pascal")
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 self.info('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 attribtue
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. Call Sofa.info("optional") to list all 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)[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 does only print the information.

  • issue_handling (str, optional) –

    Defines how issues detected during verification of the SOFA object are handeled (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

The SOFA file standard defines the following dimensions:

M

number of measurements

N

number of samles, 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.

see info to see the shapes of the data inside the SOFA object.

verify(version='latest', issue_handling='raise')[source]

Verify a SOFA object against the SOFA standard.

This function updates the API, and checks the following

  • Are all mandatory fields contained? If not mandatory fields are added with their default value and a warning is raised.

  • Are the names of variables and attributes in accordance to the SOFA standard? If not a warning is raised.

  • 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?

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

  • version (str, optional) –

    The version to which the API is updated.

    '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'. Note that this might downgrade the SOFA object

    The default is 'latest'

  • issue_handling (str, optional) –

    Defines how detected issues are handeled

    '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 'raise'.

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

sofar.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 attributs, 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_identical – True if sofa_a and sofa_b are identical, False otherwise.

Return type

bool

sofar.sofar.list_conventions()[source]

List available SOFA conventions by printing to the console.

sofar.sofar.read_sofa(filename, verify=True, version='latest', 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.

Parameters

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

  • 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 True.

  • version (str, optional) –

    Control if the SOFA file convention is changed.

    'latest'

    Update the conventions to the latest version

    'match'

    Do not change the conventions version, i.e. match the version of the SOFA file that is being read.

    str

    Force specific version, e.g., '1.0'. Note that this might downgrade the SOFA object.

    The default is 'latest'

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

Returns

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

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

sofar.sofar.write_sofa(filename: str, sofa: sofar.sofar.Sofa, version='latest', 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

  • version (str) –

    The SOFA object is verified and updated with verify before writing to disk. Version specifies, which version of the convention is used:

    'latest'

    Use the latest version upgrade the SOFA file if required.

    'match'

    Match the version of the SOFA object.

    str

    Version string, e.g., '1.0'.

    The default is 'latest'.

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