Features.extract

Features.extract(toExtract=None, start=None, end=None, number=None, randomize=False, points=None, *, useLog=None)

Move certain features of this object into their own object.

A variety of methods for specifying the features to extract based on the provided parameters. If toExtract is not None, start and end must be None. If start or end is not None, toExtract must be None.

The nimble.match module contains many helpful functions that could be used for toExtract.

Parameters:

  • toExtract (identifier, list of identifiers, function, query) –

    • identifier - a name or index

    • list of identifiers - an iterable container of identifiers

    • function - accepts a feature as its only argument and returns a boolean value to indicate if the feature should be extracted. See nimble.match for common functions.

    • query - string in the format ‘POINTNAME OPERATOR VALUE’ (i.e “pt1 < 10”, “id4 == yes”, or “row4 is nonZero”) where OPERATOR is separated from the POINTNAME and VALUE by whitespace characters. See nimble.match.QueryString for string requirements.

  • start (identifier) – Parameters indicating range based extraction. Begin the extraction at the location of start. Finish extracting at the inclusive end location. If only one of start and end are non-None, the other default to 0 and the number of values in each feature, respectively.

  • end (identifier) – Parameters indicating range based extraction. Begin the extraction at the location of start. Finish extracting at the inclusive end location. If only one of start and end are non-None, the other default to 0 and the number of values in each feature, respectively.

  • number (int) – The quantity of features that are to be extracted, the default None means unrestricted extraction. This can be provided on its own (toExtract, start and end are None) to the first number of features, or in conjuction with toExtract or start and end, to limit their output.

  • randomize (bool) – Indicates whether random sampling is to be used in conjunction with the number parameter. If randomize is False, the chosen features are determined by feature order, otherwise it is uniform random across the space of possible features.

  • points (None, identifier, list of identifiers) – Only apply the target function to a selection of points in each feature. May be a single point name or index, an iterable, container of point names and/or indices. None indicates application to all points.

  • useLog (bool, None) – Local control for whether to send object creation to the logger. If None (default), use the value as specified in the “logger” “enabledByDefault” configuration option. If True, send to the logger regardless of the global option. If False, do NOT send to the logger, regardless of the global option.

Returns:

nimble Base object

See also

retain, delete

Examples

Extract a single feature.

>>> X = nimble.identity(3)
>>> X.features.setNames(['a', 'b', 'c'])
>>> single = X.features.extract('a')
>>> single
<Matrix 3pt x 1ft
     a
   ┌──
 0 │ 1
 1 │ 0
 2 │ 0
>
>>> X
<Matrix 3pt x 2ft
     b  c
   ┌─────
 0 │ 0  0
 1 │ 1  0
 2 │ 0  1
>

Extract multiple features.

>>> X = nimble.identity(3)
>>> X.features.setNames(['a', 'b', 'c'])
>>> multiple = X.features.extract(['a', 2])
>>> multiple
<Matrix 3pt x 2ft
     a  c
   ┌─────
 0 │ 1  0
 1 │ 0  0
 2 │ 0  1
>
>>> X
<Matrix 3pt x 1ft
     b
   ┌──
 0 │ 0
 1 │ 1
 2 │ 0
>

Extract feature when the function returns True.

>>> X = nimble.data([[1, 2, 3], [4, 5, None], [7, 8, 9]])
>>> X.features.setNames(['a', 'b', 'c'])
>>> func = X.features.extract(nimble.match.anyMissing)
>>> func
<Matrix 3pt x 1ft
       c
   ┌──────
 0 │ 3.000
 1 │
 2 │ 9.000
>
>>> X
<Matrix 3pt x 2ft
       a      b
   ┌─────────────
 0 │ 1.000  2.000
 1 │ 4.000  5.000
 2 │ 7.000  8.000
>

Extract feature when the query string returns True.

>>> X = nimble.identity(3, featureNames=['a', 'b', 'c'],
...                     pointNames=['p1', 'p2', 'p3'])
>>> strFunc = X.features.extract("p2 != 0")
>>> strFunc
<Matrix 3pt x 1ft
      b
    ┌──
 p1 │ 0
 p2 │ 1
 p3 │ 0
>
>>> X
<Matrix 3pt x 2ft
      a  c
    ┌─────
 p1 │ 1  0
 p2 │ 0  0
 p3 │ 0  1
>

Extract features from the inclusive start to the inclusive end.

>>> X = nimble.identity(3)
>>> X.features.setNames(['a', 'b', 'c'])
>>> startEnd = X.features.extract(start=1, end=2)
>>> startEnd
<Matrix 3pt x 2ft
     b  c
   ┌─────
 0 │ 0  0
 1 │ 1  0
 2 │ 0  1
>
>>> X
<Matrix 3pt x 1ft
     a
   ┌──
 0 │ 1
 1 │ 0
 2 │ 0
>

Select a set number to extract, starting from the first feature.

>>> nimble.random.setSeed(42)
>>> X = nimble.identity(3)
>>> X.features.setNames(['a', 'b', 'c'])
>>> numberNoRandom = X.features.extract(number=2)
>>> numberNoRandom
<Matrix 3pt x 2ft
     a  b
   ┌─────
 0 │ 1  0
 1 │ 0  1
 2 │ 0  0
>
>>> X
<Matrix 3pt x 1ft
     c
   ┌──
 0 │ 0
 1 │ 0
 2 │ 1
>

Select a set number to extract, choosing features at random.

>>> X = nimble.identity(3)
>>> X.features.setNames(['a', 'b', 'c'])
>>> numberRandom = X.features.extract(number=2, randomize=True)
>>> numberRandom
<Matrix 3pt x 2ft
     c  a
   ┌─────
 0 │ 0  1
 1 │ 0  0
 2 │ 1  0
>
>>> X
<Matrix 3pt x 1ft
     b
   ┌──
 0 │ 0
 1 │ 1
 2 │ 0
>

Keywords: move, pull, separate, withdraw, cut, vsplit, filter