galactic.algebras.convex.characteristics.core

galactic.algebras.convex.characteristics.core#

galactic.algebras.convex.characteristics.core module

Defines core components and characteristics for convex algebras.

Components

Component: Base class for components in convex algebras.

Characteristics

Characteristic: Base class for characteristics in convex algebras.
Boolean: Characteristic for boolean values.
Integer: Characteristic for integer values.
Number: Characteristic for numeric values.
String: Characteristic for string values.

class Component(**data)#

Bases: Resource

Represents a component of a characteristic.

It is used to get a raw value from the item’s datum.

Parameters:

expr – A JMESPath expression for accessing values in the item’s datum
multiple – Whether the component can return multiple values (i.e., if the expression is designed to return a list of values). If False, the component will transform a single value to a list (or None if the expression does not match any values in the datum).

ALIAS#

The alias of the type in the resource registry.

Type:: ClassVar[str] = “core.Component”

Examples

>>> from galactic.algebras.concept.core import Item
>>> from galactic.algebras.convex.characteristics.core import Component
>>> component = Component(expr="value")
>>> component
Component(expr='value')
>>> print(component)
value
>>> dataset = [{"value": 5}, {}]
>>> print(component.find(Item(value=dataset[0])))
[5]
>>> print(component.find(Item(value=dataset[1])))
None

Configuration

If you want to specify a component in a TOML file, you can use the following syntax:

[components.1]
"$type" = "core.component.Component"
expr = "value"

Notes

The Component class is used to represent a single component of a characteristic.
It is designed to be used with JMESPath expressions to extract values from the item’s datum.
The find method is used to apply the JMESPath expression to the item’s datum and retrieve the values that match the expression.

Hint

The Component class is typically used as part of a Characteristic to define how to extract values from an item’s datum.

References

https://jmespath.org/specification.html for more information on JMESPath syntax
https://jmespath.org/tutorial.html for JMESPath tutorial
https://jmespath.org/examples.html for JMESPath examples

find(item)#

Find values in the item’s datum using the JMESPath expression.

Parameters:: item (Item) – The item to search for values
Returns:: A list of values found in the item’s datum that match the JMESPath expression or None if the component is unknown (i.e., if the expression does not match any values in the datum)
Return type:: list[None | bool | int | float | str | list[None | bool | int | float | str | list[JSONValue] | dict[str, JSONValue]] | dict[str, None | bool | int | float | str | list[JSONValue] | dict[str, JSONValue]]] | None

