base_models

Defines abstract models, mixins, and other common backend-agnostic classes.

Implementations of these abstract models should be located in bitfount.models.models or in the models subpackage of a backend.

Classes

CNNModelStructure

class CNNModelStructure(    layers: Optional[List[int]] = None,    dropout_probs: Optional[List[float]] = None,    mish_activation_function: bool = True,    kernel_size: int = 5,    padding: int = 2,    stride: int = 1,    pooling_function: str = 'max',    ff_layers: List[int] = [],    ff_dropout_probs: List[float] = [],):

Dataclass defining the structure of a convolutional neural network model.

This model structure has multiple convolutional layers followed by multiple linear and dropout layers.

Arguments

• dropout_probs: List of dropout probabilities for each layer. Must be the same length as layers. Defaults to 0.01 and 0.1 respectively.
• ff_dropout_probs: List of dropout probabilities for each linear layer. Must be the same length as ff_layers. Defaults to 0.01 and 0.1 respectively.
• ff_layers: List of linear hidden layer sizes following the convolutional layers. Defaults to [1000, 500].
• kernel_size: Kernel size for convolutional layers. Defaults to 5.
• layers: List of hidden layer sizes i.e. not including the input/output layers. The layer type depends on the specific model structure. Defaults to 2 layers with 1000 and 500 nodes respectively.
• mish_activation_function: Whether to use Mish activation function. If False, ReLU is used instead. Defaults to True.
• padding: Padding for convolutional layers. Defaults to 2.
• pooling_function: Pooling function for convolutional layers. Options are "max" or "avg". Defaults to "max".
• stride: Stride for convolutional layers. Defaults to 1.

Attributes

• fields_dict: A dictionary mapping all attributes that will be serialized in the class to their marshamllow field type. (e.g. fields_dict = {"class_name": fields.Str()}).
• nested_fields: A dictionary mapping all nested attributes to a registry that contains class names mapped to the respective classes. (e.g. nested_fields = {"datastructure": datastructure.registry})
• num_heads: Number of heads for multihead models. I.e. the number of output layers.

Raises

• ValueError: If ff_layers and ff_dropout_probs are not the same length.
• ValueError: If pooling_function is not "max" or "avg".

Ancestors

• NeuralNetworkModelStructure
• abc.ABC
• bitfount.models.base_models._BaseModelStructureMixIn
• bitfount.types._BaseSerializableObjectMixIn

Variables

• static dropout_probs : Optional[List[float]] - same as argument

• static ff_dropout_probs : List[float] - same as argument

• static ff_layers : List[int] - same as argument

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static kernel_size : int - same as argument

• static layers : Optional[List[int]] - same as argument

• static mish_activation_function : bool - same as argument

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

• static padding : int - same as argument

• static pooling_function : str - same as argument

• static stride : int - same as argument

Methods

---

set_num_heads

def set_num_heads(self, datastructure: DataStructure) ‑> None:

Inherited from:

NeuralNetworkModelStructure.set_num_heads :

Sets the num_heads attribute.

This is taken from the multihead_size attribute of the datastructure if present. Otherwise, it is set to 1.

Arguments

• datastructure: The data structure the model has been designed for.

Raises

• ValueError: If datastructure.multihead_size is not a positive integer.

ClassifierMixIn

class ClassifierMixIn(    multilabel: bool = False, param_clipping: Optional[Dict[str, int]] = None,):

MixIn for classification problems.

Classification models must have this class in their inheritance hierarchy.

Arguments

• multilabel: Whether the problem is a multi-label problem. i.e. each datapoint belongs to multiple classes
• param_clipping: Arguments for clipping for BatchNorm parameters. Used for federated models with secure aggregation. It should contain the SecureShare variables and the number of workers in a dictionary, e.g. {"prime_q":13, "precision": 10**3,"num_workers":2}

Attributes

• multilabel: Whether the problem is a multi-label problem
• n_classes: Number of classes in the problem

Ancestors

• bitfount.models.base_models._BaseModelRegistryMixIn
• bitfount.types._BaseSerializableObjectMixIn

Subclasses

• PyTorchClassifierMixIn
• LogisticRegressionClassifier

Variables

• static datastructure : DataStructure - set in _BaseModel

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

• static schema : BitfountSchema - set in _BaseModel

Methods

---

set_number_of_classes

def set_number_of_classes(self, schema: TableSchema) ‑> None:

Sets the target number of classes for the classifier.

If the data is a multi-label problem, the number of classes is set to the number of target columns as specified in the DataStructure. Otherwise, the number of classes is set to the number of unique values in the target column as specified in the BitfountSchema. The value is stored in the n_classes attribute.

