decision_rules.core

decision_rules.core.condition

Contains base abstract condition class

class decision_rules.core.condition.AbstractCondition

Bases: ABC

Abstract class for logical conditions specifying their public interface. Every conditions class should extend this class.

abstract property attributes: frozenset[int]

Returns: frozenset[int]: condition attributes

cache(recursive: bool = False)

Caches condition covered and uncovered examples masks to prevent their recalculation. It automatically enable cache for all condition’s subconditions.

Examples

>>> with condition.cache()
>>>     covered_mask = condition.covered_mask(X)
>>>     ...
Yields:

None – none

covered_mask(X: ndarray) → ndarray

Calculates covered examples mask

Parameters:

X (np.ndarray)

Returns:

1 dimensional numpy array of booleans specifying

whether given examples is covered by a condition or not.

Return type:

np.ndarray

invalidate_cache()

Disable covered and uncovered examples masks cache.

abstract to_string(columns_names: list[str]) → str
Parameters:

columns_names (list[str])

Returns:

condition string representation

Return type:

str

uncovered_mask(X: ndarray) → ndarray

Calculates uncovered examples mask - negation of covered mask

See also

conditions.conditions.AbstractCondition.covered_mask

Args

X (np.ndarray)

Returns

np.ndarray

1 dimensional numpy array of booleans specifying whether given examples is uncovered by a condition or not.

decision_rules.core.coverage

Contains rule coverage class

class decision_rules.core.coverage.ClassificationCoverageInfodict

Bases: TypedDict

N: int
P: int
n: int
p: int
class decision_rules.core.coverage.Coverage(p: int, n: int, P: int, N: int)

Bases: object

Rule coverage

N: int

All negative examples.

P: int

All positive examples.

as_tuple() → tuple[int, int, int, int]
n: int

Negative covered examples.

p: int

Positive covered examples.

exception decision_rules.core.coverage.InvalidCoverageError

Bases: ValueError

class decision_rules.core.coverage.RegressionCoverageInfodict

Bases: ClassificationCoverageInfodict

N: int
P: int
n: int
p: int
train_covered_y_mean: float
train_covered_y_std: float
class decision_rules.core.coverage.SurvivalCoverageInfodict

Bases: ClassificationCoverageInfodict

N: int
P: int
censored_count: int
events_count: int
kaplan_meier_estimator: dict[str, list[float]]
log_rank: float
median_sruvival_time_cli: float
median_survival_time: float
n: int
p: int
restricted_mean_survival_time: float

decision_rules.core.exceptions

exception decision_rules.core.exceptions.InvalidStateError

Bases: Exception

Error indicating that object in in a wrong state to perform certain operation.

Parameters:

Exception (_type_) – _description_

decision_rules.core.metrics

Contains base abstract class for calculating rules metrics.

class decision_rules.core.metrics.AbstractRulesMetrics(rules: list[AbstractRule])

Bases: ABC

Abstract class for rules metrics calculations. All classes calculating metrics for different types of rulesets should inherit this class.

Parameters:

ABC (_type_)

calculate(X: DataFrame, y: Series, metrics_to_calculate: list[str] | None = None) → dict[str, dict[str, float]]

Calculates rules metrics for all rules

Parameters:

  • X (pd.DataFrame)

  • y (pd.Series)

  • metrics_to_calculate (Optional[list[str]], optional) – Optional parameter for specifying which metrics to calculate. By default it will calculate all supported metrics.

Raises:

ValueError – when trying to calculate unsupported metric.

Returns:

Dictionary of metrics where keys are rules uuids

and values are dictionaries containing metrics values for this rules.

Return type:

dict[str, dict[str, float]]

abstract calculate_p_value(coverage: Coverage | None = None, rule: AbstractRule | None = None, y: ndarray | None = None) → float

Abstract method to calculate p-value

Parameters:

  • coverage (Optional[Coverage], optional) – Coverage object for classification rules. Defaults to None.

  • rule (Optional[RegressionRule], optional) – The rule from regression ruleset for which p-value is to be calculated.. Defaults to None.

  • y (Optional[np.ndarray], optional) – Target labels for regression rules. Defaults to None.

abstract get_metrics_calculator(rule: AbstractRule, X: DataFrame, y: Series) → dict[str, Callable[[], Any]]

Returns metrics calculator object in a form of dictionary where values are the non-parmetrized callables calculating specified metrics and keys are the names of those metrics.

Examples

>>> {
>>>  'p': lambda: rule.coverage.p,
>>>  'n': lambda: rule.coverage.n,
>>>  'P': lambda: rule.coverage.P,
>>>  'N': lambda: rule.coverage.N,
>>>  'coverage': lambda: measures.coverage(rule.coverage),
>>>  ...
>>> }
Parameters:

  • rule (AbstractRule) – rule

  • X (pd.DataFrame) – data

  • y (pd.Series) – labels

