Programming Reference:Accessing Parameters and States - Revision history

Mellinger: /* State(Name) */

2022-08-12T14:11:50Z

State(Name)

← Older revision		Revision as of 14:11, 12 August 2022
Line 75:		Line 75:
	Examples:		Examples:

	short currentStateOfAffairs = State( "OfAffairs" );		short currentStateOfAffairs = State("OfAffairs");
	State( "OfAffairs" ) = nextStateOfAffairs;		State("OfAffairs") = nextStateOfAffairs;

			If you use the above syntax, the state's value will be set for the entire data block, or read from the first sample position of the data block. In order to address other sample positions in the current data block, use another pair of parentheses to enclose the sample position.

			Example: find whether a state assumes a certain value during the current block

			bool found = false;
			for(int i = 0; i < Statevector->Size() - 1; ++i)
			if(State("OfAffairs")(i) == 1)
			found = true;

	===<tt>OptionalState(Name[, Default Value])</tt>===		===<tt>OptionalState(Name[, Default Value])</tt>===

Mellinger: /* `RelativeFreq( SignalProperties )` */

2011-04-30T12:16:06Z

<tt>RelativeFreq( SignalProperties )</tt>

← Older revision		Revision as of 12:16, 30 April 2011
Line 55:		Line 55:

	====<tt>RelativeFreq( SignalProperties )</tt>====		====<tt>RelativeFreq( SignalProperties )</tt>====
	will return a parameter's value in terms of a signal's effective sampling rate when ~~its~~ SignalProperties are specified as an argument. When a unit other than a frequency unit is present in the parameter value, an error is reported.		will return a parameter's value in terms of a signal's effective sampling rate when the signal's SignalProperties are specified as an argument. When a unit other than a frequency unit is present in the parameter value, an error is reported.

	====<tt>SystemRelativeFreq()</tt>====		====<tt>SystemRelativeFreq()</tt>====
	will return a parameter's value in terms of the system sampling rate. When a unit other than a frequency unit is present in the parameter value, an error is reported.		will return a parameter's value in terms of the system sampling rate. When a unit other than a frequency unit is present in the parameter value, an error is reported.

Mellinger: /* High-level Access */

2011-04-30T12:10:49Z

High-level Access

← Older revision		Revision as of 12:10, 30 April 2011
Line 42:		Line 42:
	This symbol behaves like the symbol <tt>Parameter()</tt> but will not report an error if the parameter does not exist. Instead, it will return the default value given in its first argument. Assignments to this symbol are not possible.		This symbol behaves like the symbol <tt>Parameter()</tt> but will not report an error if the parameter does not exist. Instead, it will return the default value given in its first argument. Assignments to this symbol are not possible.

	===~~Unit Parsing~~ Functions===		===Conversion Functions===
	may be ~~appended when accessing~~ a ~~parameter:~~		These convert parameter values between units. In BCI2000, values representing time may be given without units--then, the numeric value represents time in terms of a Sample Block's duration. Alternatively, these values may be given with a time unit such as ''ms''. Similarly, frequencies may be given in terms of the system's sampling rate, or in Hertz when appended with ''Hz''. Voltage values may be appended with ''V'', ''muV'' or similar; when no unit is specified, the numeric value is assumed to be in Microvolts.
	~~====<tt>AsSeconds</tt>~~, ~~<tt>AsMilliseconds</tt>====~~
	~~====<tt>AsHertz</tt>====~~
	~~====<tt>AsVolts</tt>~~, ~~<tt>AsMicrovolts</tt>====~~
	~~These functions return~~ the ~~parameter~~'s value~~, parsing out physical units as indicated by function names~~.

	~~Example:~~		====<tt>InBlocks(), InSampleBlocks()</tt>====
	~~double amplitude~~ = ~~Parameter~~( ~~"Amplitude"~~ )~~.AsMicrovolts~~();		Gives a parameter's value as the corresponding number of sample blocks. When a unit other than a time unit is specified in the parameter value, an error is reported.
	~~will return <math>10^{-5}~~</~~math~~> ~~when the~~ parameter's value ~~is "10muV" or "1e-5"~~. When ~~an inconsistent~~ unit is ~~present (such as~~ in ~~"10ms")~~, an error ~~will be~~ reported.		====<tt>InSeconds(), InMilliseconds()</tt>====
			Provides a parameter's value in seconds, or milliseconds, respectively. When the parameter contains a unit other than a time unit, an error is reported.
	~~===Conversion Functions===~~
	~~In addition to unit parsing functions, there are conversion functions available as well:~~
	====<tt>~~InBlocks~~()</tt>====
	~~will return~~ a parameter's value in ~~terms of system sample blocks when~~ the ~~value is given in seconds (with~~ a ~~trailing "s"~~ unit~~). A value without~~ a unit is ~~considered to be expressed directly in sample blocks~~.

	Example:		Example:
