model_parameters

Model hyperparameters.

Classes:

Name	Description
ModelDecisionGraphParameters	Hyperparameters that influence the decision graph of a Xpdeep model, in an ante-hoc context.

ModelDecisionGraphParameters

Hyperparameters that influence the decision graph of a Xpdeep model, in an ante-hoc context.

The model decision graph is characterized by a set of learnt decision and can be adjusted to the use cases to provide more interpretable explanations.

Parameters:

Name	Type	Description	Default
graph_depth	int | Literal[default]	This parameter defines the maximum depth of the decision graph. Increasing the value allows for more decision nodes, providing finer granularity in the decision-making process, but also adds to the complexity of the resulting graph. The depth should be set according to the desired balance between explanation detail and overall complexity. In a classification task, the default value is the logarithm of the number of classes, rounded up to the nearest integer. In a regression task, it is set to 3.	"default"
prune_step	int | None	Pruning will be conducted every prune_step epochs, it varies within [1, max-epochs]. To disregard this parameter, and avoid pruning the model, set its value to None. This will cause the target_homogeneity_pruning_threshold and population_pruning_threshold parameters to be ignored.	None
target_homogeneity_pruning_threshold	float | None	To obtain a decision graph with an optimal structure, nodes that are sufficiently homogeneous are converted into leaves (i.e., pruned). Namely, if the homogeneity of the target variable within a node exceeds this threshold, it is converted into a leaf. A value of 1 ignores this criterion. In particular, - In the classification task, homogeneity is measured by the proportion of the majority class within a node. This parameter varies within the range [max_prop, 1], where max_prop represents the proportion of the majority class in the training data. By default, the value is set to 0.9. - In the regression task, homogeneity is based on the ratio between the variance of the target variable (noted Y) in a node and the total variance of Y in the training set, namely: 1 - Var(Y/node)/Var(Y/train). This parameter varies within the range [0, 1]. By default, the value is set to 0.1.	None
population_pruning_threshold	float | None	To obtain a decision graph with an optimal structure, nodes that involve very few individuals (i.e., not sufficiently represented) are converted into leaves. This parameter, which ranges from [0, 1], specifies the minimum proportion of individuals required in the nodes. If the proportion falls below this threshold, the node is pruned. To ignore this parameter, set its value to 0. By default, the value is set to 0.01.	None
internal_model_complexity	int	A complexity parameter, integer between 1 and 10, governing the structure of the explainable model in the ante-hoc context: a higher value designs a more complex model and create robust explanations but the training will be slower than with a lower value (1).	required
feature_extraction_output_type	FeatureExtractionOutputType	An enum describing the output structure of the feature extraction model, required to build the explainable model.	required
target_homogeneity_weight	float	This parameter controls the homogeneity of the target variable within graph nodes. In classification tasks, a higher value increases class purity within nodes, while in regression tasks, it reduces target variable variance. A high value, particularly greater than 1, may negatively impact the model's performance. A value of 0 disregards target variable homogeneity. By default, the value is set to 0.1.	0.1
discrimination_weight	float	This parameter controls the differentiation between the left and right input features at each node. Increasing this weight enhances the distinction between the left and right descriptive features, making the separation more pronounced. A high value, particularly greater than 1, may negatively impact the model's performance. A value of 0 disregards this discriminative constraint. By default, the value is set to 0.01.	0.01
balancing_weight	float	This parameter regulates the balance between the proportions of individuals sent left and right at each node. A high value, especially above 1, can negatively affect the model's performance. A value of 0 ignores this balancing. By default, the value is set to 0.	0.0
is_post_hoc	bool	If True, only the explanations will be trained, preserving the model's original performance. If False, the explanations are trained jointly with the model.	False

Methods:

Name	Description
__attrs_post_init__	Validate config.

Attributes:

Name	Type	Description
feature_extraction_output_type	FeatureExtractionOutputType

feature_extraction_output_type: FeatureExtractionOutputType

__attrs_post_init__() -> None

Validate config.

Source code in src/xpdeep/model/model_parameters.py

@no_type_check
def __attrs_post_init__(self) -> None:
    """Validate config."""
    self.feature_extraction_output_type = ModelDecisionGraphParametersRequestBodyFeatureextractionoutputtype[
        self.feature_extraction_output_type.name
    ]
    if isinstance(self.graph_depth, int) and self.graph_depth <= 0:
        msg = f"`graph_depth` must be a positive integer but is {self.graph_depth}"
        raise ValueError(msg)
    if self.prune_step is not None and (self.prune_step <= 0 or not isinstance(self.prune_step, int)):
        msg = f"`prune_step` must be a positive integer but is {self.prune_step}"
        raise ValueError(msg)
    if (
        self.target_homogeneity_pruning_threshold is not None
        and not 0 <= self.target_homogeneity_pruning_threshold <= 1
    ):
        msg = (
            f"`target_homogeneity_pruning_threshold` must be a float in [0, 1] but is "
            f"{self.target_homogeneity_pruning_threshold}"
        )
        raise ValueError(msg)
    if self.population_pruning_threshold is not None and not 0 <= self.population_pruning_threshold <= 1:
        msg = f"`population_pruning_threshold` must be a float in [0, 1] but is {self.population_pruning_threshold}"
        raise ValueError(msg)
    if self.internal_model_complexity not in {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}:
        msg = (
            f"`internal model complexity` must be an integer between 1 and 10 but is "
            f"{self.internal_model_complexity}"
        )
        raise ValueError(msg)

    if self.target_homogeneity_weight < 0:
        msg = (
            f"`target_homogeneity_weight` must be greater than or equal to 0 but is "
            f"{self.target_homogeneity_weight}"
        )
        raise ValueError(msg)

    if self.discrimination_weight < 0:
        msg = f"`target_homogeneity_weight` must be greater than or equal to 0 but is {self.discrimination_weight}"
        raise ValueError(msg)

    if self.balancing_weight < 0:
        msg = f"`target_homogeneity_weight` must be greater than or equal to 0 but is {self.balancing_weight}"
        raise ValueError(msg)