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 asdefValue
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 asdefValue
is not present.The second argument
type
is optional withsteam 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 asdefOp
is not present. PassingsingleResult == 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 operationbirdTypes()
is called and its result returned. AlternativelydefWave
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(WaveRefWave 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 expressionE*
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
- 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
-
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)¶
-
wave SFH_DeSerializeArgSetup(variable jsonId, string jsonPath)¶
-
variable SFH_ResetArgSetupStack(wave output, string opShort)¶
-
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
- 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