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	Type	Comment
GLOBAL_Conventions	SOFA	r
GLOBAL_Version		r			Insert the actual SOFA version here
GLOBAL_SOFAConventions					Insert the name of the actual SOFA Conventions here
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				Insert the name of the actual datatype here
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	double
ListenerPosition_Type	cartesian
ListenerPosition_Units	meter
ReceiverPosition	[0 -0.09 0; 0 0.09 0]		rCI, rCM	double
ReceiverPosition_Type	cartesian
ReceiverPosition_Units	meter
SourcePosition	[0 0 0]		IC, MC	double
SourcePosition_Type	cartesian
SourcePosition_Units	meter
EmitterPosition	[0 0 0]		eCI, eCM	double
EmitterPosition_Type	cartesian
EmitterPosition_Units	meter

Note: we consider the Data as mandatory, thus, Data must be provided according the corresponding DataType. If DataType is default (="FIR") then Data for the datatype "FIR" 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
• 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)
• Type: type of the data, i.e., double, string, etc. Empty if attribute

Dimensional variables (coordinate variables): 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. We suggest the type "double" for the dimensional variables.

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.

Can datatypes change within conventions?

If yes, any application would have either to implement all possible datatypes or to check if the supported datatype is given within the conventions.

Thus, no, until we will have so many conventions with only the datatype changing that we decide to change this decision.

Fix the coordinate systems within conventions?

Until now, Conventions support just a single coordinate system per variable and each application must use conversion functions if required.

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	1	mRn	double	real part of the complex spectrum
Data.Imag	0	MRN	double	imaginary part of the complex spectrum
N	0	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 propose to add a new field, Delay to the FIR type.

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