Ctrl+K

SOFA objects#

This section documents sofar SOFA objects. Functions that work on SOFA objects are described in the sofar functions guide. For examples on how to use sofar refer to the Quick tour of SOFA and sofar.

class 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_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 attribtue
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 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. 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 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

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

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=True)[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 is True.

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

    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

On this page