class_docstr: A neural network model for entity matching.
  
  Refer to the
  `Matching Models tutorial <https://nbviewer.jupyter.org/github/sidharthms/deepmatcher/blob/master/examples/matching_models.ipynb>`_
  for details on how to customize a `MatchingModel`. A brief intro is below:
  
  This network consists of the following components:
  
  #. Attribute Summarizers
  
  #. Attribute Comparators
  
  #. A Classifier
  
  Creating a MatchingModel instance does not immediately construct the neural network.
  The network will be constructed just before training based on metadata from the
  training set:
  
  #. For each attribute (e.g., Product Name, Address, etc.), an Attribute Summarizer is
     constructed using the specified `attr_summarizer` template.
  #. For each attribute, an Attribute Comparator is constructed using the specified
     `attr_summarizer` template.
  #. A Classifier is constructed based on the specified `classifier` template.
  
  Args:
      attr_summarizer (string or :class:`AttrSummarizer` or callable):
          The attribute summarizer. Takes in two word embedding sequences and summarizes
          the information in them to produce two summary vectors as output.
          Options `listed here <https://nbviewer.jupyter.org/github/sidharthms/deepmatcher/blob/master/examples/matching_models.ipynb#attr_summarizer-can-be-set-to-one-of-the-following:>`__.
          Defaults to 'hybrid', i.e., the :class:`~deepmatcher.attr_summarizers.Hybrid`
          model.
      attr_comparator (string or :class:`~deepmatcher.modules.Merge` or callable):
          The attribute comparator. Takes as input the two summary vectors and applies a
          comparison function over those summaries to obtain the final similarity
          representation of the two attribute values. Argument must specify a
          :ref:`merge-op` operation. Default is selected based on `attr_summarizer`
          choice.
      attr_condense_factor (string or int):
          The factor by which to condense each attribute similarity vector. E.g. if
          `attr_condense_factor` is set to 3 and the attribute similarity vector size is
          300, then each attribute similarity vector is transformed to a 100 dimensional
          vector using a linear transformation. The purpose of condensing is to reduce
          the number of parameters in the classifier module. This parameter can be set
          to a number or 'auto'. If 'auto', then the condensing factor is set to be
          equal to the number attributes, but if there are more than 6 attributes, then
          the condensing factor is set to 6. Defaults to 'auto'.
      attr_merge (string or :class:`~deepmatcher.modules.Merge` or callable):
          The operation used to merge the (optionally condensed) attribute similarity
          vectors to obtain the input to the classifier. Argument must specify a
          :ref:`merge-op` operation. Defaults to 'concat', i.e., concatenate all
          attribute similarity vectors to form the classifier input.
      classifier (string or :class:`Classifier` or callable):
          The neural network to perform match / mismatch classification
          based on attribute similarity representations.
          Options `listed here <https://nbviewer.jupyter.org/github/sidharthms/deepmatcher/blob/master/examples/matching_models.ipynb#classifier-can-be-set-to-one-of-the-following:>`__.
          Defaults to '2-layer-highway', i.e., use a two layer highway network followed
          by a softmax layer for classification.
      hidden_size (int):
          The hidden size to use for the `attr_summarizer` and the `classifier` modules,
          if they are string arguments. If a module or :attr:`callable` input is specified
          for a component, this argument is ignored for that component.
