WIP: rst documetation fixes

AllenInstitute · Sep 17, 2024 · 71566d3 · 71566d3
1 parent 1779341
commit 71566d3
Showing 1 changed file with 69 additions and 56 deletions.
diff --git a/Packages/doc/SweepFormula.rst b/Packages/doc/SweepFormula.rst
@@ -578,7 +578,7 @@ The result of `selchannels` has a data type attributed.
 
 .. code-block:: bash
 
-   selchannels([AD0,AD1, DA0, DA1]) == [[0, 0, 1, 1], [0, 1, 0, 1]]
+   selchannels([AD0, AD1, DA0, DA1]) == [[0, 0, 1, 1], [0, 1, 0, 1]]
 
    // Internally NaN is evaluated as joker for all channel types and all channel numbers
    selchannels() == [[NaN], [NaN]]
@@ -615,7 +615,8 @@ selrange
 """"""""
 
 The operation `selrange` allows to specify a time interval either by epoch name or numbers in ms.
-It takes zero or one argument, an epoch name or an array with two numeric values. The numeric values specify the start and end of a range.
+It takes zero or one argument, an epoch name/wildcard or an array with two
+numeric values. The numeric values specify the start and end of a range.
 The operation returns a dataset with a range specification array.
 In case no argument is given, then a dataset with a full-range specification is returned.
 The result of `selrange` has a data type attributed.
@@ -630,6 +631,9 @@ The result of `selrange` has a data type attributed.
    # refers to epoch E1
    selrange(E1)
 
+   # all stimset epochs
+   selrange("E*")
+
    # refers to 30 ms to 100 ms
    selrange([30, 100])
 
@@ -639,7 +643,7 @@ The result of `selrange` has a data type attributed.
 selvis
 """"""
 
-The operation `selvis` allows to specify if selected data is taken from all sweeps or from displayed sweeps only.
+The operation `selvis` allows to specify if selected data is taken from all sweeps or from the displayed sweeps only.
 It takes zero or one argument that can be either `all` or `displayed`.
 In case no argument is given, then the operation defaults to `displayed`.
 The operation returns a text wave with a single element.
@@ -671,13 +675,13 @@ The result of `selcm` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select refers to sweep data in any clamp mode
+   # sweep data in any clamp mode
    selcm()
 
-   # when used in select refers to sweep data acquired in current clamp and voltage clamp mode
+   # sweep data acquired in current clamp and voltage clamp mode
    selcm(ic, vc)
 
-   # when used in select refers to sweep data acquired with no clamp mode (unassociated channels)
+   # sweep data acquired with no clamp mode (unassociated channels)
    selcm(none)
 
 selstimset
@@ -694,10 +698,10 @@ The result of `selstimset` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select refers to sweep data with any stimset wave name
+   # sweep data with any stimset wave name
    selstimset()
 
-   # when used in select refers to sweep data with all stimset wave names that start with pinky and all that end with brain
+   # sweep data with all stimset wave names that start with pinky and all that end with brain
    selstimset("pinky*", "*brain")
 
 selexp
@@ -712,16 +716,16 @@ The result of `selexp` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select refers to sweep data from a specific experiment
+   # sweep data from a specific experiment
    selexp("MyFirstExperiment.pxp")
 
-   # when used in select refers to sweep data from a specific experiment
+   # sweep data from a specific experiment
    selexp("MySecondExp*")
 
 seldev
 """"""
 
-The operation `seldev` allows to specify how select filters data regarding the device name.
+The operation `seldev` allows to specify how select filters data regarding the DAC device name.
 It takes exactly one string argument. The string that can contain wildcards.
 The operation returns a a text wave with the device name wildcard pattern.
 The result of `seldev` has a data type attributed.
@@ -730,10 +734,10 @@ The result of `seldev` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select refers to sweep data from a specific device
+   # sweep data from a specific device
    seldev("ITC18*")
 
-   # when used in select refers to sweep data from a specific device
+   # sweep data from a specific device
    seldev("Dev*")
 
 selrac
@@ -749,7 +753,7 @@ The result of `selrac` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select enables extending the selected sweep number each with the sweeps of the same repeated acquisition cycle
+   # extend the selected sweep numbers each with the sweeps of the same repeated acquisition cycle
    selrac()
 
 selsci
