NetCDF Template Engine

NetCDF metadata attributes are automatically populated from a set of template files, which reside in the NetCDF/template/ subdirectory. The following template files are used:

File	Use
global_attributes_timeSeries.txt	Global NetCDF attributes used in timeSeries mode
global_attributes_profile.txt	Global NetCDF attributes used in profile mode
dimension_attributes.txt	Any dimension attributes
variable_attributes.txt	Any variable attributes
time_attributes.txt	TIME coordinate variable attributes
longitude_attributes.txt	LONGITUDE scalar variable attributes
latitude_attributes.txt	LATITUDE scalar variable attributes
depth_attributes.txt	DEPTH scalar variable attributes
nominal_depth_attributes.txt	NOMINAL_DEPTH scalar variable attributes
dist_along_beams_attributes.txt	DIST_ALONG_BEAMS coordinate variable attributes
height_above_sensor_attributes.txt	HEIGHT_ABOVE_SENSOR coordinate variable attributes
profile_attributes.txt	PROFILE scalar variable attributes
timeseries_attributes.txt	TIMESERIES scalar variable attributes
trajectory_attributes.txt	TRAJECTORY scalar variable attributes
direction_attributes.txt	DIRECTION variable attributes
spct_attributes.txt	SPCT variable attributes
qc_coord_attributes.txt	Quality control attributes for coordinate variables
qc_attributes.txt	Quality control attributes

All of the template files except for the quality control ones are loaded when data is imported into the toolbox; the quality control template files are loaded just before data is exported. The generated attributes are added to the sample_data struct. you can use the template files to specify NetCDF attribute values in one of three different ways:

• Literal values (e.g. strings or numbers)
• Matlab expressions
• Deployment Database queries

When required, the template engine reads in a template, runs any DDB queries and executes any matlab expressions which are specified in the template, and adds the results to the sample_data struct.

A template file is a list of type,name=value tuples. The value section may contain, as listed above, literal strings, matlab expressions, database queries, or a combination of all three. The type is one of the following:

• S: String
• N: Numeric
• D: Date
• Q: Qualiy Control flag (will be cast to the same type as the quality control data for the QC set in use)

Date values may either be matlab serial dates (i.e. a number specifying days since Jan 1 0000 00:00:00), or in the format specified by the toolbox.timeFormat property.

Literal Strings

An example template attribute definition which simply provides a literal string:

S, project = Integrated Marine Observing System (IMOS)

DDB Queries

The syntax for setting an attribute value to be the value of a field within the deployment database is (the inner square brackets indicate optional sections):

attribute_name = [ddb field [related_table [related_pkey] related_field]]

where

• field is a field within the DeploymentData table (or CTDData, depending on wether the toolbox.mode is timeSeries or profile), the value of which is to be used as the attribute value (unless related_table and related_field are specified).
• related_table is the name of a table to which the field should be considered a foreign key.
• related_pkey is the name of the related_table primary key. If omitted, it is assumed to be the same as field.
• related_field is the name of the field within the related_table, the value of which is to be used as the attribute value.

A couple of examples in timeSeries mode:

1. For the attribute definition:

local_time_zone = [ddb TimeZone]

the value will be translated into a query to the deployment database of the form:

select TimeZone from DeploymentData 
where DeploymentID = dataset_deployment_id

2. For the attribute definition:

institution = [ddb PersonnelDownload Personnel StaffID Organisation]

the value will be translated into the following query:

select Organisation from Personnel where StaffID = 
(
  select PersonnelDownload from DeploymentData
  where DeploymentID = dataset_deployment_id
)

Matlab Expressions

You can set the attribute value to be the result of a matlab statement like so:

  attribute_name = [mat statement]

The following 'workspace' is available to these embedded statements:

• sample_data: the struct containing sample data, which is passed to this function.
• k: (only if the template is a data attribute template) the variable index passed to this function.

For example, for the attribute definition:

  quality_control_set = [mat readToolboxProperty('toolbox.qc_set')]

the attribute value will be the value of the matlab statment:

  readToolboxProperty('toolbox.qc_set')

Combinations

You can combine each method of defining values, as shown in the following examples:

• Tokens may not be repeated
• Tokens may not contain other tokens

qc_param_name = [mat sample_data.variables{k}.name]_QC

author = [ddb PersonnelDownload Personnel StaffID FirstName] \
         [ddb PersonnelDownload Personnel StaffID LastName]

title = [mat sample_data.field_trip_id]: [ddb Site Sites ResearchActivity]

platform = [mat ['Platform ' '[ddb Site]']]

The use of square braces to enclose tokens imposes a minor limitation on the use of square braces in attribute values: when the attribute value, tokens and all, is taken as a literal string, the square braces must be balanced. For example, the following is an example of a valid (not necessarily realistic) attribute containing nested tokens and literal braces:

  title = [mat ['abc' '[ddb Site]' 'def'](/aodn/imos-toolbox/wiki/mat-['abc'-'[ddb-Site]'-'def')]

This will evaluate (assuming that the Site field in the deployment database is 'MAI') to '[abcMAIdef]'. Using the same example, if the closing brace at the end had been omitted, the parser would raise an error, as the braces would not be balanced.