class_docstr: Experiment runner.
  
  This class implements routines to train, evaluate and make predictions from models.
class_docstr_tok: ["Experiment","runner",".","This","class","implements","routines","to","train",",","evaluate","and","make","predictions","from","models","."]
docstr: run_train(model, train_dataset, validation_dataset, best_save_path,epochs=30,             criterion=None, optimizer=None, pos_neg_ratio=None, pos_weight=None,             label_smoothing=0.05, save_every_prefix=None, save_every_freq=None,             batch_size=32, device=None, progress_style='bar', log_freq=5,             sort_in_buckets=None)
  
  Train a :class:`deepmatcher.MatchingModel` using the specified training set.
  Refer to :meth:`deepmatcher.MatchingModel.run_train` for details on
  parameters.
  
  Returns:
      float: The best F1 score obtained by the model on the validation dataset.
docstr_tok: ["run_train","(","model",",","train_dataset",",","validation_dataset",",","best_save_path",",","epochs=30",",","criterion=None",",","optimizer=None",",","pos_neg_ratio=None",",","pos_weight=None",",","label_smoothing=0.05",",","save_every_prefix=None",",","save_every_freq=None",",","batch_size=32",",","device=None",",","progress_style='bar","'",",","log_freq=5",",","sort_in_buckets=None",")","Train","a",":","class",":","`","deepmatcher.MatchingModel","`","using","the","specified","training","set",".","Refer","to",":","meth",":","`","deepmatcher.MatchingModel.run_train","`","for","details","on","parameters",".","Returns",":","float",":","The","best","F1","score","obtained","by","the","model","on","the","validation","dataset","."]
code: def train(
      model,
      train_dataset,
      validation_dataset,
      best_save_path,
      epochs=30,
      criterion=None,
      optimizer=None,
      pos_neg_ratio=None,
      pos_weight=None,
      label_smoothing=0.05,
      save_every_prefix=None,
      save_every_freq=1,
      **kwargs,
  ):
      """run_train(model, train_dataset, validation_dataset, best_save_path,epochs=30, \
              criterion=None, optimizer=None, pos_neg_ratio=None, pos_weight=None, \
              label_smoothing=0.05, save_every_prefix=None, save_every_freq=None, \
              batch_size=32, device=None, progress_style='bar', log_freq=5, \
              sort_in_buckets=None)
  
          Train a :class:`deepmatcher.MatchingModel` using the specified training set.
          Refer to :meth:`deepmatcher.MatchingModel.run_train` for details on
          parameters.
  
          Returns:
              float: The best F1 score obtained by the model on the validation dataset.
          """
  
      model.initialize(train_dataset)
  
      model._register_train_buffer("optimizer_state", None)
      model._register_train_buffer("best_score", None)
      model._register_train_buffer("epoch", None)
  
      if criterion is None:
          if pos_weight is not None:
              assert pos_weight < 2
              warnings.warn(
                  '"pos_weight" parameter is deprecated and will be removed '
                  'in a later release, please use "pos_neg_ratio" instead',
                  DeprecationWarning,
              )
              assert pos_neg_ratio is None
          else:
              if pos_neg_ratio is None:
                  pos_neg_ratio = 1
              else:
                  assert pos_neg_ratio > 0
              pos_weight = 2 * pos_neg_ratio / (1 + pos_neg_ratio)
  
          neg_weight = 2 - pos_weight
  
          criterion = SoftNLLLoss(
              label_smoothing, torch.Tensor([neg_weight, pos_weight])
          )
  
      optimizer = optimizer or Optimizer()
      if model.optimizer_state is not None:
          model.optimizer.base_optimizer.load_state_dict(
              model.optimizer_state
          )
  
      if model.epoch is None:
          epochs_range = range(epochs)
      else:
          epochs_range = range(model.epoch + 1, epochs)
  
      if model.best_score is None:
          model.best_score = -1
      optimizer.last_acc = model.best_score
  
      for epoch in epochs_range:
          model.epoch = epoch
          Runner._run(
              "TRAIN",
              model,
              train_dataset,
              criterion,
              optimizer,
              train=True,
              **kwargs,
          )
  
          score = Runner._run(
              "EVAL", model, validation_dataset, train=False, **kwargs
          )
  
          optimizer.update_learning_rate(score, epoch + 1)
          model.optimizer_state = optimizer.base_optimizer.state_dict()
  
          new_best_found = False
          if score > model.best_score:
              print("* Best F1:", score)
              model.best_score = score
              new_best_found = True
  
              if best_save_path and new_best_found:
                  print("Saving best model...")
                  model.save_state(best_save_path)
                  print("Done.")
  
          if (
              save_every_prefix is not None
              and (epoch + 1) % save_every_freq == 0
          ):
              print("Saving epoch model...")
              save_path = "{prefix}_ep{epoch}.pth".format(
                  prefix=save_every_prefix, epoch=epoch + 1
              )
              model.save_state(save_path)
              print("Done.")
          print("---------------------\n")
  
      print("Loading best model...")
      model.load_state(best_save_path)
      print("Training done.")
  
      return model.best_score
  
imports: import copy
  import logging
  import sys
  import time
  import warnings
  from collections import OrderedDict
  import pandas
  import pyprind
  import torch
  from tqdm import tqdm
  from .data import MatchingIterator
  from .optim import Optimizer, SoftNLLLoss
  from .utils import tally_parameters
label_desc: Use image node_id 6 for calling the Runner obj's underlying member method code with example usage: obj.train(model, train_dataset, validation_dataset, best_save_path, epochs, criterion, optimizer, pos_neg_ratio, pos_weight, label_smoothing, save_every_prefix, save_every_freq) and returns: model