File MIES_SweepFormula_Helpers.ipf¶

SFH Sweep formula related helper code

Functions

variable SFH_StringChecker_Prototype(string str)¶

variable SFH_NumericChecker_Prototype(variable var)¶

variable SFH_GetArgumentAsNumeric(SF_ExecutionData *exd, string opShort, variable argNum, variable defValue = defaultValue, WaveOrNull allowedValues = defaultValue, SFH_NumericChecker_Prototype checkFunc = defaultValue, variable checkDefault = defaultValue)¶

Convenience helper function to get a numeric SweepFormula operation argument.

Given the operation fetchBeer(variable numBottles, [variable size]) one can fetch both parameters via:

opShort    = "fetchBeer"
numBottles = SFH_GetArgumentAsNumeric(jsonId, jsonPath, graph, opShort, 0)
size       = SFH_GetArgumentAsNumeric(jsonId, jsonPath, graph, opShort, 1, defValue = 0.5, allowedValues = {0.33, 0.5, 1.0})

Here numBottles is argument number 0 and mandatory as defValue is not present.

The second argument size is optional with 0.5 as default and also defines a list of valid values.

string SFH_GetArgumentAsText(SF_ExecutionData *exd, string opShort, variable argNum, string defValue = defaultValue, WaveTextOrNull allowedValues = defaultValue, SFH_StringChecker_Prototype checkFunc = defaultValue, variable checkDefault = defaultValue)¶

Convenience helper function to get a textual SweepFormula operation argument.

Given the operation getTrainTable(string date, [string type]) one can fetch both parameters via:

opShort = "getTrainTable"
date    = SFH_GetArgumentAsText(exd, opShort, 0)
type    = SFH_GetArgumentAsText(exd, opShort, 1, defValue = "steam train", allowedValues = {"steam train", "light rail"})

Here date is argument number 0 and mandatory as defValue is not present.

The second argument type is optional with steam train as default and a list of allowed values.

The text argument can be abbreviated as long as it is unique, the unabbreviated result is returned in all cases.

wave SFH_GetArgumentAsWave(SF_ExecutionData *exd, string opShort, variable argNum, string defOp = defaultValue, WaveOrNull defWave = defaultValue, variable singleResult = defaultValue, variable expectedMinorType = defaultValue, variable expectedMajorType = defaultValue, variable copy = defaultValue, string *wvNote = defaultValue, variable resolveSelect = defaultValue)¶

Convenience helper function to get a wave SweepFormula operation argument.

Given the operation countBirds(array birds, [birdTypes()]) one can fetch both parameters via:

opShort      = "countBirds"
WAVE/D birds = SFH_GetArgumentAsWave(jsonId, jsonPath, graph, opShort, 0, singleResult = 1)
WAVE/T types = SFH_GetArgumentAsWave(jsonId, jsonPath, graph, opShort, 1, defOp = "birdTypes()", singleResult = 1, expectedWaveType = IGOR_TYPE_TEXT_WAVE)

Here birds is argument number 0 and mandatory as defOp is not present. Passing singleResult == 1 already unpacks the outer wave reference wave container. It should always be passed if you only expect one wave to be returned.

The second argument birdTypes is optional, if not present the operation birdTypes() is called and its result returned. Alternatively defWave can be supplied which is then returned if the argument is not present.

Parameters:

exd – Execution data structure
opShort – Short name of the operation
argNum – Argument index
defOp – [optional, defaults to None] SF code to execute in case the argument is not present
defWave – [optional] wave to return in case the argument is not present and defOp is not supplied
singleResult – [optional, defaults to 0] Return the first wave of the dataset if it has only one entry
expectedMinorType – [optional, defaults to None] Expected minor wave type, possible values are from WaveType(wv, 0)
expectedMajorType – [optional, defaults to None] Expected major wave type, possible values are from WaveType(wv, 1)
copy – [optional, defaults to 0] If the returned data should be safe for modification (true) or is only read (false)
wvNote – [out] [optional, defaults to None] Wave note of the dataset, useful for single result cases where you still need to query JSON wave note entries
resolveSelect – [optional, defaults to 0] If set then argument of the select type are automatically converted to sweep data, effectively the data() operation is applied As with data, if the argument is an array of selects, each sweep result gets concatenated to a wref wave

variable SFH_PushAssertDataFrame()¶

Push a new (blank) frame onto the SweepFormula assert-data LIFO stack, see GetSFAssertDataStack for the full picture.

Before pushing, if a frame is already active, its error-location message is rendered and frozen into its own LOCMSG field right now — this is the last moment at which the global, single-slot execution-position trackers (GetSweepFormulaJSONPathTracker / GetSweepFormulaBufferOffsetTracker) still reflect that frame’s position; the moment the nested formula execution we are pushing this frame for starts running, those trackers get overwritten with its position instead.