model_config: ClassVar[ConfigDict] = {'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class Characteristic(**data)#

Bases: Resource, ABC

Superclass for all characteristics.

Designed for subclassing.

A characteristic can be called on an item’s datum. It returns a value representing the characteristic of the item, similar to a mathematical function. The value is computed by calling the _call method on each component of the characteristic, where each component is defined using a JMESPath expression. Each component produces a list of values (representing imprecision). The components are combined to produce a list of tuples, which are passed as arguments to _call.

Parameters:

components – A tuple of Component objects that define how to extract values from the item’s datum
name – The name of the characteristic, used for string representation. It must be a valid Python identifier (i.e., it can only contain alphanumeric characters and underscores, and cannot start with a digit)
cache – The cache mode for the characteristic. It can be: - None: no caching - True: unlimited caching - int: maximum cache size (must be greater than or equal to 0)
replace – Whether to replace the oldest cached value when the cache is full (only applicable if cache is an integer greater than 0)

Examples

>>> from galactic.algebras.concept.core import Item
>>> from galactic.algebras.convex.characteristics.core import (
...     Component,
...     Integer,
... )
>>> component = Component(expr="value")
>>> characteristic = Integer(components=(component,))
>>> str(characteristic)
'int(value)'
>>> dataset = [
...     {"value": 1},
...     {"value": "a"},
...     {},
... ]
>>> print(characteristic(Item(value=dataset[0])))
[1]
>>> print(characteristic(Item(value=dataset[1])))
None
>>> print(characteristic(Item(value=dataset[2])))
None
>>> characteristic = Integer(components=(Component(expr="value", multiple=True),))
>>> dataset = [
...     {"value": [1.2, 2.3]},
...     {"value": [2]},
...     {"value": None},
...     {},
... ]
>>> print(characteristic(Item(value=dataset[0])))
[1, 2]
>>> print(characteristic(Item(value=dataset[1])))
[2]
>>> print(characteristic(Item(value=dataset[2])))
None
>>> print(characteristic(Item(value=dataset[3])))
None

Raises:

TypeError – If any component is not an instance of Component
ValueError – If the name is not a valid Python identifier or is not empty
ValueError – If the cache mode is an integer less than 0

Notes

The template is used by the str() method to format the string representation of the characteristic using the components and the parameters.
The components are determined by a tuple of Component objects.
The __call__ method is the main entry point to compute the characteristic on a given item. It returns a list of values representing the characteristic (or None if the characteristic is unknown).
The _call method is an abstract method that must be implemented by subclasses to define how to combine the values extracted from the components into a single value representing the characteristic.
The Boolean, Integer, Number and String characteristics are concrete implementations of the Characteristic class that represent boolean, integer, float, and string values, respectively. They provide a way to extract and convert values from the value item using JMESPath expressions and return them in the appropriate type.

__str__()#

Get a string representation of the characteristic.

Returns:: The string representation of the characteristic. If the name is not empty, it is returned as the string representation. Otherwise, the template is formatted using the components and the parameters.
Return type:: str

__call__(item)#

Make this characteristic callable.

This method should not be overridden in subclasses.

Parameters:: item (Item) – An item
Returns:: The item characteristic. The returned list represents the partial imprecision; each element of the list can be considered as an extreme point of a convex hull
Return type:: list[object] | None

cache_info()#

Get cache statistics.

Returns:: A named tuple with hits, misses, maxsize and currsize.
Return type:: CacheInfo

cache_clear()#

Clear cached values and reset cache statistics.

Return type:: None

abstract property template: str#

Get the template.

Returns:: The template
Return type:: str

model_config: ClassVar[ConfigDict] = {'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

class Boolean(**data)#

Bases: Characteristic

Represents a boolean value.

Parameters:: components (tuple[Component]) – A tuple containing a single Component that extracts the value from the item’s datum.

ALIAS#

The alias of the type in the resource registry.

Type:: ClassVar[str] = “core.characteristic.Boolean”

Examples

>>> from galactic.algebras.concept.core import Item
>>> from galactic.algebras.convex.characteristics.core import (
...     Boolean,
...     Component,
... )
>>> characteristic = Boolean(components=(Component(expr="value"),))
>>> str(characteristic)
'bool(value)'
>>> dataset = [
...     {"value": True},
...     {"value": False},
...     {"value": "a"},
...     {"value": 1},
...     {"value": 0},
...     {"value": None},
...     {"value": []},
...     {"value": [1, 2]},
...     {"value": {}},
...     {"value": {"a": 1}},
... ]
>>> print(characteristic(Item(value=dataset[0])))
[True]
>>> print(characteristic(Item(value=dataset[1])))
[False]
>>> print(characteristic(Item(value=dataset[2])))
[True]
>>> print(characteristic(Item(value=dataset[3])))
[True]
>>> print(characteristic(Item(value=dataset[4])))
[False]
>>> print(characteristic(Item(value=dataset[5])))
None
>>> print(characteristic(Item(value=dataset[6])))
[False]
>>> print(characteristic(Item(value=dataset[7])))
[True]
>>> print(characteristic(Item(value=dataset[8])))
[False]
>>> print(characteristic(Item(value=dataset[9])))
[True]

Configuration

If you want to specify an boolean characteristic in a TOML file, you can use the following syntax:

[components.my_component]
"$type" = "core.Component"
expr = "value"

[characteristics.my_characteristic]
"$type" = "core.characteristic.Boolean"
components = [
  {"$ref" = "components.my_component"}
]
name = "my_name"

Raises:: ValueError – If the components is not None and contain more than one element

Notes

The characteristic returns a list of booleans representing the truthiness of the value extracted from the datum.
If the value is None, the characteristic returns None, indicating that the truthiness is undetermined.
Empty lists and dictionaries are converted using Python truthiness rules and therefore return False.

property template: str#

Get the template.

Returns:: The template
Return type:: str

model_config: ClassVar[ConfigDict] = {'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

class Integer(**data)#

Bases: Characteristic

Represents an integer value.

Parameters:: components (tuple[Component]) – A tuple containing a single Component that extracts the value from the item’s datum.

ALIAS#

The alias of the type in the resource registry.

Type:: ClassVar[str] = “core.characteristic.Integer”

Examples

>>> from galactic.algebras.concept.core import Item
>>> from galactic.algebras.convex.characteristics.core import (
...     Integer,
...     Component,
... )
>>> characteristic = Integer(components=(Component(expr="value"),))
>>> str(characteristic)
'int(value)'
>>> dataset = [
...     {"value": 1},
...     {"value": "a"},
...     {"value": 2.5},
...     {"value": 3.0},
...     {"value": None},
...     {"value": []},
...     {"value": [1, 2]},
...     {"value": {}},
...     {"value": {"a": 1}},
... ]
>>> print(characteristic(Item(value=dataset[0])))
[1]
>>> print(characteristic(Item(value=dataset[1])))
None
>>> print(characteristic(Item(value=dataset[2])))
[2]
>>> print(characteristic(Item(value=dataset[3])))
[3]
>>> print(characteristic(Item(value=dataset[4])))
None
>>> print(characteristic(Item(value=dataset[5])))
None
>>> print(characteristic(Item(value=dataset[6])))
None
>>> print(characteristic(Item(value=dataset[7])))
None
>>> print(characteristic(Item(value=dataset[8])))
None

Configuration

If you want to specify an integer characteristic in a TOML file, you can use the following syntax:

[components.my_component]
"$type" = "core.Component"
expr = "value"

[characteristics.my_characteristic]
"$type" = "core.characteristic.Integer"
components = [
  {"$ref" = "components.my_component"}
]
name = "my_name"

Raises:: ValueError – If the components is not None and contain more than one element

Notes

The characteristic returns a list of integers representing the integer value extracted from the item’s datum.
If the value is None, an empty list, or a non-integer value, the characteristic returns None, indicating that the integer value is undetermined.
If the value is a float, it is converted to an integer by truncating the decimal part.
If the value is a string that cannot be converted to an integer, it returns None.
If the value is a list, it returns None since it cannot be converted directly to an integer.
If the value is a dictionary, it returns None since it cannot be converted directly to an integer.
If the value is a boolean, it returns 1 for True and 0 for False.
If the value is a number, it is converted to an integer.

property template: str#

Get the template.

Returns:: The template
Return type:: str

model_config: ClassVar[ConfigDict] = {'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

class Number(**data)#

Bases: Characteristic

Represents a float value.

Parameters:: components (tuple[Component]) – A tuple containing a single Component that extracts the value from the item’s datum.

ALIAS#

The alias of the type in the resource registry.

Type:: ClassVar[str] = “core.characteristic.Number”

Examples

>>> from galactic.algebras.concept.core import Item
>>> from galactic.algebras.convex.characteristics.core import (
...     Number,
...     Component,
... )
>>> characteristic = Number(components=(Component(expr="value"),))
>>> str(characteristic)
'float(value)'
>>> dataset = [
...     {"value": 1.2},
...     {"value": "a"},
...     {"value": 2},
...     {"value": 3.0},
...     {"value": None},
...     {"value": []},
...     {"value": [1.2, 2.3]},
...     {"value": {}},
...     {"value": {"a": 1}},
... ]
>>> print(characteristic(Item(value=dataset[0])))
[1.2]
>>> print(characteristic(Item(value=dataset[1])))
None
>>> print(characteristic(Item(value=dataset[2])))
[2.0]
>>> print(characteristic(Item(value=dataset[3])))
[3.0]
>>> print(characteristic(Item(value=dataset[4])))
None
>>> print(characteristic(Item(value=dataset[5])))
None
>>> print(characteristic(Item(value=dataset[6])))
None
>>> print(characteristic(Item(value=dataset[7])))
None
>>> print(characteristic(Item(value=dataset[8])))
None

Configuration

If you want to specify an number characteristic in a TOML file, you can use the following syntax:

[components.my_component]
"$type" = "core.Component"
expr = "value"

[characteristics.my_characteristic]
"$type" = "core.characteristic.Number"
components = [
  {"$ref" = "components.my_component"}
]
name = "my_name"

Raises:: ValueError – If the components is not None and contain more than one element

Notes

The characteristic returns a list of floats representing the float value extracted from the item’s datum.
If the value is None, an empty list, or a non-float value, the characteristic returns None, indicating that the float value is undetermined.
If the value is a string that cannot be converted to a float, it returns None.
If the value is a list, it returns None since it cannot be converted directly to a float.
If the value is a dictionary, it returns None since it cannot be converted directly to a float.
If the value is a boolean, it returns 1.0 for True and 0.0 for False.
If the value is an integer, it is converted to a float.

property template: str#

Get the template.

Returns:: The template
Return type:: str

model_config: ClassVar[ConfigDict] = {'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

class String(**data)#

Bases: Characteristic

Represents a string value.

Parameters:: components (tuple[Component]) – A tuple containing a single Component that extracts the value from the item’s datum.

ALIAS#

The alias of the type in the resource registry.

Type:: ClassVar[str] = “core.characteristic.String”

Examples

>>> from galactic.algebras.concept.core import Item
>>> from galactic.algebras.convex.characteristics.core import (
...     String,
...     Component,
... )
>>> characteristic = String(components=(Component(expr="value"),))
>>> str(characteristic)
'str(value)'
>>> dataset = [
...     {"value": "hello"},
...     {"value": 123},
...     {"value": None},
...     {"value": []},
...     {"value": {}},
...     {"value": {"a": 1}},
... ]
>>> print(characteristic(Item(value=dataset[0])))
['hello']
>>> print(characteristic(Item(value=dataset[1])))
['123']
>>> print(characteristic(Item(value=dataset[2])))
None
>>> print(characteristic(Item(value=dataset[3])))
['[]']
>>> print(characteristic(Item(value=dataset[4])))
['{}']
>>> print(characteristic(Item(value=dataset[5])))
["{'a': 1}"]

Configuration

If you want to specify an string characteristic in a TOML file, you can use the following syntax:

[components.my_component]
"$type" = "core.Component"
expr = "value"

[characteristics.my_characteristic]
"$type" = "core.characteristic.String"
components = [
  {"$ref" = "components.my_component"}
]
name = "my_name"

Raises:: ValueError – If the components is not None and contain more than one element

Notes

The characteristic returns a list of strings representing the string value extracted from the item’s datum.
If the value is None, the characteristic returns None, indicating that the string value is undetermined.
If the value is a number, it is converted to a string.
If the value is a list, it is converted to a string representation of the list.
If the value is a dictionary, it is converted to a string representation of the dictionary.
If the value is a boolean, it is converted to a string representation of the boolean (‘True’ or ‘False’).
If the value is a string, it is returned as-is.

property template: str#

Get the template.

Returns:: The template
Return type:: str

model_config: ClassVar[ConfigDict] = {'validate_assignment': True}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

galactic.algebras.convex.characteristics.core

Contents

galactic.algebras.convex.characteristics.core#