core module

This module defines some core classes used elsewhere in the package. These include classes to represent yield curves and dynamcic programming state trees.

class core.Curve(label: str | None = None, id: str | None = None, is_volume: bool = False, points: list[tuple[int, float]] | None = None, type: str = 'a', is_special: bool = False, period_length: float = 10, xmin: int = 0, xmax: int = 1000, epsilon: float = 0.01, simplify: bool = True)[source]

Bases: object

Describes change in state over time (between treatments).

Parameters:

  • label – A label for the curve.

  • id – An ID for the curve.

  • is_volume – Flag indicating whether the curve tracks volume. Defaults to False.

  • points – A list of (x,y) pairs defining the curve.

  • type – A string indicating the type of curve. Defaults to 'a'.

  • is_special – Flag indicating whether the curve is special. Defaults to False. Special curves are immune to simplification.

  • period_length – The length of the period. Defaults to ws3.common.PERIOD_LENGTH_DEFAULT.

  • xmin – The minimum age. Defaults to ws3.common.MIN_AGE_DEFAULT.

  • xmax – The maximum age. Defaults to ws3.common.MAX_AGE_DEFAULT.

  • epsilon – The tolerance for simplifying the curve. Defaults to ws3.common.CURVE_EPSILON_DEFAULT.

  • simplify – Flag indicating whether to simplify the curve. Defaults to True.

add_points(points: list[tuple[int, float]], simplify: bool = True, compile_y: bool = False) → None[source]

Adds points to the curve and optionally simplifies point geometry.

Parameters:

  • points – The points to add to the curve.

  • simplify – Flag indicating whether to simplify the curve after adding points. Defaults to True.

  • compile_y – Flag indicating whether to compile the y-component after adding points. Defaults to False.

cai() → Curve[source]

Calculates a current annual increment (CAI) curve.

Returns:

A curve representing the current annual increment.

Return type:

Curve

epsilon: float
id: str | None
interp: Interpolator
is_locked: bool
is_special: bool
is_volume: bool
label: str | None
lookup(y: float, from_right: bool = False, roundx: bool = False) → int[source]

Looks up the x-coordinate corresponding to the given y-coordinate.

Parameters:

  • y – The y-coordinate to look up.

  • from_right – Flag indicating whether to search from the right. Defaults to False.

  • roundx – Flag indicating whether to round the x-coordinate to the nearest integer. Defaults to False.

Returns:

The x-coordinate corresponding to the given y-coordinate.

mai() → Curve[source]

Calculates a mean annual increment (MAI) curve.

Returns:

A curve representing the mean annual increment.

Return type:

Curve

period_length: float
points() → list[tuple[int, float]][source]
Returns:

List of curve points.

range(lo: float | None = None, hi: float | None = None, as_bounds: bool = False, left_range: bool = True) → Curve | tuple[int, int][source]

Returns a Curve representing the range within the specified bounds.

Parameters:

  • lo – The lower bound of the range. Defaults to None.

  • hi – The upper bound of the range. Defaults to None.

  • as_bounds – Flag indicating whether to return the range as a tuple of bounds. Defaults to False.

  • left_range – Flag indicating whether to look up the upper bound from the left (default) or from the right (widest possible range).

Returns:

Returns either curve representing the range within the specified bounds, or a tuple representing lower- and upper-bound values (if as_bounds set to True).

Return type:

Curve or tuple

simplify(points: list[tuple[int, float]] | None = None, autotune: bool = True, compile_y: bool = False, verbose: bool = False) → None[source]

Simplifies the curve by removing redundant points.

Parameters:

  • points – The points to simplify. Defaults to None.

  • autotune – Flag indicating whether to automatically tune the simplification process. Defaults to True.

  • compile_y – Flag indicating whether to compile the y-component. Defaults to False.

  • verbose – Flag indicating whether to print verbose output. Defaults to False.

type: str
x: range | list[int]
xmax: int
xmin: int
y(compile_y: bool = False) → list[float][source]

Returns the y-values of the curve stored in self._y (will first compile them if compile_y is set to True and self._y is empty), else will interpolate a list of y values for each x value in self.x.

Parameters:

compile_y – Flag indicating whether to compile the y-component of the curve. Defaults to False.

Returns:

A list of y values.

ytp() → Curve[source]

