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(variable jsonId, string jsonPath, string graph, 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(variable jsonId, string jsonPath, string graph, 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(jsonId, jsonPath, graph, opShort, 0)
type    = SFH_GetArgumentAsText(jsonId, jsonPath, graph, 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(variable jsonId, string jsonPath, string graph, string opShort, variable argNum, string defOp = defaultValue, WaveOrNull defWave = defaultValue, variable singleResult = defaultValue, variable expectedWaveType = 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.

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

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(wave ranges)

Formula “cursors(A,B)” can return NaNs if no cursor(s) are set.

wave SFH_EvaluateRange(variable jsonId, string jsonPath, string graph, 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(variable jsonId, string jsonPath)
dfref SFH_GetWorkingDF(string win)
wave SFH_CreateSFRefWave(string win, string opShort, variable size)
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)
std::tuple<WAVE, string> SFH_ResolveDatasetElementFromJSONAndType(variable jsonId, string jsonPath, string graph, string opShort, variable argNum, variable checkExist = 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(variable jsonId, string jsonPath, string graph, string opShort, variable argNum, variable checkExist = 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(variable jsonId, string jsonPath, string graph, string opShort, variable argNum)

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)

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.

string SFH_GetFormulaGraphForBrowser(string browser)

Return the SweepFormula plot created by the given SweepBrowser/DataBrowser.

wave SFH_GetFormulaGraphs()

Return a text wave with all formula graph windows.

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.

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(variable jsonId, string jsonPath, 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_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.

See also

SFH_EvaluateRange

Parameters:

  • graph – name of graph window

  • numericalValues – numeric labnotebok

  • textualValues – textual labnotebok

  • range – one numerical or one/multiple epoch ranges with optional wildcard,

  • sweepNo – sweep number

  • chanType – channel type

  • chanNr – channel number

  • mapIndex – index in sweepMap if graph is a SweepBrowser

Return values:

  • adaptedRange – 2xN numeric wave with the start/stop ranges [ms]

  • epochRangeNames – epoch names (wildcard expanded) in case range was textual, a null wave ref otherwise

wave SFH_AttemptDatasetResolve(string ref, variable checkWithSFHAssert = defaultValue)

Attempt a resolution of a dataset based on a string input, returns null wave if not resolvable.

variable SFH_IsArray(wave data)

Check if data wave refers to an array Note: The check is rather weak, another option would be tagging in the wavenote by the executor?

wave SFH_MoveDatasetHigherIfCompatible(WaveRefWave data)

Moves datasets from array elements to higher level e.g. [dataset(1, 2), dataset(3, 4)] -> dataset([1, 3], [3, 4]) e.g. [dataset(1, 2, 3), dataset(4, 5, 6)] -> dataset([1, 4], [2, 5], [3, 6]) e.g. [dataset(1, 2), dataset(4, 5), dataset(6, 7)] -> dataset([1, 4, 6], [2, 5, 7]) Requirements that this is possible are:

  • all initial array elements must resolve to datasets

  • all dataset waves of the initial array elements must be non-null, have the same size and must be 1d

  • all elements of these datasets must be non-null, have the same type and the same size and must be max 3d

  • only numeric and text is supported as type, thus the datasets may not contain datasets themselves If none of the requirements are met the input data is returned.

wave SFH_GetSingleSelect(string graph, string opShort, variable sweepNo, variable channelType, variable channelNumber, variable mapIndex)
string SFH_GetStimsetName(wave numericalValues, wave textualValues, variable sweepNo, variable channelNumber, variable channelType)
variable SFH_IsSetQCPassed(wave numericalValues, wave textualValues, variable sweepNo, variable channelNumber, variable channelType)
variable SFH_IsSweepQCPassed(wave numericalValues, wave textualValues, variable sweepNo, variable channelNumber, variable channelType)
static variable SFH_GetIndepPSQEntrySCI(wave numericalValues, wave textualValues, variable sweepNo, variable channelNumber, variable channelType, string psqLNBEntry)
static variable SFH_GetIndepPSQEntry(wave numericalValues, wave textualValues, variable sweepNo, variable channelNumber, variable channelType, string psqLNBEntry)
string SFH_CreateLegendFromRanges(wave selectData, WaveRefWave ranges)
std::tuple<WAVE, WAVE, DFREF> SFH_GetLabNoteBooksAndDFForSweep(string graph, variable sweepNo, variable mapIndex)

Function returns the correct numerical and textual LNB and sweepDFR for a given sweepNumber.

Parameters:

  • graph – name of graph window

  • sweepNo – sweep number

  • mapIndex – if graph is a SweepBrowser then a non-NaN mapIndex into sweepMap, otherwise must be NaN

wave SFH_GetLabNoteBookForSweep(string graph, variable sweepNo, variable mapIndex, variable logbookWaveType)

Function returns the correct numerical and textual LNB for a given sweepNumber.

Parameters:

  • graph – name of graph window

  • sweepNo – sweep number

  • logbookWaveType – one of LabnotebookWaveTypes

  • mapIndex – if graph is a SweepBrowser then a non-NaN mapIndex into sweepMap, otherwise must be NaN

Variables

static const string SFH_WORKING_DF = "FormulaData"
static const string SFH_ARGSETUP_OPERATION_KEY = "Operation"
static const string SFH_ARGSETUP_EMPTY_OPERATION_VALUE = "NOOP"
static const string SFH_DEFAULT_SELECT_FORMULA = "select()"