BoolXAI Public API

boolxai

class boolxai.boolxai.BoolXAI[source]

Bases: object

class BaselineClassifier(metric: ~typing.Callable = <function balanced_accuracy_score>)[source]

Bases: BaselineClassifier

__init__(metric: ~typing.Callable = <function balanced_accuracy_score>)

Instantiates a classifier based on the best trivial/single-feature rule.

Parameters:: metric (callable, optional) – An sklearn-style metric function, see sklearn.metrics, used internally to score rules during training. Note: make sure to use the same metric for any external evaluation of the model, for example in cross-validation. Defaults to balanced_accuracy_score.

fit(X: ndarray, y: ndarray, sample_weight: ndarray | None = None) → BaselineClassifier

Finds the best simple rule exhaustively for training data X and labels y.

Note: calling fit() populates the best_rule_ and best_score_ attributes.

get_params(deep=True)

Get parameters for this estimator.

Parameters:: deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns:: params – Parameter names mapped to their values.
Return type:: dict

predict(X: ndarray) → ndarray

Generates predictions for X with self.best_rule_.

Parameters:: X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
Returns:: A one-dimensional Boolean ndarray. Each value corresponds to the evaluation of the rule on the respective data row.
Return type:: np.ndarray

score(X: ndarray, y: ndarray, sample_weight: ndarray | None = None) → float

Generates predictions for X with best_rule_ and returns their score vs. y.

Note

The metric used to calculate the score is the one in the metric attribute.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
y (np.ndarray) – A label for each sample in the input data. Expected to be binary (i.e., 0/1/False/True).
sample_weight (np.ndarray, optional) – A weight for each sample or None for equal sample weights. Defaults to None.

Returns:

The score of the rule in the best_rule_ attribute, given the metric in the metric attribute.

Return type:

float

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:: **params (dict) – Estimator parameters.
Returns:: self – Estimator instance.
Return type:: estimator instance

class RuleClassifier(max_complexity: int | None = 6, max_depth: int | None = 3, operators: ~boolxai.classifiers.rule_classifier.AllOperatorType = [<class 'boolxai.rules.operators.Operator.And'>, <class 'boolxai.rules.operators.Operator.Or'>, <class 'boolxai.rules.operators.Operator.AtMost'>, <class 'boolxai.rules.operators.Operator.AtLeast'>, <class 'boolxai.rules.operators.Operator.Choose'>], num_iterations: int = 500, num_starts: int = 10, max_samples: int | None = 2000, temp_high: float = 0.2, temp_low: float = 1e-06, regularization: float = 0.0001, metric: ~typing.Callable = <function balanced_accuracy_score>, random_state: int | ~numpy.random.mtrand.RandomState | None = None, num_jobs: int = -1, baseline: bool = True, base_rule: ~boolxai.rules.operators.Operator | None = None, postprocess: bool = True, on_start: ~typing.Callable | None = None, on_iteration: ~typing.Callable | None = None)[source]

Bases: RuleClassifier

__init__(max_complexity: int | None = 6, max_depth: int | None = 3, operators: ~boolxai.classifiers.rule_classifier.AllOperatorType = [<class 'boolxai.rules.operators.Operator.And'>, <class 'boolxai.rules.operators.Operator.Or'>, <class 'boolxai.rules.operators.Operator.AtMost'>, <class 'boolxai.rules.operators.Operator.AtLeast'>, <class 'boolxai.rules.operators.Operator.Choose'>], num_iterations: int = 500, num_starts: int = 10, max_samples: int | None = 2000, temp_high: float = 0.2, temp_low: float = 1e-06, regularization: float = 0.0001, metric: ~typing.Callable = <function balanced_accuracy_score>, random_state: int | ~numpy.random.mtrand.RandomState | None = None, num_jobs: int = -1, baseline: bool = True, base_rule: ~boolxai.rules.operators.Operator | None = None, postprocess: bool = True, on_start: ~typing.Callable | None = None, on_iteration: ~typing.Callable | None = None)

A simulated annealing native local classifier.

Local moves change only a very localized part of the current rule - typically only one or two subrules.

Notes:

In order to see intermediate logged information set the logging level to logger.DEBUG, for example by setting up the root logger like so: logging.basicConfig(level=logging.DEBUG). However, note that logging can significantly slow the code, and that most logging messages will only appear if num_jobs=1.
The computational effort is largely controlled by the product of num_starts and num_iterations divided by num_jobs. For large datasets, max_samples can reduce the computational effort (via a form of bagging).

Parameters:

max_complexity (int, optional) – Maximum allowed complexity - must be 3 or more. Defaults to 6. To impose no maximum complexity, pass in None.
max_depth (int, optional) – Maximum allowed depth - must be 1 or more. Defaults to 3. To impose no maximum depth, pass in None.
operators (list, optional) – List of operator classes to include when generating solutions or moves. Defaults to all_operator_classes.
num_iterations (int, optional) – Number of iterations = moves to propose. Defaults to 500.
num_starts (int, optional) – Number of independent starts (runs). Defaults to 10.
max_samples (int, optional) – Maximum number of samples from the input data X passed to fit() to use in each start. If None or if it is smaller than the number of samples, all samples will be used. Otherwise, will populate best_rule_ with the rule with the highest regularized score based on all samples, not just the smaller sample used in training, and will similarly populate scores_ with the (unregularized) scores calculated on all samples.
temp_high (float, optional) – High temperature (exploration) in geometric temperature schedule. Defaults to 0.2.
temp_low (float, optional) – Low temperature (exploitation) in geometric temperature schedule. Defaults to 0.000001.
regularization (float, optional) – Controls the strength of the complexity term in the objective function = metric - regularization * complexity. Defaults to 0.0001. To turn off regularization pass in 0.
metric (callable, optional) – An sklearn-style metric function, see sklearn.metrics, used internally to score rules during training. Note: make sure to use the same metric for any external evaluation of the model, for example in cross-validation. Defaults to balanced_accuracy_score.
random_state (int or RandomState, optional) – random number generator that selects a random sample. Pass an int for reproducible output across multiple function calls. Defaults to None which uses the RandomState singleton used by np.random.
num_jobs (int, optional) – Number of simultaneous jobs to use for multiprocessing over starts. Pass in -1 to use the number of CPUs. Defaults to -1.
baseline (bool, optional) – Whether to include the best trivial or single-feature rules. If this baseline rule has a higher regularized score than the best rule found by the solver, the former will be returned for each start. Defaults to True.
base_rule (Operator, optional) – Used to optimize part of a rule. Pass in the (user-defined) rule that will be held fixed as base_rule. The base_rule should include exactly one Wildcard rule, which cannot be at the root. The classifier will then optimize the subtree under the Wildcard, while keeping the rest of the base_rule fixed. Note that if base_rule is passed in, max_complexity and max_depth still constrain the full resulting rules (and not just the part being optimized over).
postprocess (bool, optional) – Whether to post-process the rules found by the solver to simplify them. Defaults to True.
on_start (callable, optional) – Callback function that is executed at the beginning of each start, after initialization. Called within the code as on_start(locals(), globals()). Defaults to None.
on_iteration (callable, optional) – Callback function that is executed at the end of each iteration. Can return True to exit the iteration loop for the current start. Called within the code as on_iteration(locals(), globals()). Defaults to None.

decision_function(X: ndarray) → ndarray

Returns a “soft” score for each sample in X.

Note: in our case, we simply return the same result as when calling predict(). We only implement this method since it is required for some higher-level ensemble models in sklearn.

fit(X: ndarray, y: ndarray, sample_weight: ndarray | None = None) → RuleClassifier

Finds the best rule for training data X and labels y.

Note: populates the best_rule_ and best_score_ attributes, as well as the rules_ and scores_ attributes, which contain a rule and score (respectively) for each start.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
y (np.ndarray) – A label for each sample in the input data. Expected to be binary (i.e., 0/1/False/True).
sample_weight (np.ndarray, optional) – A weight for each sample or None for equal sample weights. Defaults to None.

Returns:

Returns the classifier object - useful for chaining.

Return type:

RuleClassifier

get_params(deep=True)

Get parameters for this estimator.

Parameters:: deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns:: params – Parameter names mapped to their values.
Return type:: dict

predict(X: ndarray) → ndarray

Generates predictions for X with self.best_rule_.