Line 62:		Line 54:
	will return 5 when the sampling rate is 250Hz, sample block size is 10, and the value of the StimulusDuration parameter is "200ms".		will return 5 when the sampling rate is 250Hz, sample block size is 10, and the value of the StimulusDuration parameter is "200ms".

	====<tt>RelativeFreq( [SignalProperties] )</tt>====		====<tt>RelativeFreq( SignalProperties )</tt>====
	will return a parameter's value ~~in terms of the system sampling rate when no SignalProperties object is given, and~~ in terms of a signal's effective sampling rate when its SignalProperties are specified as an argument.		will return a parameter's value in terms of a signal's effective sampling rate when its SignalProperties are specified as an argument. When a unit other than a frequency unit is present in the parameter value, an error is reported.
			====<tt>SystemRelativeFreq()</tt>====
			will return a parameter's value in terms of the system sampling rate. When a unit other than a frequency unit is present in the parameter value, an error is reported.
			====<tt>InHertz()</tt>====
			returns a parameter's value in Hertz. When the parameter's value is a plain number, it is taken to represent multiples of the system sampling rate.

	Example:		Example:
	double hpCorner = Parameter( "HPCorner" ).RelativeFreq( Input );		double hpCorner = Parameter( "HPCorner" ).RelativeFreq( Input );
	will return 0.5 when the input signal's effective sampling rate is 250Hz, and the parameter's value is "125Hz".		will return 0.5 when the input signal's effective sampling rate is 250Hz, and the parameter's value is "125Hz".

			====<tt>InVolts(), inMicrovolts()</tt>====
			gives a parameter's value in units of Volts or Microvolts, respectively. A plain number is taken to represent Microvolts.

	===<tt>State(Name)</tt>===		===<tt>State(Name)</tt>===

Mellinger: /* `Parameter(Name)[(Index 1[, Index 2])` */

2011-04-28T14:42:48Z

