Selections and Selection History

class setvis.history.Selection(*, columns: List | None = [], records: List | None = [], intersections: List | None = [])

A collection to hold data describing a selection of items in a Membership object

This class is used as a convenient container for lists of records identifiers, intersection identifiers and column names to be considered by a method – it is up to the particular method how these are interpreted, but generally as a “selection” of items to include (or exclude) from processing.

Since columns, record IDs, and intersection IDs are specific to a Membership object, a Selection should always be used to refer to a selection of items from the same object, although no reference is kept to it.

Specifying None for any of the attributes is intended to be equivalent to specifying a list of all values of that attribute in the related Membership object.

columns

The included column names (may be any value returned by Membership.columns(), which will generally be the same as in the underlying data source)

Type:

Optional[List]

records

The included record IDs (may be any value in Membership.columns()["_record_id"])

Type:

Optional[List]

intersections

The included intersection IDs (may be any value in Membership.intersections().index)

Type:

Optional[List]

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'columns': FieldInfo(annotation=Union[List, NoneType], required=False, default=[]), 'intersections': FieldInfo(annotation=Union[List, NoneType], required=False, default=[]), 'records': FieldInfo(annotation=Union[List, NoneType], required=False, default=[])}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class setvis.history.SelectionHistory(membership: Membership, selections: Dict[str, SubSelection] | None = None)

History of nested selections made from a Membership class

Selections are identified by a name provided when they are created. Each named selection has:

  • a named parent on which the selection is based;

  • a list of items to exclude from the parent.

These named selections form a tree. The root of the tree is the initial Membership instance, passed to the constructor as membership, and may be referred to be the special name, None.

An initial tree of selections may be specified in the constructor by passing a dictionary of names to SubSelection instances as selections.

Parameters:

  • membership (Membership) – The initial Membership object

  • selections (Optional[Dict[str, SubSelection]] = None) – Optionally, a dictionary containing the selection history

__getitem__(name)

Return the Selection associated with a name

This contains the items to exclude from the parent of the named selection.

Parameters:

name (str) – The name of the selection to return

See also

parent

The parent of a named selection

__setitem__(name, exclude: Selection | None)

Set the Selection associated with name to exclude.

This mutates the SelectionHistory instance.

The selection is interpreted as the items to exclude from names parent.

Parameters:

  • name (str) – The name of the selection to mutate

  • exclude (Optional[Selection]) – The new selection to use for the items to exclude from name‘s parent. If None, the entire parent selection is kept.

Note

We do not provide an interface specifying what should be included in the selection (rather than excluded from it), since this would mean calculating the parent’s selection – this is left to the caller.

ancestors(name)

Return all ancestors of the named selection

ancestors is the transitive closure of parent

membership(name: str | None = None)

Return the membership instance associated with

This is constructed on the fly.

Parameters:

name (Optional[str]) – The name of the selection for which to construct the Membership object.

parent(name: str)

Return the parent of the named selection

class setvis.history.SubSelection(*, parent: str | None = None, exclude: Selection = Selection(columns=[], records=[], intersections=[]))

A selection relative to a named parent selection

It is used internally by SelectionHistory, and should not be needed in user code.

This is intended to represent a selection that is the same as the one named parent (extrinsic to this class), but with the selection exclude removed by drop_selection.

Selections specify the items that they exclude, rather than include, so that nested selections can be stored efficiently.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'exclude': FieldInfo(annotation=Selection, required=False, default=Selection(columns=[], records=[], intersections=[])), 'parent': FieldInfo(annotation=Union[str, NoneType], required=False, default=None)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

setvis.history.drop_selection(m: Membership, exclude: Selection) → Membership

Remove records and columns from a Membership object

Returns a new membership object the same as m but with:

  • records with the given record IDs (exclude.records) removed

  • all records with the given intersection IDs (exclude.intersections) removed

  • columns with the given column names (exclude.columns) dropped

Parameters:

  • m (Membership) – The initial Membership object

  • exclude (Selection) – The items to exclude

Returns:

A membership object, as described

Return type:

Membership

setvis.history.iterated_apply(f: Callable, x: Any)

Generator of repeated function applications

The function f must be callable with a single argument. This is repeatedly applied to its own output, yielding the result each time until f returns None. The initial result is x. This generates the sequence

x, f(x), f(f(x)), … , f( … f(x) …)

which either does not terminate, or terminates when one more application of f would be None.

previous

Set Expressions

next

Plotting and interactivity