@@ -764,13 +768,13 @@ The result of `selsci` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select enables extending the selected sweep number / channel number / channel type combination each with the sweeps of the same stimset cycle id that have the same channel number / channel type.
+   # extend the selected sweep number / channel number / channel type combination each with the sweeps of the same stimset cycle id that have the same channel number / channel type.
    selsci()
 
 selsetcyclecount
 """"""""""""""""
 
-When the operation `selsetcyclecount` is used with select it includes all selection with the specified set cycle count.
+When the operation `selsetcyclecount` is used with select it includes all sweeps with the specified set cycle count.
 The operation takes exactly one numerical argument.
 The operation returns a a numeric wave with a single element that has the value of the given argument.
 The result of `selsetcyclecount` has a data type attributed.
@@ -779,7 +783,7 @@ The result of `selsetcyclecount` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select includes all sweeps that have a set cycle count of 5
+   # sweeps that have a set cycle count of 5
    selsetcyclecount(5)
 
 selsetsweepcount
@@ -792,6 +796,11 @@ The result of `selsetsweepcount` has a data type attributed.
 
 `selsetsweepcount` is intended to be used with the `select()` operation.
 
+.. code-block:: bash
+
+   # sweeps that have a set sweep count of 2
+   selsetsweepcount(2)
+
 selsciindex
 """""""""""
 
@@ -811,9 +820,7 @@ The result of `selsciindex` has a data type attributed.
 .. code-block:: bash
 
    # Looks at all sweep starting from sweep 3 with channel AD0. Selects all sweeps that have starting from sweep 3 the third unique stimset cycle id.
-   select(selsweeps([3, inf]), selchannels(AD0), selsciindex(3))
-
-.. code-block:: bash
+   select(selsweeps([3, 1000]), selchannels(AD0), selsciindex(3))
 
    # example, where the first three columns are the result of a selection, the last two columns are added for illustration
    # a possible selection with a two headstage setup could be select(selvis(all), selsweeps([0, 3]), selchannels(AD))
@@ -861,12 +868,12 @@ The result of `selracindex` has a data type attributed.
 .. code-block:: bash
 
    # Looks at all sweep starting from sweep 3 with channel AD0. Selects all sweeps that have starting from sweep 3 the third unique repeated acquisition cycle id.
-   select(selsweeps([3, inf]), selchannels(AD0), selracindex(3))
+   select(selsweeps([3, 1000]), selchannels(AD0), selracindex(3))
 
 selexpandsci
 """"""""""""
 
-When the operation `selexpandsci` is used with select then select works in a two-step way.
+When the operation `selexpandsci` is used with select then select operates in a two-step regime.
 First the common select filters e.g. by sweep number, stimset, etc. are applied.
 Then for each of these selections the selections with the same stimset cycle id are also added.
 For example when a single sweep/channel is selected all other sweeps from the same stimset cycle id can be collected for the resulting selections.
@@ -884,7 +891,7 @@ The result of `selexpandsci` has a data type attributed.
 selexpandrac
 """"""""""""
 
-When the operation `selexpandrac` is used with select then select works in a two-step way.
+When the operation `selexpandrac` is used with select then select operates in a two-step regime.
 First the common select filters e.g. by sweep number, stimset, etc. are applied.
 Then for each of these selections the selections with the same repeated acquisition cycle are also added.
 So for example when a single sweep/channel is selected all other sweeps from the same repeated acquisition cycle can be collected for the resulting selections.