Parameters:: X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
Returns:: A one-dimensional Boolean ndarray. Each value corresponds to the evaluation of the rule on the respective data row.
Return type:: np.ndarray

score(X: ndarray, y: ndarray, sample_weight: ndarray | None = None) → float

Generates predictions for X with best_rule_ and returns their score vs. y.

Note: the metric used to calculate the score is the one in the metric attribute.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
y (np.ndarray) – A label for each sample in the input data. Expected to be binary (i.e., 0/1/False/True).
sample_weight (np.ndarray, optional) – A weight for each sample or None for equal sample weights. Defaults to None.

Returns:

The score of the rule in the best_rule_ attribute, given the metric in the metric attribute.

Return type:

float

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:: **params (dict) – Estimator parameters.
Returns:: self – Estimator instance.
Return type:: estimator instance

util

boolxai.util.check_binary(data: ndarray, error: bool = True) → bool[source]

Checks if all elements in data are binary.

Note: it’s usually preferred to pass in only the unique elements, for example via a call to np.unique().

rules

literal

class boolxai.rules.literal.Literal(index: int, negated: bool = False)[source]

Bases: Rule

A Literal is a feature, possibly negated.

__init__(index: int, negated: bool = False)[source]

Initializes a literal.

Parameters:

index (int) – The feature index that this literal corresponds to.
negated (bool, optional) – True if this literal is negated. Defaults to False.

to_dict(feature_names=None) → dict[source]: Returns dict rule, not implemented for literals.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

operators

class boolxai.rules.operators.UnparametrizedOperator(subrules: List[Operator | Literal], negated: bool = False)[source]

Bases: Rule

An UnparametrizedOperator operates on subrules, can be negated.

__init__(subrules: List[Operator | Literal], negated: bool = False)[source]

Initializes the operator.

Parameters:

subrules (list) – A list of rules that will be children of this new operator.
negated (bool, optional) – True if this operator is negated. Defaults to False.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class boolxai.rules.operators.ParametrizedOperator(subrules: List[Operator | Literal], param: int, negated: bool = False)[source]

Bases: Rule

A ParametrizedOperator operates on subrules, can be negated, has a parameter.

__init__(subrules: List[Operator | Literal], param: int, negated: bool = False)[source]

Initializes the operator.

Parameters:

subrules (list) – A list of rules that will be children of this new operator.
param (int) – An additional integer parameter for this operator.
negated (bool, optional) – True if this operator is negated. Defaults to False.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class boolxai.rules.operators.Operator[source]

Bases: object

An Operator is a rule with two or more subrules and an optional integer param.

Note: can be negated.

class And(subrules: List[Operator | Literal], negated: bool = False)[source]

Bases: UnparametrizedOperator

Returns True if all subrules are True.

__init__(subrules: List[Operator | Literal], negated: bool = False)

Initializes the operator.

Parameters:

subrules (list) – A list of rules that will be children of this new operator.
negated (bool, optional) – True if this operator is negated. Defaults to False.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class Or(subrules: List[Operator | Literal], negated: bool = False)[source]

Bases: UnparametrizedOperator

Returns True if at least one subrule is True.

__init__(subrules: List[Operator | Literal], negated: bool = False)

Initializes the operator.

Parameters:

subrules (list) – A list of rules that will be children of this new operator.
negated (bool, optional) – True if this operator is negated. Defaults to False.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class AtMost(subrules: List[Operator | Literal], param: int, negated: bool = False)[source]

Bases: ParametrizedOperator

Returns True if at most param subrules are True.

__init__(subrules: List[Operator | Literal], param: int, negated: bool = False)

Initializes the operator.

Parameters:

subrules (list) – A list of rules that will be children of this new operator.
param (int) – An additional integer parameter for this operator.
negated (bool, optional) – True if this operator is negated. Defaults to False.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class AtLeast(subrules: List[Operator | Literal], param: int, negated: bool = False)[source]

Bases: ParametrizedOperator

Returns True if at least param subrules are True.

__init__(subrules: List[Operator | Literal], param: int, negated: bool = False)

Initializes the operator.

Parameters:

subrules (list) – A list of rules that will be children of this new operator.
param (int) – An additional integer parameter for this operator.
negated (bool, optional) – True if this operator is negated. Defaults to False.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class Choose(subrules: List[Operator | Literal], param: int, negated: bool = False)[source]