variable SFH_PopAssertDataFrame()¶

Pop the innermost frame off the SweepFormula assert-data LIFO stack once a nested formula execution (e.g. the internal formula run by an operation like ivscc_apfrequency, see SFO_OperationIVSCCApFrequencyPrepareVariables) has returned normally.

Deliberately does not release the popped frame’s JSONID/SRCLOCID: by the time a nested execution finishes normally, its own JSON ids have already been released by the ordinary executor success path (SFE_ExecuteFormula/SFE_ExecuteVariableAssignments); releasing them again here would double-release. If the nested execution instead aborts (SFH_ASSERT), this function is simply never reached for that frame — it is deliberately left on the stack, see GetSFAssertDataStack — and its ids are only ever cleaned up defensively, tolerant of already-released ids, by SFH_ResetAssertDataStack.

wave SFH_GetOutermostAssertDataFrame()¶

Return the outermost (bottom-of-stack, index 0) SF assert-data frame.

This is the only frame whose LINE/OFFSET describe a position in the real, on-screen SweepFormula notebook text (see SF_CalculateErrorLocationInNotebook) — any inner/nested frame’s LINE/OFFSET instead describe a position inside an operation’s own internally-generated formula string, which was never displayed in the notebook.

variable SFH_ResetAssertDataStack()¶

Defensively empty the SweepFormula assert-data LIFO stack, releasing every remaining frame’s JSONID/SRCLOCID.

Call this whenever SweepFormula output state is cleared for a fresh run (see SF_ClearSFOutputState) so that frames left behind by a previous aborted nested execution (see SFH_PopAssertDataFrame) never leak into, or get misread as belonging to, the next run. JSON_Release(…, ignoreErr=1) tolerates ids that are already invalid or already released, so this is safe to call unconditionally, whether or not the previous run actually aborted inside a nested call.

static string SFH_GetAssertLocationMessageForFrame(WaveText assertData)¶

Render the error-location message for a single SF assert-data frame.

Extracted from the former (single-frame) SFH_GetAssertLocationMessage so it can be applied either to the live, currently-executing frame (reading the global execution-position trackers, which are only ever valid for whatever is executing right now) or, via the frozen LOCMSG field written by SFH_PushAssertDataFrame, to a suspended outer frame.

Deliberately does not release SRCLOCID: unlike the original single-frame version, this can now run opportunistically during perfectly normal, non-aborting execution (via SFH_PushAssertDataFrame, to freeze an outer frame’s message before pushing a nested one on top of it), where the outer frame’s SRCLOCID is still needed afterward. Releasing it here would strand the outer frame with an invalid id the next time its message needs (re-)rendering. SRCLOCID release is instead the sole responsibility of SFH_GetAssertLocationMessage (the only call site guaranteed to run right before an actual Abort) and SFH_ResetAssertDataStack.

static string SFH_GetAssertLocationMessage()¶

Build the full, possibly multi-level, error-location message for the currently active SweepFormula assert-data stack, see GetSFAssertDataStack.

Walks the stack from the innermost (top, currently-failing) frame down to the outermost (bottom, the formula visible in the SF notebook), rendering each frame’s own location message (SFH_GetAssertLocationMessageForFrame) and joining more than one with a “Called from:” separator, so a failure inside a nested operation call (e.g. ivscc_apfrequency running its own internal formula, see SFO_OperationIVSCCApFrequencyPrepareVariables) reports both where inside that internal formula it failed and where in the user’s own notebook formula the nested call was made.

variable SFH_ASSERT(variable condition, string message, variable jsonId = defaultValue)¶

Assertion for sweep formula.

This assertion does not indicate a general programmer error but a sweep formula user error.

All programmer error checks must still use ASSERT().

UTF_NOINSTRUMENTATION

static string SFH_FormatSourceLocationError(string formula, variable loc)¶

variable SFH_FATAL_ERROR(string message, variable jsonId = defaultValue)¶: Fatal user error for sweep formula.

wave SFH_GetEmptyRange()¶

variable SFH_IsEmptyRange(wave range)¶

wave SFH_GetFullRange()¶

variable SFH_IsFullRange(wave range)¶

wave SFH_AsDataSet(wave data)¶

static variable SFH_ExtendIncompleteRanges(WaveRefWave ranges)¶: Formula “cursors(A,B)” can return NaNs if no cursor(s) are set.

wave SFH_EvaluateRange(SF_ExecutionData *exd, string opShort, variable argNum)¶

Evaluate range parameter.