@@ -902,7 +909,8 @@ The result of `selexpandrac` has a data type attributed.
 selivsccsweepqc
 """""""""""""""
 
-The operation `selivsccsweepqc` allows to specify how select filters data regarding the sweep quality check from analysis functions.
+The operation `selivsccsweepqc` allows to specify how select filters data
+regarding the sweep quality check from the IVSCC analysis functions.
 It takes between one argument that can be either `failed` or `passed`.
 The operation returns a a text wave with the argument value as string.
 The result of `selivsccsweepqc` has a data type attributed.
@@ -911,16 +919,17 @@ The result of `selivsccsweepqc` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select refers to sweep data where the analysis function passed the sweepqc check
+   # sweep data where the analysis function passed the sweepqc check
    selivsccsweepqc(passed)
 
-   # when used in select refers to sweep data where the analysis function failed the sweepqc check
+   # sweep data where the analysis function failed the sweepqc check
    selivsccsweepqc(failed)
 
 selivsccsetqc
 """""""""""""
 
-The operation `selivsccsetqc` allows to specify how select filters data regarding the set quality check from analysis functions.
+The operation `selivsccsetqc` allows to specify how select filters data
+regarding the set quality check from the IVSCC analysis functions.
 It takes between one argument that can be either `failed` or `passed`.
 The operation returns a a text wave with the argument value as string.
 The result of `selivsccsetqc` has a data type attributed.
@@ -929,10 +938,10 @@ The result of `selivsccsetqc` has a data type attributed.
 
 .. code-block:: bash
 
-   # when used in select refers to sweep data where the analysis function passed the setqc check
+   # sweep data where the analysis function passed the setqc check
    selivsccsetqc(passed)
 
-   # when used in select refers to sweep data where the analysis function failed the setqc check
+   # sweep data where the analysis function failed the setqc check
    selivsccsetqc(failed)
 
 cursors
@@ -1005,10 +1014,11 @@ The `data` operation is the core of the `SweepFormula` library. It returns sweep
 
 The operation `data` retrieves selected sweep data.
 
-It takes one argument that is either a `select` expression or an array of `select` s.
+It takes one argument that is either a `select` operation or an array of `select` operations.
 
-If an array of `select`s is specified then over each selected data is iterated independently. Thus, one data expression can retrieve sweep data from
-multiple `select` s.
+If an array of `select` operations is specified then over each selected data is iterated
+independently. Thus, one data expression can retrieve sweep data from
+multiple `select` operations.
 
 A given `selrange` in `select` as numbers or epoch extracts a subrange of data points from the sweep. The start and end time is converted to
 closest integer indices, where the included points range from `startIndex` to `endIndex - 1`. This matches the general handling
@@ -1020,34 +1030,35 @@ The returned data type is `SF_DATATYPE_SWEEP`.
 
 .. code-block:: bash
 
-   # Shows the AD channels of all displayed sweeps with the range 0 - 1s
-   data(select(selchannels(AD)))
+   # AD channels of all displayed sweeps with the range 0 - 1s
+   data(select(selrange([0, 1000]), selchannels(AD)))
 
-   # Shows epoch "E1" range of the AD channels of all displayed sweeps
+   # epoch "E1" range of the AD channels of all displayed sweeps
    data(select(selrange(E1), channels(AD)))
 
-   # Shows epoch "E1" range with the start offsetted by 10ms of the AD channels of all displayed sweeps
+   # epoch "E1" range with the start offsetted by 10ms of the AD channels of all displayed sweeps
    sel = select(selchannels(AD))
    rng = epochs("E1", $sel) + [10, 0]
-   data(selrange($rng), $sel)
+   data(select(selrange($rng), $sel))
 
-   # Shows sweep data from all epochs starting with "E" of the AD channels of all displayed sweeps
+   # sweep data from all epochs starting with "E" of the AD channels of all displayed sweeps
    data(select(selrange("E*"), selchannels(AD)))
 
-   # Shows sweep data from all epochs starting with "E"  and "TP" of the AD channels of all displayed sweeps
+   # sweep data from all epochs starting with "E"  and "TP" of the AD channels of all displayed sweeps
    sel1 = select(selchannels(AD))
    sel2 = select(selrange("E*"), $sel1)
    sel3 = select(selrange("TP*"), $sel1)
    data([$sel2, $sel3])
 
-   # Shows sweep data from all epochs that do not start with "E"  and that do start with "TP" of the AD channels of all displayed sweeps
+   # sweep data from all epochs that do not start with "E"  and that do start with "TP" of the AD channels of all displayed sweeps
    sel1 = select(selchannels(AD))
    sel2 = select(selrange("!E*"), $sel1)
    sel3 = select(selrange("TP*"), $sel1)
    data([$sel2, $sel3])
 
    # extract the first pulse from TTL1 as epoch and extract the AD data in that range
-   sel1 = select(selrange("E0_PT_P0"), selchannels(TTL1))
+   sel1 = select(selchannels(TTL1))
+   ep = epochs(E0_PT_P0, $sel1)
    data(select(selrange($ep), channels(AD)))
 
    # extract the first pulse from TTL1 as epoch with a start and end offset, then extract the AD data in that range
@@ -1594,8 +1605,8 @@ If a specific filter is not part of the arguments and none of the arguments is a
 - `selsetsweepcount`: set sweep count is ignored
 - `selsciindex`: stimset cycle id index is ignored
 - `selracindex`: repeated acquisition is index is ignored
-- `selrac`: expansion by repeated acquisition cycle is disabled
-- `selsci`: expansion by stimset cycle id is disabled
+- `selexpandrac`: expansion by repeated acquisition cycle is disabled
+- `selexpandsci`: expansion by stimset cycle id is disabled
 
 If a specific filter is not part of the arguments and there exists at least one arguments that is a `select` then these filters will be ignored:
 - `selchannels`: select all channels
@@ -1604,16 +1615,16 @@ If a specific filter is not part of the arguments and there exists at least one
 - `selvis`: select all sweeps
 - `selscm`: select all clamp modes
 - `selstimset`: select all stimset wave names
-- `selivsccsetqc`: IVSCC SetQC is ignored
-- `selivsccsweepqc`: IVSCC SweepQC is ignored
+- `selivsccsetqc`: IVSCC Set QC is ignored
+- `selivsccsweepqc`: IVSCC Sweep QC is ignored
 - `selexp`: experiment name is ignored
 - `seldev`: device name is ignored
 - `selsetcyclecount`: set cycle count is ignored
 - `selsetsweepcount`: set sweep count is ignored
 - `selsciindex`: stimset cycle id index is ignored
 - `selracindex`: repeated acquisition is index is ignored
-- `selrac`: expansion by repeated acquisition cycle is disabled
-- `selsci`: expansion by stimset cycle id is disabled
+- `selexpandrac`: expansion by repeated acquisition cycle is disabled
+- `selexpandsci`: expansion by stimset cycle id is disabled
 
 If `select` arguments appear multiple times then the resulting selection is an intersection of all sweep/channel combinations that were selected
 from all these `select` arguments.
@@ -1624,24 +1635,24 @@ The range specified through `selrange` is always taken from the topmost `select`
 
 If an experiment is specified with a wildcard pattern through `selexp` then there must be only a single matching experiment. The same applies for `seldev`. Only when the source is from a SweepBrowser with different loaded experiments then using `selexp` is senseful as e.g. for a DataBrowser the experiment is always the current experiment.
 
-The filter criteria of the select filters are orthogonal (independent of each other) except for `selsciindex`, `selracindex`, `selrac` and `selsci`.
-Internally first the orthogonal select filters are applied. Then based on the resulting selections `selsciindex`, `selracindex` is applied, then `selrac`, `selsci`.
+The filter criteria of the select filters are orthogonal (independent of each other) except for `selsciindex`, `selracindex`, `selexpandrac` and `selexpandsci`.
+Internally first the orthogonal select filters are applied. Then based on the resulting selections `selsciindex`, `selracindex` is applied, then `selexpandsci`, `selexpandsci`.
 Intersections with additional selections from select type arguments are executed afterwards.
 This implies that created selections can not be further filtered once created (see example).
 
-When `selrac` is used then the selected sweep numbers from `selsweeps` are extended. For each sweep selected by
+When `selexpandrac` is used then the selected sweep numbers from `selsweeps` are extended. For each sweep selected by
 `selsweeps` sweeps numbers of the same repeated acquisition cycle are added. For the new sweep numbers selections are gathered with a modified copy of the initial selection filter:
 - `selvis` is changed to `all`
 - `selexp` is set to the experiment of the sweep number that was extended
 - `seldev` is set to the device of the sweep number that was extended
 
 The resulting selections are gathered for each additional sweep number. Finally all selections are reduced to be unique only.
 
-When `selsci` is used then first the selection is retrieved for `selsci` disabled. Then for each selection
+When `selexpandsci` is used then first the selection is retrieved for `selsci` disabled. Then for each selection
 for the sweep number / channel number / channel type combination the sweep numbers with the same stimset cycle id are determined. For these sweeps selections with the same channel number / channel type are added.
 Finally all selections are reduced to be unique only.
 
-The expansion through `selsci` and `selrac` operates on the current select filter.
+The expansion through `selexpandsci` and `selexpandsci` operates on the current select filter.
 
 The output is composite with two datasets of different type.
 The first dataset contains a N x 4 array where the columns are sweep number, channel type, GUI channel number and row index of the sweepMap. The sweepMap only exists if the window is a SweepBrowser, for DataBrowser the values are set NaN in that column.
@@ -1673,13 +1684,15 @@ If there are no matching sweeps found a null wave is returned.
 
 .. code-block:: bash
 
-   # For sel2 the SCI expansion applies to sweep 0, AD0. The selection result of the expansion is then intersected with sweep 1 AD0 that was selected through sel1.
+   # For sel2 the SCI expansion applies to sweep 0, AD0. The selection result
+   # of the expansion is then intersected with sweep 1 AD0 that was selected
+   # through sel1.
    sel1 = select(selchannels(AD0), selsweeps(1), selvis(all))
-   sel2 = select(selchannels(AD0), selsweeps(0), selvis(all), selsci(), $sel1)
+   sel2 = select(selchannels(AD0), selsweeps(0), selvis(all), selexpandsci(), $sel1)
 
 .. code-block:: bash
 
-   # Note that the sel2 expression does not a post-filtering of sel1
+   # Note that the sel2 expression does not do a post-filtering of sel1
    # instead selracindex(5) is applied to the selections resulting from
    # the default filter setting for select for the case there is a select type argument present
    # Then these selections are intersected from sel1
@@ -1828,7 +1841,7 @@ If a selected sweep does not contain any test pulse then for that data wave a nu
    tp(tpbase(), select(selchannels(AD1)))
 
    # Get base line level from all displayed sweeps with AD1 channel and all sweeps with AD2 channel
-   tp(tpbase(), [select(selchannels(AD1), select(selchannels(AD2), selvis(all))]))
+   tp(tpbase(), [select(selchannels(AD1)), select(selchannels(AD2), selvis(all))])
 
    # Get base line level from all displayed sweeps and channels ignoring test pulse 0 and 1
    tp(tpbase(), select(), [0, 1])