File MIES_AnalysisFunctionHelpers.ipf

AFH Helper functions for analysis function writers

Additionally the following functions might be useful

Function	Return value
GetADCListFromConfig()	Free wave with all active AD channels as entries
GetDACListFromConfig()	Free wave with all active DA channels as entries
GetLBNumericalValues()	Wave reference to the labnotebook (numerical version)
GetLBTextualValues()	Wave reference to the labnotebook (textual version)
GetLastSetting()	Last documented value for headstages of a specific setting in the labnotebook for a given sweep number.
GetLastSweepWithSetting()	Last documented numerical value for headstages of a specific setting in the labnotebook and the sweep number it was set last.
GetLastSweepWithSettingText()	Last documented textual value for headstages of a specific setting in the labnotebook and the sweep number it was set last.
ED_AddEntryToLabnotebook()	Add a user entry to the numerical/textual labnotebook

Functions

variable AFH_GetHeadstageFromADC(string device, variable AD)

Return the headstage the AD channel is assigned to.

Parameters:

• device – device

• AD – AD channel in the range [0,8[ or [0,16[ depending on the hardware

Returns:

headstage or NaN (for non-associated channels)

variable AFH_GetHeadstageFromDAC(string device, variable DA)

Return the headstage the DA channel is assigned to.

Parameters:

• device – device

• DA – DA channel in the range [0,4[ or [0,8[ depending on the hardware

Returns:

headstage or NaN (for non-associated channels)

variable AFH_GetADCFromHeadstage(string device, variable headstage)

Return the AD channel assigned to the headstage.

Parameters:

• device – device

• headstage – headstage in the range [0,8[

Returns:

AD channel or NaN (for non-associated channels)

variable AFH_GetDACFromHeadstage(string device, variable headstage)

Return the DA channel assigned to the headstage.

Parameters:

• device – device

• headstage – headstage in the range [0,8[

Returns:

DA channel or NaN (for non-associated channels)

variable AFH_GetDAQDataColumn(wave DAQConfigWave, variable channelNumber, variable channelType)

Return the column index into DAQDataWave for the given channel/type combination.

Parameters:

• DAQConfigWave – DAQ configuration wave, most users need to call GetDAQConfigWave(device) to get that wave.

• channelNumber – hardware channel number

• channelType – channel type, one of XopChannelConstants

wave AFH_GetChannelUnits(wave DAQConfigWave)

Return all channel units as free text wave.

Parameters:

DAQConfigWave – DAQ configuration wave, most users need to call GetDAQConfigWave(device) to get that wave.

string AFH_GetChannelUnit(wave DAQConfigWave, variable channelNumber, variable channelType)

Return the channel unit.

Parameters:

• DAQConfigWave – DAQ configuration wave, most users need to call GetDAQConfigWave(device) to get that wave.

• channelNumber – hardware channel number

• channelType – channel type, one of XopChannelConstants

variable AFH_GetLastSweepAcquired(string device)

Return the sweep number of the last acquired sweep.

Returns:

a non-negative integer sweep number or NaN if there is no data

wave AFH_GetSweeps(string device)

Return a numeric wave with all acquired sweep numbers, $”” if there is none.

wave AFH_GetLastSweepWaveAcquired(string device)

Return the sweep wave of the last acquired sweep.

Returns:

an existing sweep wave or an invalid wave reference if there is no data

string AFH_GetStimSetName(string device, variable chanNo, variable channelType)

Return the stimset for the given channel.

Parameters:

• device – device

• chanNo – channel number (0-based)

• channelType – one of the type constants from ChannelTypeAndControlConstants

Returns:

an existing stimulus set name for a DA channel

string AFH_GetStimSetNameForHeadstage(string device, variable headstage)

Convenience wrapper for AFH_GetStimSetName.

static wave AFH_GetSweepsFromSameRACycleNC(wave numericalValues, variable sweepNo)

Return a free wave with all sweep numbers (in ascending order) which belong to the same RA cycle. Uncached version, general users should prefer AFH_GetSweepsFromSameRACycle().

Return an invalid wave reference if not all required labnotebook entries are available

wave AFH_GetSweepsFromSameRACycle(wave numericalValues, variable sweepNo)

Return a free wave with all sweep numbers (in ascending order) which belong to the same RA cycle.

Return an invalid wave reference if not all required labnotebook entries are available

wave AFH_GetSweepsFromSameSCI(wave numericalValues, variable sweepNo, variable headstage)

Return a free wave with all sweep numbers (in ascending order) which belong to the same stimset cycle.

Return an invalid wave reference if not all required labnotebook entries are available

static wave AFH_GetSweepsFromSameSCINC(wave numericalValues, variable sweepNo, variable headstage)

Return a free wave with all sweep numbers (in ascending order) which belong to the same stimset cycle id. Uncached version, general users should prefer AFH_GetSweepsFromSameSCI().

Return an invalid wave reference if not all required labnotebook entries are available

wave AFH_ExtractOneDimDataFromSweep(string device, wave sweep, variable headstageOrChannelNum, variable channelType, wave config = defaultValue)

Return a free 1D wave from the given sweep.

Extract the AD channel data from headstage 1:

variable sweepNo = 5
WAVE sweep = GetSweepWave(device, sweepNo)
variable headstage = 1
WAVE data = AFH_ExtractOneDimDataFromSweep(device, sweep, headstage, XOP_CHANNEL_TYPE_ADC)

Extract the TTL channel 1:

variable sweepNo = 6
WAVE sweep = GetSweepWave(device, sweepNo)
variable ttlChannel = 1
WAVE data = AFH_ExtractOneDimDataFromSweep(device, sweep, ttlChannel, XOP_CHANNEL_TYPE_TTL)

Parameters:

• device – device

• sweep – sweep wave

• headstageOrChannelNum – headstage [0, NUM_HEADSTAGES[ or channel number for TTL channels [0, NUM_DA_TTL_CHANNELS]

• channelType – One of XopChannelConstants

• config – [optional, defaults to config wave of the sweep returned by GetConfigWave()] config wave

string AFH_GetAnalysisFunctions(variable versionBitMask, variable includeUserFunctions = defaultValue)

Get list of possible analysis functions.

Parameters:

• versionBitMask – bitmask of different analysis function versions which should be returned, one of AnalysisFunctionVersions

• includeUserFunctions – include analysis functions defined in “UserAnalysisFunctions.ipf”

string AFH_GetListOfAnalysisParams(string func, variable mode)

Return the list of required/optional analysis function parameters, possibly including the type, as specified by the function $func_GetParams

Parameters:

• func – Analysis function V3 which must be valid and existing

• mode – Bit mask values from GetListOfParamsModeFlags

string AFH_GetHelpForAnalysisParameter(string func, string name)

Get help string from optional $func_GetHelp

Parameters:

• func – Analysis function V3

• name – Parameter name

string AFH_GetListOfAnalysisParamNames(string params)

Return a semicolon separated list of user parameters.

Parameters:

params – serialized parameters, usually just AnalysisFunction_V3.params

variable AFH_IsParameterPresent(string name, string params)

Check if the given analysis parameter is present.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

Returns:

one if present, zero otherwise

string AFH_GetAnalysisParamType(string name, string params, variable typeCheck = defaultValue, string expectedType = defaultValue)

Return the type of the user parameter.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

• typeCheck – [optional, defaults to true] Check with an assertion that the readout type is one of ANALYSIS_FUNCTION_PARAMS_TYPES

• expectedType – [optional, defaults to nothing] Expected type, one of ANALYSIS_FUNCTION_PARAMS_TYPES, aborts if the type does not match. Implies typeCheck = true.

Returns:

one of AnalysisFunctionParameterTypes or an empty string

variable AFH_GetAnalysisParamNumerical(string name, string params, variable defValue = defaultValue)

Return a numerical user parameter.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

• defValue – [optional, defaults to NaN] return this value if the parameter could not be found

string AFH_GetAnalysisParamTextual(string name, string params, string defValue = defaultValue, variable percentDecoded = defaultValue)

Return a textual user parameter.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

• defValue – [optional, defaults to an empty string] return this value if the parameter could not be found

• percentDecoded – [optional, defaults to true] if the return value should be percent decoded or not.

wave AFH_GetAnalysisParamWave(string name, string params, wave defValue = defaultValue)

Return a numerical wave user parameter.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

• defValue – [optional, defaults to an invalid wave ref] return this value if the parameter could not be found

Returns:

wave reference to free numeric wave, or invalid wave ref in case the parameter could not be found.

wave AFH_GetAnalysisParamTextWave(string name, string params, WaveText defValue = defaultValue, variable percentDecoded = defaultValue)

Return a textual wave user parameter.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

• defValue – [optional, defaults to an invalid wave ref] return this value if the parameter could not be found

• percentDecoded – [optional, defaults to true] if the return value should be percent decoded or not.

Returns:

wave reference to free text wave, or invalid wave ref in case the parameter could not be found.

variable AFH_IsValidAnalysisParameter(string name)

Check if the given name is a valid user parameter name.

variable AFH_IsValidAnalysisParamType(string type)

Check if the given type is a valid user parameter type.

string AFH_GetAnalysisParameter(string name, string params, string expectedType = defaultValue)

Return an user parameter’s value as string.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

• expectedType – [optional, defaults to nothing] Expected type, one of ANALYSIS_FUNCTION_PARAMS_TYPES, aborts if the type does not match.

string AFH_RemoveAnalysisParameter(string name, string params)

Delete the given user parameter name.

Parameters:

• name – parameter name

• params – serialized parameters, usually just AnalysisFunction_V3.params

Returns:

serialized parameters with name removed

string AFH_CheckAnalysisParameter(string genericFunc, CheckParametersStruct *s)

Check the analysis parameters.

The following checks are made:

• Valid and matching types

• Non-empty waves supplied

• All required parameters are present

• No additional parameters are present if some are required/optional

• Valid names

• Check function passes if present

Parameters:

• genericFunc – Name of an analysis V3 function

• s – struct CheckParametersStruct with additional info

Returns:

multiline error messages, an empty string on success

variable AFH_AddAnalysisParameter(string setName, string name, variable var = defaultValue, string str = defaultValue, wave wv = defaultValue)

Add an analysis function parameter to the given stimset.

This function adds the parameter to the WPT wave and checks that it is valid.

Exactly one of var/str/wv must be given.

Parameters:

• setName – stimset name

• name – name of the parameter

• var – [optional] numeric parameter

• str – [optional] string parameter

• wv – [optional] wave parameter can be numeric or text

variable AFH_AddAnalysisParameterToParams(string *params, string name, variable var = defaultValue, string str = defaultValue, wave wv = defaultValue)

Add an analysis parameter to the given params string.

Exactly one of var/str/wv must be given.

Parameters:

• params – [inout] stimset name

• name – [in] name of the parameter

• var – [in] [optional] numeric parameter

• str – [in] [optional] string parameter

• wv – [in] [optional] wave parameter can be numeric or text

string AFH_GetAnalysisParameterAsText(string name, string params)

Return a stringified version of the analysis parameter value.

Parameters:

• name – name of the parameter

• params – serialized parameters, usually just AnalysisFunction_V3.params

variable AFH_GetHeadstageFromActiveADC(WaveOrNull statusADC, variable activeADCount)

Return the headstage from the given active AD count.

Parameters:

• statusADC – channel status as returned by GetLastSetting()

• activeADCount – running number of active ADC’s, starting at zero

Returns:

headstage in the range [0, NUM_HEADSTAGES], or NaN if nothing could be found

wave AFH_GetConfigWave(string device, wave sweepWave)

returns the correct config wave depending on the fact if sweepwave is either a scaledDataWave from a currently running acquisition or sweep wave from a finished acquisition

variable AFH_GetFifoInStimsetTime(string device, AnalysisFunction_V3 *s)

Some analysis function like PSQ_Ramp and PSQ_EvaluateBaselineChunks need the current acquisition time within the stimset (where the fifo is currently). This function wraps this calculation and returns the time in ms. The stimset begin is the reference point and 0 ms on that time scale.

Parameters:

• device – device name

• s – analysis function structure V3

Returns:

point in time where the current fifo is within the stimset in ms

wave AFH_GetChannelFromSweepOrScaledWave(wave sweepOrScaled, variable channelIndex)

std::tuple<variable, variable> AFH_GetSampleIntervalsFromSweep(wave sweep, wave config)

Returns the DA and AD sample intervals of the given sweep. The sweep data input can be text sweep wave, 2D numeric sweep wave or waveRef sweep wave (including e.g. scaledDataWave)

std::tuple<WAVE, WAVE> AFH_GetRheobaseSweepsSCISweepQCSplitted(wave numericalValues, variable sweepNo, variable headstage, wave sweepsSCI, variable passedSetQC)

Only for PSQ_RHEOBASE, returns a wave with passing and failing sweep numbers for sweepQC with all sweep numbers of the same SCI range This is a workaround and uses a different approach as for other analysis functions.

Parameters:

• numericalValues – numerical LNB

• sweepNo – sweep number

• headstage – headstage number

• sweepsSCI – numerical wave with all sweep numbers from the SCI where sweepNo is part of, AFH_GetSweepsFromSameSCI

• passedSetQC – flag that indicates if for this sweepNo the setQC passed, GetLastSettingIndepSCI for PSQ_FMT_LBN_SET_PASS

Return values:

• passingSweeps – numerical wave containing the sweep numbers of the sweeps from this SCI that passed the sweepQC

• failingSweeps – numerical wave containing the sweep numbers of the sweeps from this SCI that failed the sweepQC

variable AFH_LastSweepInSet(string device, variable sweepNo, variable headstage, variable eventType)

Return 1 if we are currently acquiring the last sweep in the stimulus set, 0 if not and NaN if it is not possible to determine.

variable AFH_GetNextSweepSetCount(wave numericalValues, variable sweepNo, variable headstage)

Return the set count of the next sweep.

No checking is done on the number of sweeps in the stimulus set