3.9.2. sciexp2.common.instance.InstanceGroup

Methods

add(instance)	Add an Instance into this group.
cache_get()	Get the caching state.
cache_prefetch([variables, skip_cached])	Enable caching and force it for the given variables.
cache_reset([hard])	Reset the cache of this group.
cache_set(enable[, proactive, others])	Set the caching status for this group.
copy()	Return a copy.
dump(file_obj[, export])	Write a pickled representation.
extend(instances)	Extend this group with the contents of another group.
get_index(index)	Get instance at the index'th position.
has_instance(instance)	Whether this group contains the given Instance.
has_variable(variable)	Whether the group contains any Instance with given variable name.
load(file_obj)	Load a pickled representation.
pformat(pretty, cycle[, name])	Return pretty representation.
select(filter_[, allow_unknown])	Generate a sequence of instances matching the given filter.
set_view_able(view_able)	Set whether this object can produce "views" from it.
sort(variables[, key])	Sort group in-place by the given variables.
sorted(*args, **kwargs)	Same as sort, but returns a sorted copy.
variables()	The sequence of variables in this group.
view(index)	Create a view (sub-set) of this object.

class InstanceGroup(instances=None, cache=True, cache_proactive=False, cache_others=None, view_able=False)

Bases: Pretty

A group of Instance objects suitable for searching.

Provides a fast way to retrieve a set of Instance objects that have certain variables set or certain variable values.

Parameters:

instancesiterable of Instance objects, optional

Initial contents. Contents are copied during initialization.

cache, cache_proactive, cache_others

Arguments to cache_set.

view_ablebool, optional

Whether to enable the use of view.

See also

cache_set

Notes

Warning

You should not modify the results of accessing an InstanceGroup, unless you know what you’re doing.

As this operation returns the same data being used internally, changes to it must be kept consistent with the cache (see cache_reset).

Warning

You should not add or extend a group with instances that have the same contents as other instances already present in the group.

Examples

>>> g = InstanceGroup([{'a':4, 'b':3}, {'a':2, 'b':1}, {'a':4}])
>>> g
InstanceGroup([Instance({'a': 4, 'b': 3}),
               Instance({'a': 2, 'b': 1}),
               Instance({'a': 4})])

Testing the existence of variables:

>>> 'a' in g
True
>>> 'c' in g
False

Getting all the possible values for a variable:

>>> g['a']
OrderedDict({4: OrderedSet([Instance({'a': 4, 'b': 3}), Instance({'a': 4})]),
             2: OrderedSet([Instance({'a': 2, 'b': 1})])})
>>> g['b']
OrderedDict({3: OrderedSet([Instance({'a': 4, 'b': 3})]),
             1: OrderedSet([Instance({'a': 2, 'b': 1})])})

Getting all the instances with a specific value:

>>> g['a'][4]
OrderedSet([Instance({'a': 4, 'b': 3}), Instance({'a': 4})])

Extending a group with another:

>>> h = InstanceGroup([{'a':1}, {'a':2}])
>>> h
InstanceGroup([Instance({'a': 1}), Instance({'a': 2})])
>>> g + h
InstanceGroup([Instance({'a': 4, 'b': 3}),
               Instance({'a': 2, 'b': 1}),
               Instance({'a': 4}),
               Instance({'a': 1}),
               Instance({'a': 2})])
>>> g += h
>>> g
InstanceGroup([Instance({'a': 4, 'b': 3}),
               Instance({'a': 2, 'b': 1}),
               Instance({'a': 4}),
               Instance({'a': 1}),
               Instance({'a': 2})])
>>> g['a']
OrderedDict({4: OrderedSet([Instance({'a': 4, 'b': 3}), Instance({'a': 4})]),
             2: OrderedSet([Instance({'a': 2, 'b': 1}), Instance({'a': 2})]),
             1: OrderedSet([Instance({'a': 1})])})

set_view_able(view_able)

Set whether this object can produce “views” from it.

Objects able to produce views have lower performance when adding new elements to them.

See also

InstanceGroup.view

view(index)

Create a view (sub-set) of this object.

This object also becomes a view. Modifications to the elements of a view will also take effect on all other views of the same object.

Parameters:

indexslice

See also

InstanceGroup.set_view_able

copy()

Return a copy.

get_index(index)

Get instance at the index’th position.

add(instance)

Add an Instance into this group.

The caching state will have an impact on the performance of this operation.

See also

cache_set

extend(instances)

Extend this group with the contents of another group.

has_variable(variable)

Whether the group contains any Instance with given variable name.

has_instance(instance)

Whether this group contains the given Instance.

variables()

The sequence of variables in this group.

cache_get()

Get the caching state.

cache_set(enable, proactive=None, others=None)

Set the caching status for this group.

Caching offers greater speed of getting a specific variable multiple times (e.g., g['a']), at the expense of a higher memory footprint.

Parameters:

enablebool

Caching status. When the caching is disabled, automatically calls cache_reset.

proactivebool or sequence of variable names, optional

Proactively cache slected variables when adding new instances (default is to keep last value).

otherssequence of variable names, optional

List of other variables that the group does/will contain (default is to keep last value).

See also

cache_get, cache_reset, cache_prefetch

Notes

If caching is disabled, every call to add will reset the cache for the variables of the added instance.

If proactive is True, it will proactively cache all variables, if it is False it will not. If it is a sequence of variable names, only these variables will be proactively cached.

You can also provide an empty proactive list and an appropriate others list to get zero-caching during instance addition, which is the fastest option available.

Warning

Providing others will greatly enhance the performance of add, but the contents will be inconsistent if others does not contain exactly all the variables of the instances previously present or added before interacting with the group.

You can use cache_reset with the hard argument to ensure consistency.

cache_reset(hard=False)

Reset the cache of this group.

Parameters:

hardbool optional

Perform a costly “hard” cache reset by inspecting all instances in the group.

See also

cache_get, cache_set

cache_prefetch(variables=None, skip_cached=True)

Enable caching and force it for the given variables.

Parameters:

variablessequence of variable names, optional

Variables to prefetch. Uses all variables when None.

skip_cachedbool, optional

Do not recompute caching if a variable is already cached.

See also

cache_get, cache_set

Notes

When prefetching a variable that is already cached, not necessarily all its values will be present on the cache (only those previously referenced); thus the skip_cached argument.

select(filter_, allow_unknown=False)

Generate a sequence of instances matching the given filter.

Parameters:

filter_filter

Filter establishing which instances to select from this group (accepts anything convertible into a filter).

allow_unknownbool or callable, optional

Whether to allow the filter to reference variables not present in all instances of the group (in which case the instance is not selected). If a callable is used, it will receive the instance and its result will be used.

sorted(*args, **kwargs)

Same as sort, but returns a sorted copy.

sort(variables, key=None)

Sort group in-place by the given variables.

Parameters:

variableslist of strings

Variable names for which to sort their values. The instances are sorted according to the order of the given variable names.

keyfunc, optional

Function returning a value that will be used for comparison. By default compares all instance variables as a list.

See also

functools.cmp_to_key

dump(file_obj, export=None)

Write a pickled representation.

Parameters:

file_objfile

The destination file.

exportset of strings, optional

Variables that must be exported. Defaults to all.

See also

pickle

static load(file_obj)

Load a pickled representation.

See also

pickle