Proposal 0.4

Only changes compared to the last version are listed here!!!

Please discuss the proposal by using the "Discussion" function of Wiki.

Fix mandatory metadata

The metadata mandatory in all SOFA conventions have not been fixed yet. We propose to have the following metadata mandatory in all SOFA conventions:

Name	Default	Read-Only	Dimensions	Comment
GLOBAL_Conventions	SOFA	r
GLOBAL_Version	*	r		Insert the actual SOFA version here
GLOBAL_SOFAConventions	SimpleFreeFieldHRIR
GLOBAL_SOFAConventionsVersion	*			Insert the actual SOFA convention version here
GLOBAL_APIName	*			Insert the API Name here
GLOBAL_APIVersion	*			Insert the API Version here
GLOBAL_AuthorContact
GLOBAL_License	No license provided, ask the author for permission
GLOBAL_Organization
GLOBAL_RoomType	free field
GLOBAL_DataType	FIR
GLOBAL_History
GLOBAL_Source				The method of production of the original data. If it was model-generated, source should name the model and its version, as specifically as could be useful. If it is observational, source should characterize it.
GLOBAL_Title				A succinct description of what is in the dataset
GLOBAL_References				Published or web-based references that describe the data or methods used to produce it
GLOBAL_Comment
GLOBAL_DatabaseTimeCreated	*			will be updated when saving and not existing or empty
GLOBAL_DatabaseTimeModified	*			will be updated each time when saving
ListenerPosition	[1 0 0]		IC, MC
ListenerPosition_Type	cartesian
ListenerPosition_Units	meter
ReceiverPosition	[0 -0.09 0; 0 0.09 0]		rCI, rCM
ReceiverPosition_Type	cartesian
ReceiverPosition_Units	meter
SourcePosition	[0 0 0]		IC, MC
SourcePosition_Type	cartesian
SourcePosition_Units	meter
EmitterPosition	[0 0 0]		eCI, eCM
EmitterPosition_Type	cartesian
EmitterPosition_Units	meter
Data.IR	[1 1]		mRn	Only mandatory when DataType is FIR
Data.SamplingRate	48000		I	Only mandatory when DataType is FIR
Data.SamplingRate_Units	hertz			Only mandatory when DataType is FIR

Note: we consider the Data as mandatory, thus, if DataType is default (=FIR) then Data.FIR, Data.SamplingRate, and Data.SamplingRate_Units must be provided. Otherwise, the correct Data-fields must be provided.

Legend:

• Name: the name of the metadata
  • An underscore (_): the metadata is an attribute
    • GLOBAL_: the metadata is a global attribute
    • X_Y: the metadata is an attribute Y of the variable X
  • No underscore: the metadata is a variable
  • Data.X: the metadata is structured within the data
• Default: default value for the metadata
  • An asterisk (*): special handling required, mentioned in the column Comment
• Flags:
  • r: read-only, must be the default value and must not be changed
• Dimensions: dimensions of the metadata (see SOFA specifications for more explanations)
  • lower case: the variable size in that dimension determines the dimension size in the file
  • upper case: variable must be of that dimension (or one of these dimensions)

At the moment, we consider the dimension variables (or coordinate variables) as not mandatory, i.e., optional. Depending on the datatype and conventions, some of them might be mandatory, though.

Name	Default	Read-Only	Dimensions	Comment
I	1	r	I
I_LongName	singleton dimension	r
R	2		R
R_LongName	index of receivers	r
E	1		E
E_LongName	index of emitters	r
N	-		N
N_LongName	index
N_Units	sampling tap
M	-		M
M_LongName	index of measurements	r
C	3	r	C
C_LongName	coordinate triplet	r

Fix versioning of SOFA and conventions

Three version types:

• Version: defines the version of the general SOFA specs
• ConventionsVersion: defines the version of the particular SOFA conventions. Could be merged with Version, but then, when we change something a Conventions, each time the version for the general SOFA specs would need to be increased. Not clear how to proceed. Maybe the AES standardization process will clarify. Until then: no merging, to be on the safe side.
• APIVersion: clearly separated from the rest.

New datatype: IIRBiquad

Name	Default	Dimensions	Comment
Data.G	1	MR	broadband linear gain
Data.B1		MRN	nominator coefficient B1
Data.B2		MRN	nominator coefficient B2
Data.A1		MRN	denominator coefficient A1
Data.A2		MRN	denominator coefficient A2
Data.Delay	0	MR	broadband delay
Data.SamplingRate	48000	I	Sampling rate of the filter coefficients and the delay
Data.SamplingRate_Units	hertz

New datatype: ComplexSpectrum

Name	Default	Dimensions	Type	Comment
Data.Real		MRN	double	real part of the complex spectrum
Data.Imag		MRN	double	imaginary part of the complex spectrum
N		N	double	frequency values
N_LongName	frequency
N_Units	hertz

Note that the dimensional variable N is mandatory, must be of dimension N, and must provide the frequency values.

Update of datatype FIR

The standard committee agreed that the broadband delay should be provided in any case. Thus, we add a new field, Delay to the FIR type.

Name	Default	Dimensions	Type	Comment
Data.IR		MRN	double	impulse responses
Data.Delay	0	MR	double	broadband delay
Data.SamplingRate	48000	I	double	Sampling rate of the IRs and the delay
Data.SamplingRate_Units	hertz