Returns:

metrics calculator object

Return type:

dict[str, Callable[[], Any]]

abstract property supported_metrics: list[str]

Returns: list[str]: list of names of all supported metrics

decision_rules.core.prediction

class decision_rules.core.prediction.BestRulePredictionStrategy(rules: list[AbstractRule], default_conclusion: AbstractConclusion)

Bases: PredictionStrategy

Best rule prediction strategy for prediction.

class decision_rules.core.prediction.FirstRuleCoveringStrategy(rules: list[AbstractRule], default_conclusion: AbstractConclusion)

Bases: PredictionStrategy

First rule prediction strategy for prediction. It selects the first rule from a set of rules that that covers the given examples and uses it to get the predicted value

class decision_rules.core.prediction.PredictionStrategy(rules: list[AbstractRule], default_conclusion: AbstractConclusion)

Bases: ABC

Prediction strategy interface. By subclassing it you can implement custom prediction strategies. You have to implement _perform_prediction method.

predict(coverage_matrix: ndarray) → ndarray

Predicts for given dataset.

Parameters:

coverage_matrix (np.ndarray) – coverage matrix. See “AbstractRuleSet.calculate_coverage_matrix” for more details.

Returns:

predictions

Return type:

np.ndarray

decision_rules.core.rule

Contains abstract rule and conclusion classes.

class decision_rules.core.rule.AbstractConclusion(value: Any, column_name: str)

Bases: ABC

Abstract decision rule’s conclusion.

Parameters:

ABC (_type_) – _description_

abstract is_empty() → bool

Returns whether conclusion is empty or not.

abstract static make_empty(column_name: str) → AbstractConclusion

Creates empty conclusion. Use it when you don’t want to use default conclusion during prediction.

Parameters:

column_name (str) – decision column name

Returns:

empty conclusion

Return type:

AbstractConclusion

negatives_mask(y: ndarray) → ndarray

Calculates negatives examples mask - negation of positives mask

Parameters:

y (np.ndarray)

Returns:

1 dimensional numpy array of booleans specifying

whether given examples are inconsistent with the conclusion.

Return type:

np.ndarray

abstract positives_mask(y: ndarray) → ndarray

Calculates positive examples mask

Parameters:

y (np.ndarray)

Returns:

1 dimensional numpy array of booleans specifying

whether given examples are consistent with the conclusion.

Return type:

np.ndarray

class decision_rules.core.rule.AbstractRule(premise: AbstractCondition, conclusion: AbstractConclusion, column_names: list[str])

Bases: ABC

Abstract decision rule.

Parameters:

ABC (_type_) – _description_

calculate_coverage(X: ndarray, y: ndarray = None, P: int = None, N: int = None) → Coverage
Parameters:

  • X (np.ndarray)

  • y (np.ndarray, optional) – if None then P and N params should be passed. Defaults to None.

  • P (int, optional) – optional number of all examples from rule decison class. Defaults to None.

  • N (int, optional) – optional number of all examples not from rule decison class. Defaults to None.

Raises:

ValueError – if y is None and either P or N is None too

Returns:

rule coverage

Return type:

Coverage

get_coverage_dict() → dict
negative_covered_mask(X: ndarray, y: ndarray) → ndarray

Calculates negative covered examples mask.

Parameters:

  • X (np.ndarray)

  • y (np.ndarray)

Returns:

1 dimensional numpy array of booleans specifying

whether given examples is negative and covered by a rule or not

Return type:

np.ndarray

negative_uncovered_mask(X: ndarray, y: ndarray) → ndarray

Calculates negative uncovered examples mask (negation of positive_uncovered_mask)

Parameters:

  • X (np.ndarray)

  • y (np.ndarray)

Returns:

1 dimensional numpy array of booleans specifying

whether given examples is negative and uncovered by a rule or not

Return type:

np.ndarray

positive_covered_mask(X: ndarray, y: ndarray) → ndarray

Calculates positive covered examples mask.

Parameters:

  • X (np.ndarray)

  • y (np.ndarray)

Returns:

1 dimensional numpy array of booleans specifying

whether given examples is positive and covered by a rule or not

Return type:

np.ndarray

positive_uncovered_mask(X: ndarray, y: ndarray) → ndarray

Calculates positive uncovered examples mask (negation of positive_covered_mask)

Parameters:

  • X (np.ndarray)

  • y (np.ndarray)

Returns:

1 dimensional numpy array of booleans specifying

whether given examples is positive and uncovered by a rule or not

Return type:

np.ndarray

property uuid: str

Rule uuid

Returns:

rule uuid

Return type:

str

decision_rules.core.ruleset

Contains abstract ruleset class.

class decision_rules.core.ruleset.AbstractRuleSet(rules: list[AbstractRule])

Bases: _PredictionModel, ABC

