Ctrl+K

sofar functions#

This section documents general functions of the sofar package. Handling data in SOFA objects is described in SOFA objects. For examples on how to use sofa refer to the Quick tour of SOFA and sofar.

Top-level package for sofar.

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.
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.list_conventions()[source]#

List available SOFA conventions by printing to the console.

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

  • 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-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.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-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.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. Convert csv files to json files to be read by sofar.

  3. Notify which conventions were newly added or updated.

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.

  • response (bool, optional) –

    True

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

    False

    The conventions are updated without confirmation.

    The default is True

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

On this page