Model

class neer_match_utilities.model.EpochEndSaver(base_dir, model_name)[source]

Custom Keras callback to save weights and biases at the end of every epoch using the Model.save(…) static method.

__init__(base_dir, model_name)[source]
Parameters:
  • base_dir (Path) – The root directory under which the model subdirectories will be created. For instance: Path.cwd(), as used by TrainingPipe

  • model_name (str) – A short identifier for the model. Each epoch’s directory will be base_dir / model_name / “checkpoints” / “epoch_<NN>”

on_epoch_end(epoch, logs=None)[source]

At the end of each epoch, call Model.save(…) so that weights and optimizer state are pickled as per your spec.

class neer_match_utilities.model.Model[source]

A class for saving and loading matching models.

save(model, target_directory, name):

Save the specified model to a target directory.

load(model_directory):

Load a model from a given directory.

static load(model_directory)[source]

Load a model from a specified directory.

Parameters:

model_directory (Path) – The directory containing the saved model.

Returns:

The loaded model. A DLMatchingModel carries the threshold tuned by TrainingPipe as best_threshold_ (None if none was tuned) and, if there is one, is compiled with it.

Return type:

Union[DLMatchingModel, NSMatchingModel]

static save(model, target_directory, name, save_architecture=False, overwrite=False)[source]

Save the model to a specified directory.

Parameters:
  • model (Union[DLMatchingModel, NSMatchingModel]) – The model to be saved.

  • target_directory (Path) – The directory where the model should be saved.

  • name (str) – Name of the model directory.

  • save_architecture (bool) – Whether to also render the architecture as architecture.png. Requires the graphviz binaries. Defaults to False.

  • overwrite (bool) – Whether to replace a model already saved under name. Defaults to False, in which case an existing model raises FileExistsError.

Raises:

FileExistsError – If target_directory / name / "model" exists and overwrite is False.

Return type:

None

class neer_match_utilities.model.ValidationMetrics(left, right, matches, batch_size=1024, tune_metric=None, match_share=None)[source]

Score the model on validation data at the end of every epoch.

The scores of validation_scores() on all validation record pairs are added to the epoch’s logs (val_F1, val_MCC, val_Loss, …; with tune_metric also val_threshold and val_tuned_MCC, …), where the history and later callbacks, such as EarlyStopping, see them.

It predicts from data frames, which every supported neer-match version provides; Keras’s own validation_data needs a newer neer-match.

__init__(left, right, matches, batch_size=1024, tune_metric=None, match_share=None)[source]
Parameters:
  • left (DataFrame) – The validation data, in the format the model is trained on.

  • right (DataFrame) – The validation data, in the format the model is trained on.

  • matches (DataFrame) – The validation data, in the format the model is trained on.

  • batch_size (int) – Record pairs per prediction batch. Affects speed and memory only.

  • tune_metric (str | None) – If given, each epoch is also scored at the threshold that maximises this metric on the validation pairs.

  • match_share (float | None) – If given, that threshold is chosen, and scored, with the non-matches weighted as if matches made up this share of the pairs.

on_epoch_end(epoch, logs=None)[source]

Called at the end of an epoch.

Subclasses should override for any actions to run. This function should only be called during TRAIN mode.

Parameters:
  • epoch (int) – Integer, index of epoch.

  • logs – Dict, metric results for this training epoch, and for the validation epoch if validation is performed. Validation result keys are prefixed with val_. For training epoch, the values of the Model’s metrics are returned. Example: {‘loss’: 0.2, ‘accuracy’: 0.7}.

neer_match_utilities.model.validation_scores(model, left, right, matches, batch_size=1024, tune_metric=None, match_share=None)[source]

Score a model on all record pairs of validation data.

Returns the scores, keyed as an epoch’s logs are, and the predicted probabilities of all pairs, left record by left record:

  • val_TP … val_MCC: at the model’s threshold, 0.5 unless it was compiled with another. Precision, Recall, F1 and MCC are 0 where they are undefined.

  • val_Loss: the model’s loss on all pairs at once.

  • With tune_metric (‘mcc’ or ‘f1’): val_threshold, the threshold that maximises it (see tune_threshold()), and val_tuned_F1, val_tuned_MCC, val_tuned_Precision and val_tuned_Recall at that threshold. With match_share, the non-matches count as if matches made up that share of the pairs, both in choosing the threshold and in these four scores (see non_match_weight()).

Return type:

tuple[dict, ndarray]