APar

From STX Wiki
Jump to navigation Jump to search

APar : CObj

The APar class implements a parameter interface for the DataSet. An alternative to this class is the ADesc class and its derivatives.

APar Static Functions

The following static functions are implemented:

LoadData

Load existing parameter data.

Usage:

APar LoadData aset ; aseg ; method ; [ xunit [ xuref ]] | NO ; [ yunit [ yuref ]] | NO [; channel ; id ]

Parameters:
aset
The audio set reference or position.
aseg
The audio segment ID.
method
The name of the parameter method (as displayed in the Detail view).
xunit
The unit for the x-scale data. The following keywords are supported:
no, off or false Do not load the x-scale data.
<empty> Load the x-scale data without unit conversion.
unit Load the x-scale data and convert to the selected unit.
yunit
The unit for the y-scale data. The following keywords are supported:
no, off or false Do not load the y-scale data.
<empty> Load the y-scale data without unit conversion.
unit Load the y-scale data and convert to the selected unit.
channel
Passed to the Load command.
id
Passed to the Load command.
Result:

An empty string if load fails or the following (depending on the xunit and yunit arguments).

[ xdata ] [ ydata ]

Load

Load parameter object of type 'method' from the audio segment 'aset ; aseg'.

Usage:

APar Load aset ; aseg ; method [; channel ; id ]

Parameters:
aset
The audio set reference or position.
aseg
The audio segment ID.
method
The name of the parameter method (as displayed in the Detail view).
channel
The channel number of the analysed signal. If specified, the channel attribute CH is included in the parameter selection.
id
The id of the analysed signal. If specified, the id attribute ID is included in the parameter selection.
Result:

An APar instance or empty string

GetAllMethods

Retrieve all parameter extraction methods defined in the STx INI file.

Usage:

APar GetAllMethods

Result:

A semi-colon separated list of methods in the format:

method1 parameterName1 ; method2 parameterName2 ; ...

GetMethodInfo

Retrieve all information about a specific method.

Usage:

APar GetMethodInfo method

Parameters:
method
The method name (as returned by GetAllMethods).
Result:

Information about the method in the following format:

method ; param ; ny ; text ; nx ; xtype ; ytype ; unit

Otherwise an empty string is returned.

GetParameterInfo

Retrieve all information about a parameter type. E.g a fundamental frequency parameter.

Usage:

APar GetParameterInfo param

Result:

If successful, the all information pertaining to the parameter param is returned in the following format:

name ; nx ; text ; xtype ; ytype ; unit

Otherwise an empty string is returned.

Examples:

The call

APar GetParameterInfo F0

returns the string

F0; 1; Fundametal Frequency; time; frequency;

GetTypeInfo

Retrieve information about a scale type.

Usage:

APar GetTypeInfo type

Parameters:
type
A valid unit type (One of the entries returned by GetAllUnitTypes).
Result:

A simple table of defined units or empty string if type does not exist. Each table entry has the following format:

unit ; unitname ; ref ; min ; max

GetAllUnits

Get a list of all units (shortname) of a scale type.

Usage:

APar GetAllUnits type

Parameters:
type
A valid unit type (One of the entries returned by GetAllUnitTypes).
Result:

A blank separated list of the units of the requested type.

GetAllUnitTypes

Retrieve all unit types currently supported. One of these types can then be passed to the functions GetTypeInfo or GetAllUnits.

Usage:

APar GetAllUnitTypes

Result:

A simple table with one entry per unit type.

APar Class Members

The APar class implements the following public member functions. See CObj Member Functions for a list of functions implemented in the parent class.

construct

Initialise the instance. If posref is specified, initialize the instance with parameter data from the element at the position reference (see Load for more details). If table is specified, initialize the instance with a table containing parameters (see NEW for more details).

Usage:

inst construct [ posref | table ]

Parameters:
posref
An IRef to an APar element in the DataSet.
table
The table containing the parameters.
Result:

0 if successful, 1 otherwise.

destruct

Destroy the instance.

getScale

Get the scale domain.

Usage:

inst getScale axis order

Parameters:
axis
The name of the axis (X|Y)
order
The axis order or parameter number.
Result:

The domain of selected scale or an empty string.

getXData

Get x scale data vector.

Usage:

inst getXData order ; length ; unit uref [; table field ]

Parameters:
order
The x-scale order (1 or 2). The default value is 1.
length
The number of values (0|* = original length)
unit, uref
The output unit and reference value. The default unit depends on the parameter type. For time parameters the default unit is seconds (s) whilst for frequency parameters, the default unit is Hz.
table, field
The output table and field (a new table is created if not specified).
Result:

The x-data vector (parameter table with one row) or empty string.

getYData

Get the y scale data vector(s).

Usage:

inst getYData index ; length ; unit uref [; table field ; mvsym ]

Parameters:
index
The index of the y-data to be loaded (0 for all).
length
The number of values (0|* = original length)
unit, uref
The output unit and reference value. If no unit is specified, the unit specified with the last setYData is used.
table, field
The output table and (first) field (a new table is created if not specified).
mvsym
The missing value symbol.
Result:

The y-data vector/s (parameter table) or empty string.

load

Load data from an existing APar in the DataSet into this instance.

Usage:

inst load aparref

Parameters:
aparref
An IRef to an APar in the DataSet.
Result:

An empty string on success or an error message on failure.

new

Initializes a new parameter instance with values from the table. The table must have the following format:

$table[0] asegposref ; channel
$table[1] method ; framelength ; frameshift ; framecount ; methodparam
$table[2] axes order ; unit [ref] ; datavalue|datatable [datafield]
$table[3] ....
Usage:

inst new table

Parameters:
table
The parameter table.
Result:

An empty string on success and an error message on failure.

save

Save local APar file in the DataSet. If a table is specified a new parameter is created by calling the function NEW table.

Usage:

inst save [ replace table edit save ]

Parameters:
replace
1 if the existing parameter should be replace, 0 otherwise.
table
The parameter table to save. See the member function new for details.
edit
Set the edit attribute to 1 or 0.
save
Set the save attribute to 1 or 0.
Result:

An empty string on success or an error message on failure.

setXData

Set the x scale data.

Usage:

inst setXData order ; unit [ uref ]

Parameters:
order
The x-scale order (1|2).
unit
The x-scale unit.
uref
The unit reference value.
Result:

An empty string on success or an error message on failure.

setYData

Set the y scale data.

Usage:

inst setYData order ; unit [ uref ] ; table [ field ]

inst setYData order ; unit [ uref ] ; value

Parameters:
order
The y-scale order (>=1) or order range.
unit
The y-scale unit.
uref
The unit reference value.
table
The data table containing values to set (one value per order).
field
The first table field containing Y vectors.
value
The value to set the y data to or a range of values if an order range was specified.
Result:

An empty string on success or an error message on failure.

getXScale

The definitions of the independent scale x with the specified order.

Usage:

inst getXScale [ order]

Parameters:
order
The order (1 ... ny). The default order is 1.
Result:

'domain ; unit ; uref' or an empty string.

getYScale

The definitions of the independent scale y with the specified order.

Usage:

inst getYScale [ order]

Parameters:
order
The order (1 ... ny). The default order is 1.
Result:

'domain ; unit ; uref' or an empty string.