Bases: ParametrizedOperator

Returns True if exactly param subrules are True.

__init__(subrules: List[Operator | Literal], param: int, negated: bool = False)

Initializes the operator.

Parameters:

subrules (list) – A list of rules that will be children of this new operator.
param (int) – An additional integer parameter for this operator.
negated (bool, optional) – True if this operator is negated. Defaults to False.

complexity() → int: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

trivials

class boolxai.rules.trivials.Trivial[source]

Bases: Rule

A Trivial rule evaluates to a constant.

__init__()[source]

to_dict(feature_names: Dict[str, int] | None = None) → dict[source]

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

complexity()[source]: Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class boolxai.rules.trivials.Zero[source]

Bases: Trivial

A Zero rule evaluates to zero always.

__init__()

complexity(): Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class boolxai.rules.trivials.One[source]

Bases: Trivial

A One rule evaluates to one always.

__init__()

complexity(): Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str

class boolxai.rules.trivials.Wildcard[source]

Bases: Trivial

A Wildcard rule cannot be evaluated - it is used for marking purposes only.

__init__()

complexity(): Calculates and returns the complexity of this rule.

depth() → int: Calculates and returns the depth of this rule.

evaluate(X: ndarray, check: bool = True) → ndarray

Evaluates this rule on data X, returns a one-dimensional Boolean ndarray.

Parameters:

X (np.ndarray) – Input data - each row is a sample. Expected to be binary (i.e., 0/1/False/True).
check (bool, optional) – If True, check validity of inputs. Defaults to True.

Returns:

A one-dimensional Boolean array. Each value corresponds to the evaluation of the rule on the respective data row.

Return type:

np.ndarray

flatten() → list: Returns a flattened list including this rule and all child rules.

Plots this rule.

Parameters:

feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
filename (str) – Path where the plot should be saved. The format will be inferred from the extension. Pass in None to plot the figure on the screen instead of to a file. The latter currently only supports plotting within a Jupyter notebook. Defaults to None.
graph_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().graph_attr. If None is passed in, the default values are used.
node_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().node_attr. If None is passed in, the default values are used.
edge_attr (dict, optional) – Mapping from attribute name to value, which will update the default values of AGraph().edge_attr. If None is passed in, the default values are used.

to_dict(feature_names: Dict[str, int] | None = None) → dict

Returns dict rule, optionally replacing indices with feature names.

Operators are represented as a dictionary from the name of the operator to a list of subrules. Literals are represented as a string. These definitions are used recursively to return a dict representing the full rule.

Note: to_dict() is undefined, and hence not implemented, for literals and trivial rules.

Example

>>> from boolxai import Operator, Literal
>>> x0 = Literal(0)
>>> x1 = Literal(1)
>>> x2 = Literal(2)
>>> rule = Operator.AtMost([Operator.And([x0, x1]), ~Operator.Or([x0, ~x2])], param=1)
>>> rule.to_dict()
{'AtMost1': [{'And': ['0', '1']}, {'~Or': ['0', '~2']}]}
>>> rule.to_dict({0:"a", 1:"b", 2:"c"})
{'AtMost1': [{'And': ['a', 'b']}, {'~Or': ['a', '~c']}]}

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A dict representation of the rule.
Return type:: dict

to_graph(feature_names: Dict[str, int] | None = None)

Returns a NetworkX directed graph representing this rule.

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: A NetworkX directed graph representing this rule.
Return type:: nx.DiGraph

to_str(feature_names: Dict[int, str] | List[str] | None = None) → str

Returns string rule, optionally replacing indices with feature names.

Example

>>> from boolxai import Operator, Literal
>>> rule = Operator.AtMost([Literal(0), Literal(1, negated=True)], param=1)
>>> rule.to_str()
"AtMost1(0, ~1)"
>>> rule.to_str({0:"a", 1:"b"})
"AtMost1(a, ~b)"

Parameters:: feature_names (dict or list, optional) – Feature names for each index. Can be provided as a dict, in which case the key is the index and the value is the feature name. Alternatively, a list of feature names can be passed in, such that the index in the list is the respective index of each feature. If None is passed in, the indices are used in the rule.
Returns:: String representation of the rule.
Return type:: str