Range is read as dataset(s), it can be per dataset:

numerical 1D: [start,end]
numerical 2D with multiple ranges: [[start1,start2,start3],[end1,end2,end3]]
- implicit: cursors(A, B) or [cursors(A, B), cursors(C, D)]
- implicit: epochs([E0, TP])
- implicit with offset calculcation: epochs(E0) + [1, -1]
named epoch: E0 or a as wildcard expression E* or multiple

If one dataset is returned, numRows == 1, all ranges will be used for all sweeps in the selection.

When multiple datasets are returned, numRows > 1, the i-th sweep will use all ranges from the i-th dataset. The number of sweeps and datasets also has to match.

Returns:: One or multiple datasets

wave SFH_GetRangeFromEpoch(string graph, string epochName, variable sweep, variable chanType, variable channel, variable mapIndex)¶

Returns a range from a epochName.

Parameters:

graph – name of databrowser graph
epochName – name epoch
sweep – number of sweep
chanType – type of channel
channel – number of DA channel
mapIndex – index in sweepMap, required if source is a SweepBrowser

Returns:

a 1D wave with two elements, [startTime, endTime] in ms, if no epoch could be resolved [NaN, NaN] is returned

wave SFH_GetSweepsForFormula(string graph, WaveRefWaveOrNull selectDataArray, string opShort)¶

static wave SFH_GetSweepsForFormulaImpl(string graph, WaveRefWave selectDataComp, string opShort)¶

Return a wave reference wave with the requested sweep data. The argument range can contain multiple datasets, if it is a single dataset the range(s) are extracted from each selection, if there are multiple datasets then the number of datasets must equal the number of selections, for that case range datasets and selections are indexed the same. This is usually only senseful if the same select arguments are used for e.g. data to retrieve sweeps and epochs to retrieve ranges.

All wave input parameters are treated as const and are thus not modified.

Parameters:

graph – name of databrowser graph
selectDataComp – channel/sweep selection composite, see also SFH_GetArgumentSelect()
opShort – operation name (short)

variable SFH_GetNumberOfArguments(SF_ExecutionData *exd)¶

dfref SFH_GetWorkingDF(string win)¶

wave SFH_CreateSFRefWave(string win, string opShort, variable size)¶

variable SFH_IsVariable(wave dataset)¶

variable SFH_CleanUpInput(wave input)¶

variable SFH_AddOpToOpStack(wave w, string oldStack, string opShort)¶

variable SFH_AddToArgSetupStack(wave output, WaveOrNull input, string argSetupStr, variable resetStack = defaultValue)¶

wave SFH_GetOutputForExecutorSingle(WaveOrNull data, string graph, string opShort, variable discardOpStack = defaultValue, wave clear = defaultValue, string dataType = defaultValue)¶

wave SFH_GetOutputForExecutor(wave output, string win, string opShort, wave clear = defaultValue)¶

static variable SFH_ConvertAllReturnDataToPermanent(WaveRefWave output, string win, string opShort)¶

wave SFH_CopyDataIfRequired(variable copy, WaveOrNull dataset, WaveOrNull data)¶: If the copy condition is met and dataset is a variable then returns a free copy of data dataset and data can refer to the same wave.

std::tuple<WAVE, string> SFH_ResolveDatasetElementFromJSONAndType(SF_ExecutionData *exd, string opShort, variable argNum, variable checkExist = defaultValue, variable copy = defaultValue)¶: Retrieves from an argument the datatype and the first dataset and disposes the argument.

static wave SFH_CheckForSingleDSAndGetData(WaveRefWave input, variable checkExist, string opShort, variable argNum)¶

wave SFH_ResolveDatasetElementFromJSON(SF_ExecutionData *exd, string opShort, variable argNum, variable checkExist = defaultValue, variable copy = defaultValue)¶: Retrieves from an argument the first dataset and disposes the argument.

variable SFH_TransferFormulaDataWaveNoteAndMeta(WaveRefWave input, WaveRefWave output, string opShort, string newDataType, WaveText argSetup = defaultValue, variable keepX = defaultValue)¶

Transfer wavenote from input data sets to output data sets set a label for a x-axis and x-value(s) for data waves.

See also

SFH_GetNewArgSetupWave

Parameters:

input – Input wave reference wave
output – Output wave reference wave
opShort – operation short name
newDataType – data type of output
argSetup – [optional, default=$””] 2d text wave with argument setup of operation
keepX – [optional, default=0] When set then xvalues and xlabel of output are kept.

wave SFH_GetArgumentSelect(SF_ExecutionData *exd, variable argNum, variable doNotEnforce = defaultValue)¶

