Descriptor developer API

A Descriptor is a special kind of object which takes in one or many RecordCollection, and output one or many RecordCollection where each enclosed Record have an additional property.

The developer API exposes the abstract base class for all descriptors which indicates necessary interfaces to implement to construct a valid Descriptor.

It also exposes two special kinds of Descriptor:

• The ColorEngine, which is used internally to generate a color property which contains the Color used to plot a Record from one or two Descriptor.

• The ByCategoryDescriptor which wraps a Descriptor to make it dependent on a monitored property in Record.

class plums.plot.engine.Descriptor(name)

Bases: object

Abstract base class for all Descriptor.

A Descriptor is a class used to extract relevant information from a collection of Record.

More specifically, a Descriptor is used in two phases:

• In a first time, optional internals are updated and/or accumulated over the entire collection of RecordCollection tuples. Those internals will be used to tailor the Descriptor to the description task specific context (e.g. like updating a range of possible value to later normalize or clip a property value).

• In a second time, the descriptor is used to construct a new RecordCollection or a tuple of RecordCollection where each enclosed Record is added a named property containing the adequate description of the Record from a tuple of RecordCollection.

Subclasses must override the two interfaces used to do so: update(*record_collections) and compute(*record_collections) as well as the reset() method and the _make_interface() private method.

Parameters

name (str) – The Descriptor name.

name

The Descriptor name.

Type

str

property property_name

The Record inserted property name after compute() call.

Type

str

abstract update(*record_collections)

Update internal values from Record descriptions.

Parameters

*record_collections (RecordCollection) – RecordCollection of which Record will be used to update internals.

abstract compute(*record_collections)

Construct new RecordCollection where each enclosed Record is added a named description property.

Parameters

*record_collections (RecordCollection) – RecordCollection used to construct new RecordCollection with described Record.

Returns

A described RecordCollection tuple.

Return type

(RecordCollection, )

abstract reset()

Reset Descriptor internals to factory values.

class plums.plot.engine.color_engine.ByCategoryDescriptor(monitored_property, descriptor)

Bases: plums.plot.engine.descriptor.Descriptor

Wrapper class to split a given Descriptor interface calls along a set of categories.

Parameters

• monitored_property (str) – The Record property to monitor for the collection and descriptor split.

• descriptor (Descriptor) – A Descriptor to split along a set of categories.

property property_name

The Record inserted property name after compute() call.

Type

str

property type

Either categorical or continuous. The enclosed Descriptor type.

Type

str

update(*record_collections)

Update internal values of category-split Descriptor from Record descriptions.

Parameters

*record_collections (RecordCollection) – RecordCollection of which Record will be used to update internals.

compute(*record_collections)

Construct new RecordCollection where each enclosed Record is added a named description property.

Parameters

*record_collections (RecordCollection) – RecordCollection used to construct new RecordCollection with described Record.

Returns

A described RecordCollection tuple.

Return type

(RecordCollection, )

reset()

Reset Descriptor internals to factory values.

class plums.plot.engine.color_engine.ColorEngine(main_descriptor, secondary_descriptor=None, ctype='sRGB255')

Bases: plums.plot.engine.descriptor.Descriptor

A special Descriptor used to generate Color from one or two Descriptor.

More specifically, a ColorEngine is used in two phases:

• In a first time, enclosed Descriptor internals are updated and/or accumulated over the entire collection of RecordCollection tuples.

• In a second time, the ColorEngine is used to construct a new RecordCollection where each enclosed Record is added a property called color containing a Color instance computed from the properties computed by the enclosed Descriptor.

Parameters

• main_descriptor (Descriptor) – The principal Descriptor. It might be a categorical descriptor or a continuous descriptor, in which case no secondary_descriptor can be provided.

• secondary_descriptor (Descriptor) – Optional. Default to None. A refinement Descriptor. It might be a categorical descriptor or a continuous descriptor.

• ctype (str) – The color space the generated Color will live in (e.g. “sRGB255” or “JCh”).

property property_name

The Record inserted property name after compute() call.

Type

str

property ctype

The color space the ColorMap lives in (e.g. “sRGB255” or “JCh”).

See also

For more information on valid color spaces, please see Color.

Type

str

update(*record_collections)

Update the enclosed Descriptor from Record property name value.

Parameters

*record_collections (RecordCollection) – RecordCollection of which Record will be used to update the enclosed Descriptor.

compute(*record_collections)

Construct a new RecordCollection where each enclosed Record is added a Color as a property.

Parameters

**record_collections (RecordCollection) – RecordCollection used to construct new RecordCollection with described Record.

Returns

A tuple containing one RecordCollection with colors.

Return type

(RecordCollection, )

reset()

Reset Descriptor enclosed Descriptor to factory values.