Points.retain

Points.retain(toRetain=None, start=None, end=None, number=None, randomize=False, features=None, *, useLog=None)

Keep only certain points of this object.

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

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

Parameters:

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

  • identifier - a name or index

  • list of identifiers - an iterable container of identifiers

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

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

• start (identifier) – Parameters indicating range based retention. Begin the retention at the location of start. Finish retaining 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 point, respectively.

• end (identifier) – Parameters indicating range based retention. Begin the retention at the location of start. Finish retaining 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 point, respectively.

• number (int) – The quantity of points that are to be retained, the default None means unrestricted retained. This can be provided on its own (toRetain, start and end are None) to the first number of points, or in conjuction with toRetain 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 points are determined by point order, otherwise it is uniform random across the space of possible points.

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

• 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.

See also

extract, delete

Examples

Retain a single point.

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

Retain multiple points.

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

Retain point when the function returns True.

>>> X = nimble.data([[1, 2, 3], [4, 5, 6], [-1, -2, -3]])
>>> X.points.setNames(['a', 'b', 'c'])
>>> X.points.retain(nimble.match.allPositive)
>>> X
<Matrix 2pt x 3ft
     0  1  2
   ┌────────
 a │ 1  2  3
 b │ 4  5  6
>

Retain point when the query string returns True.

>>> X = nimble.identity(3, pointNames=['a', 'b', 'c'],
...                     featureNames=['f1', 'f2', 'f3'])
>>> X.points.retain("f2 != 0")
>>> X
<Matrix 1pt x 3ft
     f1  f2  f3
   ┌───────────
 b │ 0   1   0
>

Retain points from the inclusive start to the inclusive end.

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

Select a set number to retain, starting from the first point.

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

Select a set number to retain, choosing points at random.

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

Keywords: keep, hold, maintain, preserve, remove, filter