class_docstr: Estimator Class for easy model training
  
  :py:class:`Estimator` can be used to facilitate the training & validation process
  
  
  Parameters
  ----------
  net : gluon.Block
      The model used for training.
  loss : gluon.loss.Loss
      Loss (objective) function to calculate during training.
  train_metrics : EvalMetric or list of EvalMetric
      Training metrics for evaluating models on training dataset.
  val_metrics : EvalMetric or list of EvalMetric
      Validation metrics for evaluating models on validation dataset.
  initializer : Initializer
      Initializer to initialize the network.
  trainer : Trainer
      Trainer to apply optimizer on network parameters.
  device : Device or list of Device
      Device(s) to run the training on.
  val_net : gluon.Block
      The model used for validation. The validation model does not necessarily belong to
      the same model class as the training model. But the two models typically share the
      same architecture. Therefore the validation model can reuse parameters of the
      training model.
  
      The code example of consruction of val_net sharing the same network parameters as
      the training net is given below:
  
      >>> net = _get_train_network()
      >>> val_net = _get_test_network()
      >>> val_net.share_parameters(net.collect_params())
      >>> net.initialize(device=device)
      >>> est = Estimator(net, loss, val_net=val_net)
  
      Proper namespace match is required for weight sharing between two networks. Most networks
      inheriting :py:class:`Block` can share their parameters correctly. An exception is
      Sequential networks that Block scope must be specified for correct weight sharing. For
      the  naming in mxnet Gluon API, please refer to the site
      (https://mxnet.apache.org/api/python/docs/tutorials/packages/gluon/blocks/naming.html)
      for future information.
  val_loss : gluon.loss.loss
      Loss (objective) function to calculate during validation. If set val_loss
      None, it will use the same loss function as self.loss
  batch_processor: BatchProcessor
      BatchProcessor provides customized fit_batch() and evaluate_batch() methods
class_docstr_tok: ["Estimator","Class","for","easy","model","training",":","py",":","class",":","`","Estimator","`","can","be","used","to","facilitate","the","training","&","validation","process","Parameters","--","--","--","--","--","net",":","gluon.Block","The","model","used","for","training",".","loss",":","gluon.loss.Loss","Loss","(","objective",")","function","to","calculate","during","training",".","train_metrics",":","EvalMetric","or","list","of","EvalMetric","Training","metrics","for","evaluating","models","on","training","dataset",".","val_metrics",":","EvalMetric","or","list","of","EvalMetric","Validation","metrics","for","evaluating","models","on","validation","dataset",".","initializer",":","Initializer","Initializer","to","initialize","the","network",".","trainer",":","Trainer","Trainer","to","apply","optimizer","on","network","parameters",".","device",":","Device","or","list","of","Device","Device","(","s",")","to","run","the","training","on",".","val_net",":","gluon.Block","The","model","used","for","validation",".","The","validation","model","does","not","necessarily","belong","to","the","same","model","class","as","the","training","model",".","But","the","two","models","typically","share","the","same","architecture",".","Therefore","the","validation","model","can","reuse","parameters","of","the","training","model",".","The","code","example","of","consruction","of","val_net","sharing","the","same","network","parameters","as","the","training","net","is","given","below",":",">",">",">","net","=","_get_train_network","(",")",">",">",">","val_net","=","_get_test_network","(",")",">",">",">","val_net.share_parameters","(","net.collect_params","(",")",")",">",">",">","net.initialize","(","device=device",")",">",">",">","est","=","Estimator","(","net",",","loss",",","val_net=val_net",")","Proper","namespace","match","is","required","for","weight","sharing","between","two","networks",".","Most","networks","inheriting",":","py",":","class",":","`","Block","`","can","share","their","parameters","correctly",".","An","exception","is","Sequential","networks","that","Block","scope","must","be","specified","for","correct","weight","sharing",".","For","the","naming","in","mxnet","Gluon","API",",","please","refer","to","the","site","(","https",":","\/\/mxnet.apache.org\/api\/python\/docs\/tutorials\/packages\/gluon\/blocks\/naming.html",")","for","future","information",".","val_loss",":","gluon.loss.loss","Loss","(","objective",")","function","to","calculate","during","validation",".","If","set","val_loss","None",",","it","will","use","the","same","loss","function","as","self.loss","batch_processor",":","BatchProcessor","BatchProcessor","provides","customized","fit_batch","(",")","and","evaluate_batch","(",")","methods"]
docstr: Trains the model with a given :py:class:`DataLoader` for a specified
  number of epochs or batches. The batch size is inferred from the
  data loader's batch_size.
  
  This function calls :py:func:`fit_batch` on each of the batches from the
  training data loader. Thus, for custom use cases, it's possible to inherit the
  estimator class and override :py:func:`fit_batch`.
  
  Parameters
  ----------
  train_data : DataLoader
      Training data loader with data and labels.
  val_data : DataLoader, default None
      Validation data loader with data and labels.
  epochs : int, default None
      Number of epochs to iterate on the training data.
      You can only specify one and only one type of iteration(epochs or batches).
  event_handlers : EventHandler or list of EventHandler
      List of :py:class:`EventHandlers` to apply during training. Besides
      the event handlers specified here, a StoppingHandler,
      LoggingHandler and MetricHandler will be added by default if not
      yet specified manually. If validation data is provided, a
      ValidationHandler is also added if not already specified.
  batches : int, default None
      Number of batches to iterate on the training data.
      You can only specify one and only one type of iteration(epochs or batches).
  batch_axis : int, default 0
      Batch axis to split the training data into devices.
docstr_tok: ["Trains","the","model","with","a","given",":","py",":","class",":","`","DataLoader","`","for","a","specified","number","of","epochs","or","batches",".","The","batch","size","is","inferred","from","the","data","loader","'s","batch_size",".","This","function","calls",":","py",":","func",":","`","fit_batch","`","on","each","of","the","batches","from","the","training","data","loader",".","Thus",",","for","custom","use","cases",",","it","'s","possible","to","inherit","the","estimator","class","and","override",":","py",":","func",":","`","fit_batch","`",".","Parameters","--","--","--","--","--","train_data",":","DataLoader","Training","data","loader","with","data","and","labels",".","val_data",":","DataLoader",",","default","None","Validation","data","loader","with","data","and","labels",".","epochs",":","int",",","default","None","Number","of","epochs","to","iterate","on","the","training","data",".","You","can","only","specify","one","and","only","one","type","of","iteration","(","epochs","or","batches",")",".","event_handlers",":","EventHandler","or","list","of","EventHandler","List","of",":","py",":","class",":","`","EventHandlers","`","to","apply","during","training",".","Besides","the","event","handlers","specified","here",",","a","StoppingHandler",",","LoggingHandler","and","MetricHandler","will","be","added","by","default","if","not","yet","specified","manually",".","If","validation","data","is","provided",",","a","ValidationHandler","is","also","added","if","not","already","specified",".","batches",":","int",",","default","None","Number","of","batches","to","iterate","on","the","training","data",".","You","can","only","specify","one","and","only","one","type","of","iteration","(","epochs","or","batches",")",".","batch_axis",":","int",",","default","0","Batch","axis","to","split","the","training","data","into","devices","."]
code: def fit(
      self,
      train_data,
      val_data=None,
      epochs=None,
      event_handlers=None,
      batches=None,
      batch_axis=0,
  ):
      """Trains the model with a given :py:class:`DataLoader` for a specified
      number of epochs or batches. The batch size is inferred from the
      data loader's batch_size.
  
      This function calls :py:func:`fit_batch` on each of the batches from the
      training data loader. Thus, for custom use cases, it's possible to inherit the
      estimator class and override :py:func:`fit_batch`.
  
      Parameters
      ----------
      train_data : DataLoader
          Training data loader with data and labels.
      val_data : DataLoader, default None
          Validation data loader with data and labels.
      epochs : int, default None
          Number of epochs to iterate on the training data.
          You can only specify one and only one type of iteration(epochs or batches).
      event_handlers : EventHandler or list of EventHandler
          List of :py:class:`EventHandlers` to apply during training. Besides
          the event handlers specified here, a StoppingHandler,
          LoggingHandler and MetricHandler will be added by default if not
          yet specified manually. If validation data is provided, a
          ValidationHandler is also added if not already specified.
      batches : int, default None
          Number of batches to iterate on the training data.
          You can only specify one and only one type of iteration(epochs or batches).
      batch_axis : int, default 0
          Batch axis to split the training data into devices.
      """
      if not isinstance(train_data, DataLoader):
          raise ValueError(
              "Estimator only support input as Gluon DataLoader. Alternatively, you "
              "can transform your DataIter or any NDArray into Gluon DataLoader. "
              "Refer to gluon.data.dataloader"
          )
  
      # must specify one and only one of epochs or batches
      if (not epochs) == (not batches):
          raise ValueError(
              "Fit only support exactly one type of iteration, "
              "train by number of epochs or number of batches."
              "Please specify one and only one of: epochs or batches."
          )
  
      self.max_epoch = epochs
      self.max_batch = batches
      self.batch_axis = batch_axis
  
      # provide default handlers
      event_handlers = self._prepare_default_handlers(
          val_data, event_handlers
      )
  
      (
          train_begin,
          epoch_begin,
          batch_begin,
          batch_end,
          epoch_end,
          train_end,
      ) = self._categorize_handlers(event_handlers)
  
      # pass a reference to all event handlers
      estimator_ref = self
      # training begin
      for handler in train_begin:
          handler.train_begin(estimator_ref)
  
      while True:
          # epoch begin
          for handler in epoch_begin:
              handler.epoch_begin(estimator_ref)
  
          for batch in train_data:
              # batch begin
              for handler in batch_begin:
                  handler.batch_begin(estimator_ref, batch=batch)
  
              _, label, pred, loss = self.batch_processor.fit_batch(
                  estimator_ref, batch, batch_axis
              )
              # batch end
  
              batch_end_result = []
              for handler in batch_end:
                  batch_end_result.append(
                      handler.batch_end(
                          estimator_ref,
                          batch=batch,
                          pred=pred,
                          label=label,
                          loss=loss,
                      )
                  )
              # if any handler signaled to stop
              if any(batch_end_result):
                  break
  
          # epoch end
          epoch_end_result = []
          for handler in epoch_end:
              epoch_end_result.append(handler.epoch_end(estimator_ref))
          # if any handler signaled to stop
          if any(epoch_end_result):
              break
  
      # train end
      for handler in train_end:
          handler.train_end(estimator_ref)
  
imports: import copy
  import logging
  import sys
  import warnings
  from .event_handler import MetricHandler, ValidationHandler, LoggingHandler, StoppingHandler, GradientUpdateHandler
  from .event_handler import TrainBegin, EpochBegin, BatchBegin, BatchEnd, EpochEnd, TrainEnd
  from .event_handler import _check_event_handlers
  from .utils import _check_metrics, _suggest_metric_for_loss, _check_handler_metric_ref
  from ...data import DataLoader
  from ...loss import Loss
  from ...trainer import Trainer
  from ...utils import split_and_load
  from ....device import Device, cpu, gpu, num_gpus
  from ...metric import Loss
  from .batch_processor import BatchProcessor
label_desc: Use image node_id 15 for calling the Estimator obj's underlying member method code with example usage: obj.fit(train_data, val_data, epochs, event_handlers, batches, batch_axis) without return types