Abstract ruleset allowing to perform prediction on data

abstract calculate_attribute_importances(condition_importances: dict[str, float] | dict[str, dict[str, float]]) → dict[str, float] | dict[str, dict[str, float]]

Calculate importances of attriubtes in RuleSet based on conditions importances

Parameters:

  • Union[dict[str (condition_importances) – condition importances

  • float] – condition importances

  • dict[str – condition importances

  • dict[str – condition importances

  • float]]] – condition importances

Returns:

attribute importances, in the case of classification additionally

returns information about class dict[str, dict[str, float]]:

Return type:

dict[str, float]

abstract calculate_condition_importances(X: DataFrame, y: Series, measure: Callable[[Coverage], float]) → dict[str, float] | dict[str, dict[str, float]]

Calculate importances of conditions in RuleSet

Parameters:

  • X (pd.DataFrame)

  • y (pd.Series)

  • measure (Callable[[Coverage], float]) – measure used to count importance

Returns:

condition importances, in the case of classification additionally returns information about class dict[str, dict[str, float]]:

Return type:

dict[str, float]

calculate_coverage_matrix(X: ndarray | DataFrame)

Calculate binary coverage matrix showing if each rule covers each sample. Number of columns in the matrix is equal to the number of rules. Number of rows is equal to the number of samples in the dataset. :param X: dataset :type X: Union[np.ndarray, pd.DataFrame]

calculate_rules_coverages(X_train: ndarray | DataFrame, y_train: ndarray | Series, **kwargs) → ndarray
Parameters:

  • X_train (Union[np.ndarray, pd.DataFrame]) – train dataset

  • y_train (Union[np.ndarray, pd.Series]) – train labels

Returns:

rules coverage matrix, same as calculated using “calculate_coverage_matrix” method.

Return type:

np.ndarray

calculate_rules_metrics(X: DataFrame, y: Series, metrics_to_calculate: list[str] | None = None) → dict[dict[str, str, float]]

Calculate rules metrics for each rule such as precision, coverage, TP, FP etc. This method should be called after updating or calculating rules coverages.

Parameters:

  • X (pd.DataFrame)

  • y (pd.Series)

  • metrics_to_calculate (Optional[list[str]], optional) – list of metrics names to calculate. Defaults to None.

Raises:

InvalidStateError – if rule’s coverage have not been calculated

Returns:

metrics for each rule

Return type:

dict[dict[str, str, float]]

calculate_rules_weights(measure: Callable[[Coverage], float])
Parameters:

measure (Callable[[Coverage], float]) – quality measure function

Raises:

ValueError – if any of the rules in ruleset has uncalculated coverage

calculate_ruleset_stats(*args, **kwargs) → dict[str, float]

Calculate ruleset statistics such as number of rules, average rule length, average precision, average coverage. This method should be called after updating rules coverages.

Returns:

RuleSet statistics

Return type:

dict

property coverage_dict: dict
property default_conclusion: AbstractConclusion

Default conclusion used during prediction

Returns:

default conclusion

Return type:

AbstractConclusion

abstract get_metrics_object_instance() → AbstractRulesMetrics

Returns metrics object instance.

property is_using_default_conclusion: bool

Whether default conclusion is enabled and used during prediction

Returns:

whether default conclusion is enabled

Return type:

bool

local_explainability(x: Series) → tuple[list[str], str]

Calculate local explainability of ruleset for given instance.

Parameters:

x (pd.Series) – Instance to explain

Returns:

list of rules covering instance str: Decision (in classification task) or prediction (in regression task)

Return type:

list

predict(X: DataFrame) → ndarray
Parameters:

X (pd.DataFrame)

Returns:

prediction

Return type:

np.ndarray

set_default_conclusion_enabled(enabled: bool) → None

Enable or disable usage of default conclusion during prediction.

Parameters:

enabled (bool) – whether to use default conclusion or not

split_dataset(dataset: DataFrame) → tuple[DataFrame, Series]
update(X_train: DataFrame, y_train: Series, measure: Callable[[Coverage], float])

Updates ruleset using training dataset. This method should be called both after creation of new ruleset or after manipulating any of its rules or internal conditions. This method recalculates rules coverages and voting weights making it ready for prediction

Parameters:

  • X_train (pd.DataFrame)

  • y_train (pd.Series)

  • measure (Callable[[Coverage], float]) – voting measure function

Raises:

ValueError – if called on empty ruleset with no rules

update_meta(new_attributes: list[str])
update_using_coverages(coverages_info: dict[str, ClassificationCoverageInfodict], measure: Callable[[Coverage], float], columns_names: list[str] = None)

decision_rules.core.simplifier

class decision_rules.core.simplifier.RulesetSimplifier(ruleset: AbstractRuleSet)

Bases: object

simplify() → AbstractRuleSet

decision_rules.core.test_measures