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:
|
Create a new SOFA object. |
|
Read desired data from SOFA-file directly from disk without loading entire file into memory. |
Functions:
|
Compare two SOFA objects against each other. |
List available SOFA conventions by printing to the console. |
|
|
Read SOFA file from disk and convert it to SOFA object. |
|
Read corrupted SOFA data from disk. |
|
Update SOFA conventions. |
|
Return version of sofar and SOFA conventions |
|
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 isFalse
, 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 seelist_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 withverify=False
. The default'auto'
defaults toTrue
for stable conventions with versions of 1.0 or higher and toFalse
otherwise.
- Returns:
sofa – A SOFA object filled with the default values of the convention.
- Return type:
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
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)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)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.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:
Print the dimensions of the SOFA object
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")
- 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 andget_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 toFalse
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 isNone
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 toTrue
for stable conventions with versions of 1.0 or higher and toFalse
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 ofverify
- 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 andread_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:
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:
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 useinspect
.- 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 andget_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_identical –
True
if sofa_a and sofa_b are identical,False
otherwise.- Return type:
bool
- 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 withverify=False
. The default is'auto'
defaults toTrue
for stable conventions with versions of 1.0 or higher and toFalse
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:
Notes
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)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.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 isTry 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:
Notes
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)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.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
Download official SOFA conventions as csv files from https://www.sofaconventions.org/conventions/ and https://www.sofaconventions.org/conventions/deprecated/.
Notify which conventions would be added or updated.
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.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 and9
being the best compression. The default of9
optimizes the file size but increases the time for writing files to disk.
Notes
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)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.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.