This function returns an array of select composites that are parsed from one argument that can be either a single select: select(…) or an 1d array of selects: [select(…), select(…), …] The distinction between a single select an array of selects is done through the SF_META_DATATYPE field in the JSON wavenote select composites are of type SF_DATATYPE_SELECTCOMP, whereas arrays are untyped There is also a quick path for argNum >= numArgs, which is the case for e.g. data() For that case numArgs is 0 and select is expected at argNum 0. Then the result of “select()” is returned (as selectArray with a single element) If the doNotEnforce flag is set then a select type value at the arguments location is not enforced. If the argument is neither a single select or an array of selects then a null wave is returned.

selectArray is wave reference wave containing select composite wave reference waves with SELECTION, RANGE each.

This allows operations with selects as arguments to iterate over different selections given by the user

wave SFH_GetEpochNamesFromInfo(WaveText epochInfo)¶

wave SFH_GetEpochIndicesByWildcardPatterns(WaveText epochNames, WaveText patterns)¶

string SFH_ResultTypeToString(variable resultType)¶

string SFH_FormatResultsKey(variable resultType, string name)¶

std::tuple<WaveText, WaveText> SFH_CreateResultsWaveWithCode(string graph, string code, wave data = defaultValue, string name = defaultValue, variable resultType = defaultValue)¶

string SFH_GetBrowserForFormulaGraph(string win)¶: Return the SweepBrowser/DataBrowser from which the given SweepFormula plot window originated from If the plotter runs in normal mode the user data is present for each output window (table/graph) If the plotter runs in subwindow mode the user data is present for the panel that contains the table/graph subwindows, thus if win is a subwindow the browser name will be retrieved from the parent panel.

string SFH_GetFormulaPanelFromBrowser(string browser, variable displayType)¶: Return the SweepFormula plot created by the given SweepBrowser/DataBrowser This function requires the plotter to run in subwindow display mode.

wave SFH_GetFormulaPlotPanels()¶: Return a text wave with all formula graph/table panels from all open data/sweep browsers This function requires the plotter to run in subwindow display mode.

wave SFH_NewSelectDataWave(variable numSweeps, variable numChannels)¶: Create a new selectData wave The row counts the selected combinations of sweep, channel type, channel number The three columns per row store the sweep number, channel type, channel number.

wave SFH_ParseSweepDataRange(wave sweepData)¶: Parse the range stored in the JSON wavenote from SFH_GetSweepsForFormula()

std::tuple<WAVE, WAVE> SFH_ParseToSelectDataWaveAndRange(wave sweepData)¶: Recreate a single select data wave and range stored in the JSON wavenote from SFH_GetSweepsForFormula()

wave SFH_GetNewArgSetupWave(variable size)¶

static string SFH_SerializeArgSetup(WaveText argSetup)¶

wave SFH_DeSerializeArgSetup(variable jsonId, string jsonPath)¶

variable SFH_ResetArgSetupStack(wave output, string opShort)¶

static string SFH_GetArgSetupValueByKey(WaveText argSetup, string key)¶

static string SFH_GetEmptyArgSetup()¶

variable SFH_EnrichAnnotations(WaveText annotations, WaveText formulaArgSetup)¶

Based on the argument setup modifies the annotations per formula with additional information from the different arguments.

Returns:: 1 of difference was found, 0 otherwise

static variable SFH_EnrichAnnotationsRelease(wave formulaIDs)¶

variable SFH_GetPlotMarkerCodeSelection(variable count)¶

variable SFH_GetPlotLineCodeSelection(variable count)¶

wave SFH_FilterSelect(WaveOrNull selectData, variable keepChanType)¶

filters data from select, currently supports only one option:

specify a channel type to keep

variable SFH_CheckArgumentCount(SF_ExecutionData *exd, string opShort, variable minArgs, variable maxArgs = defaultValue)¶: checks the argument count and returns the number of arguments

wave SFH_GetStimsetRange(string graph, wave data, wave selectData)¶

Return a SF range in ms with the stimset range.

Prefers the ST epoch if present, otherwise it tries to deduce the equivalent from labnotebook entries.

std::tuple<WAVE, WaveText> SFH_GetNumericRangeFromEpochFromSingleSelect(string graph, wave singleSelectData, wave range)¶

std::tuple<WAVE, WaveText> SFH_GetNumericRangeFromEpoch(string graph, wave numericalValues, wave textualValues, wave range, variable sweepNo, variable chanType, variable chanNr, variable mapIndex)¶

From a single numeric/textual range wave we return a 2xN numeric range.

Supports numeric ranges, epochs, and epochs with wildcards.

File MIES_SweepFormula_Helpers.ipf¶

Table of Contents

Previous topic

Next topic