Returns a years-to-peak (YTP) curve. This curve is a measure of how many years it takes for the curve to reach its peak (positive values to the left of the peak, and negative values to the right of the peak). :return: A curve representing the years to peak. :rtype: Curve

class core.Interpolator(points: list[tuple[int, float]])[source]

Bases: object

Interpolates x and y values from sparse curve point list.

Used by the ws3.core.Curve class to interpolate between real data points.

Parameters:

points – A list of (x,y) coordinate pairs.

lookup(y: float, from_right: bool = False) → float[source]

Looks up the x-coordinate corresponding to the given y-coordinate.

Parameters:

  • y – The y-coordinate to look up.

  • from_right – Flag indicating whether to search from the right. Defaults to False.

Returns:

The x-coordinate corresponding to the given y-coordinate.

m: list[float]
n: int
points() → list[tuple[int, float]][source]

Returns the points as a list of tuples representing the points.

Returns:

A list of (x, y) coordinate pairs.

x: list[float]
y: list[float]
class core.Node(nid, data=None, parent=None)[source]

Bases: object

A node class representing a state in a dynamic programming state tree.

The constructor for a node class.

Parameters:

  • nid – The unique ID of this node

  • data – The data stored in this node

  • parent – The parent of this node

add_child(child: int) → None[source]

The function adds a child node to the current object.

:param ws3.core.Node child: The child node to be added.

children()[source]

The function gets the list of child nodes of the current object.

Returns:

List of child nodes.

Return type:

list of ws3.core.Node objects.

data(key=None)[source]

The function gets the data associated with the current object. If a specific key is provided, return the corresponding value. If no key is provided, return the entire data dictionary.

Parameters:

key – The key to retrieve a specific value (default is None).

Returns:

The data associated with the key if a key is specified (or the entire data dictionary if a key is not specified).

is_leaf() → bool[source]

Checks if the current object is a leaf node (i.e., node has no children).

Returns:

True if the object is a leaf node, False otherwise.

Return type:

bool

is_root() → bool[source]

Check if the current object is the root node.

Returns:

True if the object is the root node, False otherwise.

Return type:

bool

parent() → int[source]

The function gets the parent node of the current object.

Returns:

The parent node.

Return type:

ws3.core.Node

class core.Tree(period=1)[source]

Bases: object

Represents a tree object.

add_node(data: Any, parent: int | None = None) → Node[source]

Adds a new node to the tree.

Parameters:

  • data – The data associated with the new node.

  • parent – The parent node to which the new node will be attached.

Returns:

The newly created node.

Return type:

ws3.core.Node

children(nid)[source]

The function gets the child nodes of the node with the specified ID.

Parameters:

nid – The ID of the node for which to retrieve children.

Returns:

List of child nodes.

Return type:

list of ws3.core.Node objects.

grow(data)[source]

Expands the current path by adding a new child node. The new node is added as a child of the last node in the current path. The current path used by the optimization problem formulation functions to iterate over all possible states (in a depth-first-search pattern).

Parameters:

data – The data associated with the new node.

Returns:

The newly created node.

Return type:

ws3.core.Node

leaves() → list[Node][source]

Returns all leaf nodes.

Returns:

A list of all leaf nodes.

Return type:

list of ws3.core.Node objects

node(nid: int) → Node[source]

Returns a node with the specified ID.

Parameters:

nid – The unique identifier of the node to be retrieved.

Returns:

The node object corresponding to the specified ID.

Return type:

ws3.core.Node

nodes() → list[Node][source]

Returns all nodes in the tree. :returns: List of all nodes in the tree. :rtype: list of ws3.core.Node objects.

path(leaf: Node | None = None) → tuple[Node, ...][source]

Retrieves the path from the root to a specific leaf node or to the current path.

Parameters:

leaf – The leaf node for which the path is to be retrieved. Default is None (which returns the current path).

Returns:

a path

Return type:

tuple of ws3.core.Node objects

paths() → list[tuple[Node, ...]][source]

Retrieves paths from the root to all leaf nodes.

Returns:

A list of paths from the root to all leaf nodes.

Return type:

list of tuples of ws3.core.Node objects

root()[source]

Returns the root node.

Returns:

The root node.

Return type:

ws3.core.Node

ungrow()[source]

Reduces the current path by removing the last node.