dualing.core¶
Core is the core. Essentially, it is the parent of everything. You should find parent classes defining the basis of our structure. They should provide variables and methods that will help to construct other modules.
A core package, containing all the basic class and functions that serves as the foundation of Dualing common modules.
- class dualing.core.Base(name: Optional[str] = '')¶
Bases:
tensorflow.keras.Model
A Base class is responsible for easily-implementing the base twin architecture of a Siamese Network.
- __init__(self, name: Optional[str] = '')¶
Initialization method.
- Parameters
name – Naming identifier.
- abstract call(self, x: tensorflow.Tensor)¶
Method that holds vital information whenever this class is called.
Note that you need to implement this method directly on its child. Essentially, each neural network has its own forward pass implementation.
- Parameters
x – Tensor containing the input sample.
- Raises
NotImplementedError. –
- class dualing.core.BinaryCrossEntropy¶
A BinaryCrossEntropy class defines the binary cross-entropy loss.
- __call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor)¶
Method that holds vital information whenever this class is called.
- Parameters
y_true – Tensor containing the true labels.
y_pred – Tensor containing the predictions, e.g., similar or dissimilar.
- Returns
Binary cross-entropy loss.
- Return type
(tf.Tensor)
- class dualing.core.ContrastiveLoss¶
A ContrastiveEntropy class defines the contrastive loss.
- __call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, margin: Optional[float] = 1.0)¶
Method that holds vital information whenever this class is called.
- Parameters
y_true – Tensor containing the true labels.
y_pred – Tensor containing the predictions, e.g., distance.
margin – Radius around the embedding space.
- Returns
Contrastive loss.
- Return type
(tf.Tensor)
- class dualing.core.Dataset(batch_size: Optional[int] = 1, input_shape: Optional[Tuple[int, Ellipsis]] = None, normalize: Optional[Tuple[int, int]] = (0, 1), shuffle: Optional[bool] = True, seed: Optional[int] = 0)¶
A Dataset class is responsible for receiving raw data, pre-processing it and persisting batches that will be feed as inputs to the networks.
- __init__(self, batch_size: Optional[int] = 1, input_shape: Optional[Tuple[int, Ellipsis]] = None, normalize: Optional[Tuple[int, int]] = (0, 1), shuffle: Optional[bool] = True, seed: Optional[int] = 0)¶
Initialization method.
- Parameters
batch_size – Batch size.
input_shape – Shape of the reshaped array.
normalize – Normalization bounds.
shuffle – Whether data should be shuffled or not.
seed – Provides deterministic traits when using random module.
- abstract _build(self)¶
Method that builds the class.
Note that you need to implement this method directly on its child. Essentially, each Dataset has its building procedure.
- Raises
NotImplementedError. –
- property batch_size(self)¶
Batch size.
- property input_shape(self: Tuple[int, Ellipsis])¶
Shape of the input tensors.
- property normalize(self)¶
Normalization bounds.
- preprocess(self, data: numpy.array)¶
Pre-process the data by reshaping and normalizing, if necessary.
- Parameters
data – Array of data.
- Returns
Pre-processed data.
- Return type
(np.array)
- property shuffle(self)¶
Whether data should be shuffled or not.
- class dualing.core.Siamese(base: Base, name: Optional[str] = '')¶
Bases:
tensorflow.keras.Model
An Siamese class is responsible for implementing the base of Siamese Neural Networks.
- property B(self)¶
Twin architecture.
- __init__(self, base: Base, name: Optional[str] = '')¶
Initialization method.
- Parameters
base – Twin architecture.
name – Naming identifier.
- abstract compile(self, optimizer: tensorflow.keras.optimizers)¶
Method that builds the network by attaching optimizer, loss and metrics.
Note that you need to implement this method directly on its child. Essentially, each type of Siamese has its own set of loss and metrics.
- Parameters
optimizer – Optimization algorithm.
- Raises
NotImplementedError. –
- abstract evaluate(self, batches: dualing.core.dataset.Dataset)¶
Method that evaluates the model over validation or testing batches.
Note that you need to implement this method directly on its child. Essentially, each type of Siamese may use a distinct type of dataset.
- Parameters
batches – Batches of tuples holding validation / testing samples and labels.
- Raises
NotImplementedError. –
- extract_embeddings(self, x: Union[numpy.array, tensorflow.Tensor])¶
Method that extracts embeddings by performing a forward pass over the base architecture (embedder).
- Parameters
x – Array or tensor containing the inputs to be embedded.
- Returns
A tensor containing the embedded inputs.
- Return type
(tf.Tensor)
- abstract fit(self, batches: dualing.core.dataset.Dataset, epochs: Optional[int] = 100)¶
Method that trains the model over training batches.
Note that you need to implement this method directly on its child. Essentially, each type of Siamese may use a distinct type of dataset.
- Parameters
batches – Batches of tuples holding training samples and labels.
epochs – Maximum number of epochs.
- Raises
NotImplementedError. –
- abstract predict(self, x: tensorflow.Tensor)¶
Method that performs a forward pass over samples and returns the network’s output.
Note that you need to implement this method directly on its child. Essentially, each type of Siamese may predict in a different way.
- Parameters
x – Tensor containing samples.
- Raises
NotImplementedError. –
- abstract step(self, x: tensorflow.Tensor, y: tensorflow.Tensor)¶
Method that performs a single batch optimization step.
Note that you need to implement this method directly on its child. Essentially, each type of Siamese has an unique step.
- Parameters
x – Tensor containing samples.
y – Tensor containing labels.
- Raises
NotImplementedError. –
- class dualing.core.TripletHardLoss¶
A TripletHardLoss class defines the triplet loss with hard negative mining.
- __call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, margin: Optional[float] = 1.0, soft: Optional[bool] = False, distance_metric: Optional[str] = 'L2')¶
Method that holds vital information whenever this class is called.
- Parameters
y_true – Tensor containing the true labels.
y_pred – Tensor containing the predictions, e.g., embeddings.
margin – Radius around the embedding space.
soft – Whether network should use soft margin or not.
distance_metric – Distance metric.
- Returns
Triplet loss with hard negative mining.
- Return type
(tf.Tensor)
- class dualing.core.TripletSemiHardLoss¶
A TripletSemiHardLoss class defines the triplet loss with semi-hard negative mining.
- __call__(self, y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, margin: Optional[float] = 1.0, soft: Optional[bool] = None, distance_metric: Optional[str] = 'L2')¶
Method that holds vital information whenever this class is called.
- Parameters
y_true – Tensor containing the true labels.
y_pred – Tensor containing the predictions, e.g., embeddings.
margin – Radius around the embedding space.
soft – Only for retro-compatibility.
distance_metric – Distance metric.
- Returns
Triplet loss with semi-hard negative mining.
- Return type
(tf.Tensor)