EarlyStopping

class EarlyStopping(params: _StrAnyDict = {}):

Class for specifying early stopping parameters.

Arguments

• params: dictionary of keyword arguments for the early stopping constructor. The parameters will depend on the backend being used.

Ancestors

• bitfount.models.base_models._BaseEarlyStopping
• bitfount.types._BaseSerializableObjectMixIn

Variables

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

• static params : Dict[str, Any] - same as argument

FeedForwardModelStructure

class FeedForwardModelStructure(    layers: Optional[List[int]] = None,    dropout_probs: Optional[List[float]] = None,    mish_activation_function: bool = True,    embedding_dropout: float = 0.04,):

Dataclass defining the structure of a feedforward neural network model.

This model structure only defines linear and dropout layers.

Arguments

• dropout_probs: List of dropout probabilities for each layer. Must be the same length as layers. Defaults to 0.01 and 0.1 respectively.
• embedding_dropout: Dropout probability for embedding layer. Defaults to 0.04.
• layers: List of hidden layer sizes i.e. not including the input/output layers. The layer type depends on the specific model structure. Defaults to 2 layers with 1000 and 500 nodes respectively.
• mish_activation_function: Whether to use Mish activation function. If False, ReLU is used instead. Defaults to True.

Attributes

• fields_dict: A dictionary mapping all attributes that will be serialized in the class to their marshamllow field type. (e.g. fields_dict = {"class_name": fields.Str()}).
• nested_fields: A dictionary mapping all nested attributes to a registry that contains class names mapped to the respective classes. (e.g. nested_fields = {"datastructure": datastructure.registry})
• num_heads: Number of heads for multihead models. I.e. the number of output layers.

Raises

• ValueError: If layers and dropout_probs are not the same length.

Ancestors

• NeuralNetworkModelStructure
• abc.ABC
• bitfount.models.base_models._BaseModelStructureMixIn
• bitfount.types._BaseSerializableObjectMixIn

Variables

• static dropout_probs : Optional[List[float]] - same as argument

• static embedding_dropout : float - same as argument

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static layers : Optional[List[int]] - same as argument

• static mish_activation_function : bool - same as argument

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

Methods

---

set_num_heads

def set_num_heads(self, datastructure: DataStructure) ‑> None:

Inherited from:

NeuralNetworkModelStructure.set_num_heads :

Sets the num_heads attribute.

This is taken from the multihead_size attribute of the datastructure if present. Otherwise, it is set to 1.

Arguments

• datastructure: The data structure the model has been designed for.

Raises

• ValueError: If datastructure.multihead_size is not a positive integer.

LoggerConfig

class LoggerConfig(    name: str,    save_dir: Optional[Path] = PosixPath('bitfount_logs'),    params: Optional[_StrAnyDict] = {},):

Configuration for the logger.

The configured logger will log training events, metrics, model checkpoints, etc. to your chosen platform. If no logger configuration is provided, the default logger is a Tensorboard logger.

Arguments

• name: The name of the logger. Should be one of the loggers supported by the chosen backend
• save_dir: The directory to save the logs. Defaults to BITFOUNT_LOGS_DIR
• params: A dictionary of keyword arguments to pass to the logger. Defaults to an empty dictionary

Variables

• static name : str - same as argument

• static params : Optional[Dict[str, Any]] - same as argument

• static save_dir : Optional[pathlib.Path] - same as argument

NeuralNetworkMixIn

class NeuralNetworkMixIn(    model_structure: Union[NeuralNetworkModelStructure, NeuralNetworkPredefinedModel],    batch_size: int = 512,    epochs: Optional[int] = None,    steps: Optional[int] = None,    optimizer: Optional[Optimizer] = None,    scheduler: Optional[Scheduler] = None,    custom_loss_func: Optional[Callable] = None,    early_stopping: Optional[EarlyStopping] = None,):

Specifies model structure and hyperparameters for neural network models.

All neural network models must inherit from this class.

caution

custom_loss_func cannot be serialized and therefore cannot be used in Federated Learning.

Arguments

• model_structure: The structure of the model.
• batch_size: The number of data points in each batch. Defaults to 512.
• epochs: The number of epochs to train for. If steps is provided, epochs cannot be provided. Defaults to None.
• steps: The number of steps to train for. If epochs is provided, steps cannot be provided. Defaults to None.
• optimizer: The optimizer to use. Defaults to "AdamW" with a learning rate of 0.01.
• scheduler: The scheduler to use. Defaults to None.
• custom_loss_func: A custom loss function to use. Defaults to None.
• early_stopping: Early stopping parameters. Defaults to None.

