xpdeep_model

Define the xpdeep explainable model.

Classes:

Name	Description
XpdeepModel	Xpdeep Model class.

Functions:

Name	Description
wrapped_from_dict	Overwrite from_dict method of ModelDecisionGraphParametersRequestBody class.

Attributes:

Name	Type	Description
DROPOUT_TYPES
BATCH_NORM_TYPES

DROPOUT_TYPES = nn.Dropout | nn.Dropout2d | nn.Dropout3d | nn.AlphaDropout | nn.FeatureAlphaDropout

BATCH_NORM_TYPES = nn.BatchNorm1d | nn.BatchNorm2d | nn.BatchNorm3d | nn.SyncBatchNorm | nn.LazyBatchNorm1d | nn.LazyBatchNorm2d | nn.LazyBatchNorm3d

XpdeepModel

Xpdeep Model class.

Parameters:

Name	Type	Description	Default
feature_extraction	AbstractModule	The feature extraction model, responsible to extract the most important and coherent features prior to the task you want to achieve.	required
task_learner	AbstractModule	The task learner model is responsible to achieve your task (classification etc.), given a set of meaningful extracted features.	required
backbone	AbstractModule | None	The backbone model, having the same role as a traditional backbone model on a neural network, default None.	None
decision_graph_parameters	ModelDecisionGraphParameters	Internal parameters and architecture of the Xpdeep explainable model.	required
seed	int	Seed for reproducibility.	0

Methods:

Name	Description
from_torch	Build a Xpdeep model from torch model.
to_model	As request body.
get_output_size	Infer the model output size without batch size as it is required to serialize a loss function.
__repr__	Represent the model.

Attributes:

Name	Type	Description
feature_extraction	AbstractModule
task_learner	AbstractModule
decision_graph_parameters	ModelDecisionGraphParameters
backbone	AbstractModule | None
seed	int

feature_extraction: AbstractModule

task_learner: AbstractModule

decision_graph_parameters: ModelDecisionGraphParameters

backbone: AbstractModule | None = None

seed: int = 0

from_torch(fitted_schema: FittedSchema, feature_extraction: nn.Module, task_learner: nn.Module, decision_graph_parameters: ModelDecisionGraphParameters, backbone: nn.Module | None = None, seed: int = 0) -> Self

Build a Xpdeep model from torch model.

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

@classmethod
def from_torch(  # noqa: PLR0913, PLR0917
    cls,
    fitted_schema: FittedSchema,
    feature_extraction: nn.Module,
    task_learner: nn.Module,
    decision_graph_parameters: ModelDecisionGraphParameters,
    backbone: nn.Module | None = None,
    seed: int = 0,
) -> Self:
    """Build a Xpdeep model from torch model."""
    XpdeepModel.__assert_no_dropout_nor_batch_norm(task_learner)
    XpdeepModel.__assert_no_dropout_nor_batch_norm(feature_extraction)
    XpdeepModel.__assert_no_dropout_nor_batch_norm(backbone) if backbone is not None else None

    input_size = fitted_schema.input_size

    # export with batch normalization layers for instance requires more than 1 sample
    inputs = torch.randn(2, *input_size[1:])

    if backbone is not None:
        backbone_module = ApiModule.from_torch_module(backbone, inputs)
        inputs_feature_extraction = backbone_module(feature_extraction)
    else:
        backbone_module = None
        inputs_feature_extraction = inputs

    feature_extractor_module = ApiModule.from_torch_module(feature_extraction, inputs_feature_extraction)

    inputs_task_learner = feature_extraction(inputs_feature_extraction)
    task_learner_module = ApiModule.from_torch_module(task_learner, inputs_task_learner)

    return cls(
        feature_extraction=feature_extractor_module,
        task_learner=task_learner_module,
        backbone=backbone_module,
        decision_graph_parameters=decision_graph_parameters,
        seed=seed,
    )

to_model() -> XpdeepModelRequestBody

As request body.

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

def to_model(self) -> XpdeepModelRequestBody:
    """As request body."""
    decision_graph_parameters_as_dict = self.decision_graph_parameters.to_dict()
    decision_graph_parameters_as_dict["feature_extraction_output_type"] = (
        ModelDecisionGraphParametersFeatureExtractionOutputType(
            decision_graph_parameters_as_dict["feature_extraction_output_type"]
        )
    )
    # Convert the xpdeep-types SerializedModule to xpdeep_api_client SerializedModuleInput
    return XpdeepModelRequestBody(
        feature_extraction=convert_serialized_module(self.feature_extraction.to_pydantic()),
        task_learner=convert_serialized_module(self.task_learner.to_pydantic()),
        decision_graph_parameters=ModelDecisionGraphParametersRequestBody(**decision_graph_parameters_as_dict),
        seed=self.seed,
        backbone=convert_serialized_module(self.backbone.to_pydantic()) if self.backbone is not None else None,
    )

get_output_size(schema: FittedSchema) -> tuple[int, ...]

Infer the model output size without batch size as it is required to serialize a loss function.

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

def get_output_size(self, schema: FittedSchema) -> tuple[int, ...]:
    """Infer the model output size without batch size as it is required to serialize a loss function."""
    x = MultiModal(
        torch.ones((5, *schema.input_size[1:]))
    )  # Batch size of one is not accepted by batch normalization layer.
    if self.backbone is not None:
        x = self.backbone(x)
    x = self.feature_extraction.forward_with_casting(x)
    x = self.task_learner.forward_with_casting(x)
    return tuple(x.shape.args[0])

__repr__() -> str

Represent the model.

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

def __repr__(self) -> str:
    """Represent the model."""
    model_string = repr(self.decision_graph_parameters)
    model_string += f"\n\nFeature extraction model:\n{self.feature_extraction.model}"
    model_string += f"\n\nTask learner model:\n{self.task_learner.model}"
    if self.backbone is not None:
        model_string += f"\n\nBackbone model:\n{self.backbone.model}"

    return model_string

wrapped_from_dict(cls: type[ModelDecisionGraphParametersRequestBody], src_dict: Mapping[str, object]) -> ModelDecisionGraphParametersRequestBody

Overwrite from_dict method of ModelDecisionGraphParametersRequestBody class.

Bug in the current generated client: it tries if graph depth is not an integer it raises an Exception.

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

def wrapped_from_dict(
    cls: type[ModelDecisionGraphParametersRequestBody], src_dict: Mapping[str, object]
) -> ModelDecisionGraphParametersRequestBody:
    """Overwrite from_dict method of ModelDecisionGraphParametersRequestBody class.

    Bug in the current generated client: it tries if graph depth is not an integer it raises an Exception.
    """
    return cls(**src_dict)  # type: ignore[arg-type]