class_docstr_tok: ["A","neural","network","model","for","entity","matching",".","Refer","to","the","`","Matching","Models","tutorial","<","https",":","\/\/nbviewer.jupyter.org\/github\/sidharthms\/deepmatcher\/blob\/master\/examples\/matching_models.ipynb",">","`","_","for","details","on","how","to","customize","a","`","MatchingModel","`",".","A","brief","intro","is","below",":","This","network","consists","of","the","following","components",":","#",".","Attribute","Summarizers","#",".","Attribute","Comparators","#",".","A","Classifier","Creating","a","MatchingModel","instance","does","not","immediately","construct","the","neural","network",".","The","network","will","be","constructed","just","before","training","based","on","metadata","from","the","training","set",":","#",".","For","each","attribute","(","e.g.",",","Product","Name",",","Address",",","etc",".",")",",","an","Attribute","Summarizer","is","constructed","using","the","specified","`","attr_summarizer","`","template",".","#",".","For","each","attribute",",","an","Attribute","Comparator","is","constructed","using","the","specified","`","attr_summarizer","`","template",".","#",".","A","Classifier","is","constructed","based","on","the","specified","`","classifier","`","template",".","Args",":","attr_summarizer","(","string","or",":","class",":","`","AttrSummarizer","`","or","callable",")",":","The","attribute","summarizer",".","Takes","in","two","word","embedding","sequences","and","summarizes","the","information","in","them","to","produce","two","summary","vectors","as","output",".","Options","`","listed","here","<","https",":","\/\/nbviewer.jupyter.org\/github\/sidharthms\/deepmatcher\/blob\/master\/examples\/matching_models.ipynb","#","attr_summarizer-can-be-set-to-one-of-the-following",":",">","`","__",".","Defaults","to","'hybrid","'",",","i.e.",",","the",":","class",":","`","~deepmatcher.attr_summarizers.Hybrid","`","model",".","attr_comparator","(","string","or",":","class",":","`","~deepmatcher.modules.Merge","`","or","callable",")",":","The","attribute","comparator",".","Takes","as","input","the","two","summary","vectors","and","applies","a","comparison","function","over","those","summaries","to","obtain","the","final","similarity","representation","of","the","two","attribute","values",".","Argument","must","specify","a",":","ref",":","`","merge-op","`","operation",".","Default","is","selected","based","on","`","attr_summarizer","`","choice",".","attr_condense_factor","(","string","or","int",")",":","The","factor","by","which","to","condense","each","attribute","similarity","vector",".","E.g",".","if","`","attr_condense_factor","`","is","set","to","3","and","the","attribute","similarity","vector","size","is","300",",","then","each","attribute","similarity","vector","is","transformed","to","a","100","dimensional","vector","using","a","linear","transformation",".","The","purpose","of","condensing","is","to","reduce","the","number","of","parameters","in","the","classifier","module",".","This","parameter","can","be","set","to","a","number","or","'auto","'",".","If","'auto","'",",","then","the","condensing","factor","is","set","to","be","equal","to","the","number","attributes",",","but","if","there","are","more","than","6","attributes",",","then","the","condensing","factor","is","set","to","6",".","Defaults","to","'auto","'",".","attr_merge","(","string","or",":","class",":","`","~deepmatcher.modules.Merge","`","or","callable",")",":","The","operation","used","to","merge","the","(","optionally","condensed",")","attribute","similarity","vectors","to","obtain","the","input","to","the","classifier",".","Argument","must","specify","a",":","ref",":","`","merge-op","`","operation",".","Defaults","to","'concat","'",",","i.e.",",","concatenate","all","attribute","similarity","vectors","to","form","the","classifier","input",".","classifier","(","string","or",":","class",":","`","Classifier","`","or","callable",")",":","The","neural","network","to","perform","match","\/","mismatch","classification","based","on","attribute","similarity","representations",".","Options","`","listed","here","<","https",":","\/\/nbviewer.jupyter.org\/github\/sidharthms\/deepmatcher\/blob\/master\/examples\/matching_models.ipynb","#","classifier-can-be-set-to-one-of-the-following",":",">","`","__",".","Defaults","to","'","2-layer-highway","'",",","i.e.",",","use","a","two","layer","highway","network","followed","by","a","softmax","layer","for","classification",".","hidden_size","(","int",")",":","The","hidden","size","to","use","for","the","`","attr_summarizer","`","and","the","`","classifier","`","modules",",","if","they","are","string","arguments",".","If","a","module","or",":","attr",":","`","callable","`","input","is","specified","for","a","component",",","this","argument","is","ignored","for","that","component","."]
docstr: run_train(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 the model using the specified training set.
  
  Args:
      train_dataset (:class:`~deepmatcher.data.MatchingDataset`):
          The training dataset obtained using :func:`deepmatcher.data.process`.
      validation_dataset (:class:`~deepmatcher.data.MatchingDataset`):
          The validation dataset obtained using :func:`deepmatcher.data.process`.
          This is used for `early stopping
          <https://en.wikipedia.org/wiki/Early_stopping>`_.
      best_save_path (string):
          The path to save the best model to. At the end of each epoch, if the new
          model accuracy (F1) is better than all previous epochs, then it is saved
          to this location.
      epochs (int):
          Number of training epochs, i.e., number of times to cycle through the
          entire training set. Defaults to 50.
      criterion (:class:`torch.nn.Module`):
          The loss function to use. Refer to the `losses section of the PyTorch API
          <https://pytorch.org/docs/master/nn.html#loss-functions>`_ for options. By
          default, `deepmatcher` will output a 2d tensor of shape (N, C) where N is
          the batch size and C is 2 - the number of classes. Keep this in mind when
          picking the loss. Defaults to :class:`~deepmatcher.optim.SoftNLLLoss` with
          label smoothing.
      optimizer (:class:`~deepmatcher.optim.Optimizer`):
          The optimizer to use for updating the trainable parameters of the
          :class:`~deepmatcher.MatchingModel` neural network after each iteration.
          If not specified an :class:`~deepmatcher.optim.Optimizer` with Adam
          optimizer will be constructed.
      pos_neg_ratio (int):
          The weight of the positive class (match) wrt the negative class
          (non-match). This parameter must be specified if there is a significant
          class imbalance in the dataset.
      label_smoothing (float):
          The `label_smoothing` parameter to constructor of
          :class:`~deepmatcher.optim.SoftNLLLoss` criterion. Only used when
          `criterion` param is None. Defaults to 0.05.
      save_every_prefix (string):
          Prefix of the path to save model to, after end of
          every N epochs, where N is determined by `save_every_freq` param.
          E.g. setting this to "/path/to/saved/model" will save models to
          "/path/to/saved/model_ep1.pth", "/path/to/saved/model_ep2.pth", etc.
          Models will not be saved periodically if this is None. Defaults to
          None.
      save_every_freq (int):
          Determines the frequency (number of epochs) for saving models periodically
          to the path specified by the `save_every_prefix` param (has no effect if
          that param is not set). Defaults to 1.
      batch_size (int):
          Mini-batch size for SGD. For details on what this is
          `see this video <https://www.coursera.org/learn/machine-learning/lecture/9zJUs/mini-batch-gradient-descent>`__.
          Defaults to 32. This is a keyword only param.
      device (string):
          The device on which to train the model ('cpu' or 'cuda'). If None, will use
          first available GPU, or use CPU if no GPUs are available. Defaults to None.
          This is a keyword only param.
      progress_style (string):
          Sets the progress update style. One of 'bar' or 'log'. If 'bar', uses a
          progress bar, updated every N batches. If 'log', prints training stats
          every N batches. N is determined by the `log_freq` param.
          This is a keyword only param.
      log_freq (int):
          Number of batches between progress updates. Defaults to 5.
          This is a keyword only param.
      sort_in_buckets (bool):
          Whether to batch examples of similar lengths together. If True, minimizes
          amount of padding needed while producing freshly shuffled batches for each
          new epoch. Implemented using :func:`torchtext.data.pool`.
          Defaults to True. This is a keyword only param.
  
  Returns:
      float: The best F1 score obtained by the model on the validation dataset.
code: def run_train(self, *args, **kwargs):
      """run_train(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 the model using the specified training set.
  
          Args:
              train_dataset (:class:`~deepmatcher.data.MatchingDataset`):
                  The training dataset obtained using :func:`deepmatcher.data.process`.
              validation_dataset (:class:`~deepmatcher.data.MatchingDataset`):
                  The validation dataset obtained using :func:`deepmatcher.data.process`.
                  This is used for `early stopping
                  <https://en.wikipedia.org/wiki/Early_stopping>`_.
              best_save_path (string):
                  The path to save the best model to. At the end of each epoch, if the new
                  model accuracy (F1) is better than all previous epochs, then it is saved
                  to this location.
              epochs (int):
                  Number of training epochs, i.e., number of times to cycle through the
                  entire training set. Defaults to 50.
              criterion (:class:`torch.nn.Module`):
                  The loss function to use. Refer to the `losses section of the PyTorch API
                  <https://pytorch.org/docs/master/nn.html#loss-functions>`_ for options. By
                  default, `deepmatcher` will output a 2d tensor of shape (N, C) where N is
                  the batch size and C is 2 - the number of classes. Keep this in mind when
                  picking the loss. Defaults to :class:`~deepmatcher.optim.SoftNLLLoss` with
                  label smoothing.
              optimizer (:class:`~deepmatcher.optim.Optimizer`):
                  The optimizer to use for updating the trainable parameters of the
                  :class:`~deepmatcher.MatchingModel` neural network after each iteration.
                  If not specified an :class:`~deepmatcher.optim.Optimizer` with Adam
                  optimizer will be constructed.
              pos_neg_ratio (int):
                  The weight of the positive class (match) wrt the negative class
                  (non-match). This parameter must be specified if there is a significant
                  class imbalance in the dataset.
              label_smoothing (float):
                  The `label_smoothing` parameter to constructor of
                  :class:`~deepmatcher.optim.SoftNLLLoss` criterion. Only used when
                  `criterion` param is None. Defaults to 0.05.
              save_every_prefix (string):
                  Prefix of the path to save model to, after end of
                  every N epochs, where N is determined by `save_every_freq` param.
                  E.g. setting this to "/path/to/saved/model" will save models to
                  "/path/to/saved/model_ep1.pth", "/path/to/saved/model_ep2.pth", etc.
                  Models will not be saved periodically if this is None. Defaults to
                  None.
              save_every_freq (int):
                  Determines the frequency (number of epochs) for saving models periodically
                  to the path specified by the `save_every_prefix` param (has no effect if
                  that param is not set). Defaults to 1.
              batch_size (int):
                  Mini-batch size for SGD. For details on what this is
                  `see this video <https://www.coursera.org/learn/machine-learning/lecture/9zJUs/mini-batch-gradient-descent>`__.
                  Defaults to 32. This is a keyword only param.
              device (string):
                  The device on which to train the model ('cpu' or 'cuda'). If None, will use
                  first available GPU, or use CPU if no GPUs are available. Defaults to None.
                  This is a keyword only param.
              progress_style (string):
                  Sets the progress update style. One of 'bar' or 'log'. If 'bar', uses a
                  progress bar, updated every N batches. If 'log', prints training stats
                  every N batches. N is determined by the `log_freq` param.
                  This is a keyword only param.
              log_freq (int):
                  Number of batches between progress updates. Defaults to 5.
                  This is a keyword only param.
              sort_in_buckets (bool):
                  Whether to batch examples of similar lengths together. If True, minimizes
                  amount of padding needed while producing freshly shuffled batches for each
                  new epoch. Implemented using :func:`torchtext.data.pool`.
                  Defaults to True. This is a keyword only param.
  
          Returns:
              float: The best F1 score obtained by the model on the validation dataset.
          """
      return Runner.train(self, *args, **kwargs)
  
imports: import copy
  import logging
  from collections import Mapping
  import dill
  import six
  import deepmatcher
  import torch
  import torch.nn
  from .None import _utils
  from ..data import MatchingDataset, MatchingIterator
  from ..runner import Runner
  from ..utils import Bunch, tally_parameters
label_desc: Use image node_id 2 for calling the MatchingModel obj's underlying member method code with example usage: obj.run_train() and returns: Runner