Attributes

• model_structure: The structure of the model.
• batch_size: The number of data points in each batch.
• epochs: The number of epochs to train for.
• steps: The number of steps to train for.
• optimizer: The optimizer to use.
• scheduler: The scheduler to use.
• loss_func: A custom loss function to use.
• early_stopping: Early stopping parameters.

Raises

• ValueError: If both epochs and steps are provided.

Ancestors

• bitfount.types._BaseSerializableObjectMixIn

Subclasses

• bitfount.backends.pytorch.models.base_models._PyTorchNeuralNetworkMixIn

Variables

• static datastructure : DataStructure - set in _BaseModel

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

NeuralNetworkModelStructure

class NeuralNetworkModelStructure(    layers: Optional[List[int]] = None,    dropout_probs: Optional[List[float]] = None,    mish_activation_function: bool = True,):

Dataclass defining the structure of a neural network model.

Arguments

• layers: List of hidden layer sizes i.e. not including the input/output layers. The layer type depends on the specific model structure. Defaults to 2 layers with 1000 and 500 nodes respectively.
• dropout_probs: List of dropout probabilities for each layer. Must be the same length as layers. Defaults to 0.01 and 0.1 respectively.
• mish_activation_function: Whether to use Mish activation function. If False, ReLU is used instead. Defaults to True.

Attributes

• num_heads: Number of heads for multihead models. I.e. the number of output layers.

Raises

• ValueError: If layers and dropout_probs are not the same length.

Ancestors

• abc.ABC
• bitfount.models.base_models._BaseModelStructureMixIn
• bitfount.types._BaseSerializableObjectMixIn

Subclasses

• CNNModelStructure
• FeedForwardModelStructure

Variables

• static dropout_probs : Optional[List[float]] - same as argument

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static layers : Optional[List[int]] - same as argument

• static mish_activation_function : bool - same as argument

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

Methods

---

set_num_heads

def set_num_heads(self, datastructure: DataStructure) ‑> None:

Sets the num_heads attribute.

This is taken from the multihead_size attribute of the datastructure if present. Otherwise, it is set to 1.

Arguments

• datastructure: The data structure the model has been designed for.

Raises

• ValueError: If datastructure.multihead_size is not a positive integer.

NeuralNetworkPredefinedModel

class NeuralNetworkPredefinedModel(    name: str, pretrained: bool = True, kwargs: Optional[Dict[str, bool]] = None,):

This class encompasses what is required to use a predefined model e.g. ResNet.

The currently supported models are: - AlexNet - DenseNet{121,161,169,201} - ResNet{18,34,50,101,152} - SqueezeNet{1_0,1_1} - VGG{11,11_bn,13,13_bn,16,16_bn,19,19_bn} - TabNet

Arguments

• name: name of the model
• pretrained: flag to denote whether to download the pretrained parameters
• ****kwargs**: additional arguments to pass to the model constructor

Ancestors

• bitfount.models.base_models._BaseModelStructureMixIn
• bitfount.types._BaseSerializableObjectMixIn

Variables

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static kwargs : Optional[Dict[str, bool]] - same as argument

• static name : str - same as argument

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

• static pretrained : bool - same as argument

Optimizer

class Optimizer(name: str, params: _StrAnyDict = {}):

Class for specifying the optimizer for a neural network.

The options for the optimizer will depend on the backend being used.

Arguments

• name: name of the optimizer
• params: dictionary of keyword arguments for the optimizer constructor

Ancestors

• bitfount.models.base_models._BaseOptimizer
• bitfount.types._BaseSerializableObjectMixIn

Variables

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static name : str - same as argument

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

• static params : Dict[str, Any] - same as argument

RegressorMixIn

class RegressorMixIn():

MixIn for regression problems.

Currently, just used for tagging purposes.

Ancestors

• bitfount.models.base_models._BaseModelRegistryMixIn
• bitfount.types._BaseSerializableObjectMixIn

Subclasses

• RegBoostRegressor

Variables

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

Scheduler

class Scheduler(name: str, params: _StrAnyDict = {}):

Class for specifying the scheduler for a neural network.

The options for the scheduler will depend on the backend being used.

Arguments

• name: name of the scheduler
• params: dictionary of keyword arguments for the scheduler constructor

Ancestors

• bitfount.models.base_models._BaseScheduler
• bitfount.types._BaseSerializableObjectMixIn

Variables

• static fields_dict : ClassVar[Dict[str, marshmallow.fields.Field]]

• static name : str - same as argument

• static nested_fields : ClassVar[Dict[str, Mapping[str, Any]]]

• static params : Dict[str, Any] - same as argument

---