<tt>Parameter(Name)[(Index 1[, Index 2])</tt>

← Older revision		Revision as of 14:42, 28 April 2011
Line 30:		Line 30:
	===<tt>Parameter(Name)[(Index 1[, Index 2])</tt> ===		===<tt>Parameter(Name)[(Index 1[, Index 2])</tt> ===

	This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, an exception is thrown.		This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into [[Programming_Reference:Errors_and_Warnings\|<tt>bcierr</tt>]]. If the specified indices do not exist, an exception is thrown.

	Examples:		Examples:

Mellinger: /* `Parameter(Name)[(Index 1[, Index 2])` */

2011-04-28T14:40:43Z

<tt>Parameter(Name)[(Index 1[, Index 2])</tt>

← Older revision		Revision as of 14:40, 28 April 2011
Line 30:		Line 30:
	===<tt>Parameter(Name)[(Index 1[, Index 2])</tt> ===		===<tt>Parameter(Name)[(Index 1[, Index 2])</tt> ===

	This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, ~~no error~~ is ~~reported. In both cases, on read access, the string constant <tt>"0"</tt> resp. the number 0 is returned~~.		This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, an exception is thrown.

	Examples:		Examples:
Line 36:		Line 36:
	int myValue = Parameter( "MyParam" );		int myValue = Parameter( "MyParam" );
	string myOtherValue = Parameter( "MyOtherParam" );		string myOtherValue = Parameter( "MyOtherParam" );
	Parameter( "My3rdParam" )( 2, 3 ) = my3rdValue;		Parameter( "My3rdParam" )( 2, 3 ) = my3rdValue;

	===<tt>OptionalParameter(Name[, Default Value])(Index 1[, Index 2])</tt>===		===<tt>OptionalParameter(Name[, Default Value])(Index 1[, Index 2])</tt>===

Mellinger: /* Low Level Access */

2011-04-28T14:39:43Z

Low Level Access

← Older revision		Revision as of 14:39, 28 April 2011
Line 5:		Line 5:
	==Low Level Access==		==Low Level Access==
	is provided by the following symbols:		is provided by the following symbols:
	<tt>Parameters</tt> syntactically behaves like a <tt>ParamList</tt>,		<tt>Parameters</tt> syntactically behaves like a [[Programming_Reference:Parameters#ParamList_Class\|<tt>ParamList</tt>]],
	<tt>States</tt> behaves like a <tt>StateList</tt>,		<tt>States</tt> behaves like a [[Programming_Reference:States#StateList_Class\|<tt>StateList</tt>]],
	and <tt>Statevector</tt> behaves like a <tt>StateVector</tt>.		and <tt>Statevector</tt> behaves like a [[Programming_Reference:States#StateVector_Class\|<tt>StateVector</tt>]].

	As an example,		As an example,
Line 14:		Line 14:
	Param* param = Parameters->GetParamPtr( "MyParameter" );		Param* param = Parameters->GetParamPtr( "MyParameter" );
	if( param )		if( param )
	myParameterValue = atof( param->GetValue() );		myParameterValue = ::atof( param->GetValue() );
	else		else
	bcierr << "Could not access \"MyParameter\"" << endl;		bcierr << "Could not access \"MyParameter\"" << endl;

Mellinger: /* See also */

2011-04-28T14:20:34Z

Mellinger: /* High-level Access */

2011-04-28T14:17:00Z

High-level Access

← Older revision		Revision as of 14:17, 28 April 2011
Line 28:		Line 28:
	is possible through a number of symbols which offer built-in checking and error reporting:		is possible through a number of symbols which offer built-in checking and error reporting:

	*<tt>Parameter(Name)[(Index 1[, Index 2])</tt>		===<tt>Parameter(Name)[(Index 1[, Index 2])</tt> ===

	This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, no error is reported. In both cases, on read access, the string constant <tt>"0"</tt> resp. the number 0 is returned.		This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, no error is reported. In both cases, on read access, the string constant <tt>"0"</tt> resp. the number 0 is returned.
Line 38:		Line 38:
	Parameter( "My3rdParam" )( 2, 3 ) = my3rdValue;		Parameter( "My3rdParam" )( 2, 3 ) = my3rdValue;

	*<tt>OptionalParameter(Name[, Default Value])(Index 1[, Index 2])</tt>		===<tt>OptionalParameter(Name[, Default Value])(Index 1[, Index 2])</tt>===

	This symbol behaves like the symbol <tt>Parameter()</tt> but will not report an error if the parameter does not exist. Instead, it will return the default value given in its first argument. Assignments to this symbol are not possible.		This symbol behaves like the symbol <tt>Parameter()</tt> but will not report an error if the parameter does not exist. Instead, it will return the default value given in its first argument. Assignments to this symbol are not possible.

	*The following ''Unit Parsing Functions'' may be appended when accessing a parameter:		===Unit Parsing Functions===
	;<tt>AsSeconds</tt>, <tt>AsMilliseconds</tt>, <tt>AsHertz</tt>, <tt>AsVolts</tt>, <tt>AsMicrovolts</tt>		may be appended when accessing a parameter:
	;;These functions return the parameter's value, parsing out physical units as indicated by function names.		====<tt>AsSeconds</tt>, <tt>AsMilliseconds</tt>====
			====<tt>AsHertz</tt>====
			====<tt>AsVolts</tt>, <tt>AsMicrovolts</tt>====
			These functions return the parameter's value, parsing out physical units as indicated by function names.

	Example:		Example:
Line 50:		Line 53:
	will return <math>10^{-5}</math> when the parameter's value is "10muV" or "1e-5". When an inconsistent unit is present (such as in "10ms"), an error will be reported.		will return <math>10^{-5}</math> when the parameter's value is "10muV" or "1e-5". When an inconsistent unit is present (such as in "10ms"), an error will be reported.

	*In addition to unit parsing functions, there are conversion functions available as well:		===Conversion Functions===
	;<tt>InBlocks()</tt>		In addition to unit parsing functions, there are conversion functions available as well:
	;;will return a parameter's value in terms of system sample blocks when the value is given in seconds (with a trailing "s" unit). A value without a unit is considered to be expressed directly in sample blocks.		====<tt>InBlocks()</tt>====
			will return a parameter's value in terms of system sample blocks when the value is given in seconds (with a trailing "s" unit). A value without a unit is considered to be expressed directly in sample blocks.

	Example:		Example:
Line 58:		Line 62:
	will return 5 when the sampling rate is 250Hz, sample block size is 10, and the value of the StimulusDuration parameter is "200ms".		will return 5 when the sampling rate is 250Hz, sample block size is 10, and the value of the StimulusDuration parameter is "200ms".

	;<tt>RelativeFreq( [SignalProperties] )</tt>		====<tt>RelativeFreq( [SignalProperties] )</tt>====
	;;will return a parameter's value in terms of the system sampling rate when no SignalProperties object is given, and in terms of a signal's effective sampling rate when its SignalProperties are specified as an argument.		will return a parameter's value in terms of the system sampling rate when no SignalProperties object is given, and in terms of a signal's effective sampling rate when its SignalProperties are specified as an argument.

	Example:		Example:
Line 65:		Line 69:
	will return 0.5 when the input signal's effective sampling rate is 250Hz, and the parameter's value is "125Hz".		will return 0.5 when the input signal's effective sampling rate is 250Hz, and the parameter's value is "125Hz".

	*<tt>State(Name)</tt>		===<tt>State(Name)</tt>===

	This symbol allows for reading a state's value from the state vector and setting a state's value in the state vector. Trying to access a state that is not accessible will result in an error reported via <tt>bcierr</tt>.		This symbol allows for reading a state's value from the state vector and setting a state's value in the state vector. Trying to access a state that is not accessible will result in an error reported via <tt>bcierr</tt>.
Line 74:		Line 78:
	State( "OfAffairs" ) = nextStateOfAffairs;		State( "OfAffairs" ) = nextStateOfAffairs;

	*<tt>OptionalState(Name[, Default Value])</tt>		===<tt>OptionalState(Name[, Default Value])</tt>===

	Analagous to <tt>OptionalParameter()</tt>, this symbol does not report an error if the specified state does not exist but returns the given default value. Assignments to this symbol are not possible.		Analagous to <tt>OptionalParameter()</tt>, this symbol does not report an error if the specified state does not exist but returns the given default value. Assignments to this symbol are not possible.

	*Converters to and from numeric types		===Converters to and from numeric types===

	State values may be of numeric types other than <tt>unsigned</tt>. For conversion, functions are provided as in the following examples:		State values may be of numeric types other than <tt>unsigned</tt>. For conversion, functions are provided as in the following examples:
	float f = State( "MyFloatState" ).AsFloat();		float f = State( "MyFloatState" ).AsFloat();

Mellinger at 14:11, 28 April 2011

2011-04-28T14:11:53Z

New page

On this page, we discuss how to access BCI2000 parameters from filter components that derive from <tt>GenericFilter</tt>, or from extension components deriving from the <tt>EnvironmentExtension</tt> class.

There are two kinds of access to parameters and states: High-level access allows to easily manipulate parameter and state values, and is appropriate most of the time. Low-level access allows to directly manipulate the data structures lying beneath the surface of parameter and state values. This might be necessary to, e.g., iterate over all parameters or states present.

==Low Level Access==
is provided by the following symbols:
*<tt>Parameters</tt> syntactically behaves like a <tt>ParamList*</tt>,
*<tt>States</tt> behaves like a <tt>StateList*</tt>,
*and <tt>Statevector</tt> behaves like a <tt>StateVector*</tt>.

As an example,

float myParameterValue = 0.0;
Param* param = Parameters->GetParamPtr( "MyParameter" );
if( param )
myParameterValue = atof( param->GetValue() );
else
bcierr << "Could not access \"MyParameter\"" << endl;

Unlike true pointers, these symbols cannot be assigned any values, cannot be assigned to variables, or have other manipulating operators applied. For example, the lines

delete Parameters;
Parameters = new ParamList;

will all result in compiler errors.

==High-level Access==
is possible through a number of symbols which offer built-in checking and error reporting:

*<tt>Parameter(Name)[(Index 1[, Index 2])</tt>

This symbol stands for the value of the named parameter. Indices may be given in numerical or textual form; if omitted, they default to 0. The type of the symbol <tt>Parameter()</tt> may be numerical or a string type, depending on its use. (If the compiler complains about ambiguities, use explicit typecasts.) If a parameter with the given name does not exist, an error message is written into <tt>bcierr</tt>. If the specified indices do not exist, no error is reported. In both cases, on read access, the string constant <tt>"0"</tt> resp. the number 0 is returned.

Examples:

int myValue = Parameter( "MyParam" );
string myOtherValue = Parameter( "MyOtherParam" );
Parameter( "My3rdParam" )( 2, 3 ) = my3rdValue;

*<tt>OptionalParameter(Name[, Default Value])(Index 1[, Index 2])</tt>

This symbol behaves like the symbol <tt>Parameter()</tt> but will not report an error if the parameter does not exist. Instead, it will return the default value given in its first argument. Assignments to this symbol are not possible.

*The following ''Unit Parsing Functions'' may be appended when accessing a parameter:
;<tt>AsSeconds</tt>, <tt>AsMilliseconds</tt>, <tt>AsHertz</tt>, <tt>AsVolts</tt>, <tt>AsMicrovolts</tt>
;;These functions return the parameter's value, parsing out physical units as indicated by function names.

Example:
double amplitude = Parameter( "Amplitude" ).AsMicrovolts();
will return <math>10^{-5}</math> when the parameter's value is "10muV" or "1e-5". When an inconsistent unit is present (such as in "10ms"), an error will be reported.

*In addition to unit parsing functions, there are conversion functions available as well:
;<tt>InBlocks()</tt>
;;will return a parameter's value in terms of system sample blocks when the value is given in seconds (with a trailing "s" unit). A value without a unit is considered to be expressed directly in sample blocks.

Example:
double stimulusDuration = Parameter( "StimulusDuration" ).InBlocks();
will return 5 when the sampling rate is 250Hz, sample block size is 10, and the value of the StimulusDuration parameter is "200ms".

;<tt>RelativeFreq( [SignalProperties] )</tt>
;;will return a parameter's value in terms of the system sampling rate when no SignalProperties object is given, and in terms of a signal's effective sampling rate when its SignalProperties are specified as an argument.

Example:
double hpCorner = Parameter( "HPCorner" ).RelativeFreq( Input );
will return 0.5 when the input signal's effective sampling rate is 250Hz, and the parameter's value is "125Hz".

*<tt>State(Name)</tt>

This symbol allows for reading a state's value from the state vector and setting a state's value in the state vector. Trying to access a state that is not accessible will result in an error reported via <tt>bcierr</tt>.

Examples:

short currentStateOfAffairs = State( "OfAffairs" );
State( "OfAffairs" ) = nextStateOfAffairs;

*<tt>OptionalState(Name[, Default Value])</tt>

Analagous to <tt>OptionalParameter()</tt>, this symbol does not report an error if the specified state does not exist but returns the given default value. Assignments to this symbol are not possible.

*Converters to and from numeric types

State values may be of numeric types other than <tt>unsigned</tt>. For conversion, functions are provided as in the following examples:
float f = State( "MyFloatState" ).AsFloat();
State( "MyFloatState" ).AsFloat() = 1.23;
int i = State( "MySignedState" ).AsSigned();
State( "MySignedState" ).AsSigned() = -3;
State( "MyUnsignedState" ).AsUnsigned() = 2;
Note that the <tt>AsUnsigned()</tt> converter function is provided for completeness only. When no conversion is given, state values are treated as unsigned as well.

==See also==
[[Programming Reference:Parameters]], [[Programming Reference:States]]

← Older revision		Revision as of 14:20, 28 April 2011
Line 93:		Line 93:
	==See also==		==See also==
	[[Programming Reference:Parameters]], [[Programming Reference:States]]		[[Programming Reference:Parameters]], [[Programming Reference:States]]

			[[Category:Framework API]] [[Category:Development]]

Programming Reference:Accessing Parameters and States - Revision history

Mellinger: /* State(Name) */

Mellinger: /* RelativeFreq( SignalProperties ) */

Mellinger: /* High-level Access */

Mellinger: /* Parameter(Name)[(Index 1[, Index 2]) */

Mellinger: /* Parameter(Name)[(Index 1[, Index 2]) */

Mellinger: /* Low Level Access */

Mellinger: /* See also */

Mellinger: /* High-level Access */

Mellinger at 14:11, 28 April 2011

Mellinger: /* `RelativeFreq( SignalProperties )` */

Mellinger: /* `Parameter(Name)[(Index 1[, Index 2])` */

Mellinger: /* `Parameter(Name)[(Index 1[, Index 2])` */