class_docstr: A base hidden Markov model.
  
  A hidden Markov model is an extension of a mixture model to sequences by
  including a transition matrix between the elements of the mixture. Each of
  the algorithms for a hidden Markov model are essentially just a revision
  of those algorithms to incorporate this transition matrix.
  
  There are two main ways one can implement a hidden Markov model: either the
  transition matrix can be implemented in a dense, or a sparse, manner. If the
  transition matrix is dense, implementing it in a dense manner allows for
  the primary computation to use matrix multiplications which can be very
  fast. However, if the matrix is sparse, these matrix multiplications will
  be fairly slow and end up significantly slower than the sparse version of
  a matrix multiplication.
  
  This object is a wrapper for both implementations, which can be specified
  using the `kind` parameter. Choosing the right implementation will not
  effect the accuracy of the results but will change the speed at which they
  are calculated.         
  
  Separately, there are two ways to instantiate the hidden Markov model. The
  first is by passing in a set of distributions, a dense transition matrix, 
  and optionally start/end probabilities. The second is to initialize the
  object without these and then to add edges using the `add_edge` method
  and to add nodes using the `add_nodes` method. Importantly, the way that
  you choose to initialize the hidden Markov model is independent of the
  implementation that you end up choosing. If you pass in a dense transition
  matrix, this will be converted to a sparse matrix with all the zeros
  dropped if you choose `kind='sparse'`.
  
  
  Parameters
  ----------
  distributions: tuple or list
          A set of distribution objects. These objects do not need to be
          initialized, i.e., can be "Normal()". 
  
  edges: numpy.ndarray, torch.Tensor, or None. shape=(k,k), optional
          A dense transition matrix of probabilities for how each node or
          distribution passed in connects to each other one. This can contain
          many zeroes, and when paired with `kind='sparse'`, will drop those
          elements from the matrix. Default is None.
  
  starts: list, numpy.ndarray, torch.Tensor, or None. shape=(k,), optional
          The probability of starting at each node. If not provided, assumes
          these probabilities are uniform. Default is None.
  
  ends: list, numpy.ndarray, torch.Tensor, or None. shape=(k,), optional
          The probability of ending at each node. If not provided, assumes
          these probabilities are uniform. Default is None.
  
  kind: str, 'sparse' or 'dense', optional
          The underlying implementation of the transition matrix to use.
          Default is 'sparse'. 
  
  init: str, optional
          The initialization to use for the k-means initialization approach.
          Default is 'first-k'. Must be one of:
  
                  'first-k': Use the first k examples from the data set
                  'random': Use a random set of k examples from the data set
                  'submodular-facility-location': Use a facility location submodular
                          objective to initialize the k-means algorithm
                  'submodular-feature-based': Use a feature-based submodular objective
                          to initialize the k-means algorithm.
  
  max_iter: int, optional
          The number of iterations to do in the EM step, which for HMMs is
          sometimes called Baum-Welch. Default is 10.
  
  tol: float, optional
          The threshold at which to stop during fitting when the improvement
          goes under. Default is 0.1.
  
  inertia: float, [0, 1], optional
          Indicates the proportion of the update to apply to the parameters
          during training. When the inertia is 0.0, the update is applied in
          its entirety and the previous parameters are ignored. When the
          inertia is 1.0, the update is entirely ignored and the previous
          parameters are kept, equivalently to if the parameters were frozen.
  
  frozen: bool, optional
          Whether all the parameters associated with this distribution are frozen.
          If you want to freeze individual pameters, or individual values in those
          parameters, you must modify the `frozen` attribute of the tensor or
          parameter directly. Default is False.
  
  random_state: int or None, optional
          The random state to make randomness deterministic. If None, not
          deterministic. Default is None.
  
  check_data: bool, optional
          Whether to check properties of the data and potentially recast it to
          torch.tensors. This does not prevent checking of parameters but can
          slightly speed up computation when you know that your inputs are valid.
          Setting this to False is also necessary for compiling.
  
  verbose: bool, optional
          Whether to print the improvement and timings during training.
class_docstr_tok: ["A","base","hidden","Markov","model",".","A","hidden","Markov","model","is","an","extension","of","a","mixture","model","to","sequences","by","including","a","transition","matrix","between","the","elements","of","the","mixture",".","Each","of","the","algorithms","for","a","hidden","Markov","model","are","essentially","just","a","revision","of","those","algorithms","to","incorporate","this","transition","matrix",".","There","are","two","main","ways","one","can","implement","a","hidden","Markov","model",":","either","the","transition","matrix","can","be","implemented","in","a","dense",",","or","a","sparse",",","manner",".","If","the","transition","matrix","is","dense",",","implementing","it","in","a","dense","manner","allows","for","the","primary","computation","to","use","matrix","multiplications","which","can","be","very","fast",".","However",",","if","the","matrix","is","sparse",",","these","matrix","multiplications","will","be","fairly","slow","and","end","up","significantly","slower","than","the","sparse","version","of","a","matrix","multiplication",".","This","object","is","a","wrapper","for","both","implementations",",","which","can","be","specified","using","the","`","kind","`","parameter",".","Choosing","the","right","implementation","will","not","effect","the","accuracy","of","the","results","but","will","change","the","speed","at","which","they","are","calculated",".","Separately",",","there","are","two","ways","to","instantiate","the","hidden","Markov","model",".","The","first","is","by","passing","in","a","set","of","distributions",",","a","dense","transition","matrix",",","and","optionally","start\/end","probabilities",".","The","second","is","to","initialize","the","object","without","these","and","then","to","add","edges","using","the","`","add_edge","`","method","and","to","add","nodes","using","the","`","add_nodes","`","method",".","Importantly",",","the","way","that","you","choose","to","initialize","the","hidden","Markov","model","is","independent","of","the","implementation","that","you","end","up","choosing",".","If","you","pass","in","a","dense","transition","matrix",",","this","will","be","converted","to","a","sparse","matrix","with","all","the","zeros","dropped","if","you","choose","`","kind='sparse","'","`",".","Parameters","--","--","--","--","--","distributions",":","tuple","or","list","A","set","of","distribution","objects",".","These","objects","do","not","need","to","be","initialized",",","i.e.",",","can","be","``","Normal","(",")","''",".","edges",":","numpy.ndarray",",","torch.Tensor",",","or","None",".","shape=","(","k",",","k",")",",","optional","A","dense","transition","matrix","of","probabilities","for","how","each","node","or","distribution","passed","in","connects","to","each","other","one",".","This","can","contain","many","zeroes",",","and","when","paired","with","`","kind='sparse","'","`",",","will","drop","those","elements","from","the","matrix",".","Default","is","None",".","starts",":","list",",","numpy.ndarray",",","torch.Tensor",",","or","None",".","shape=","(","k",",",")",",","optional","The","probability","of","starting","at","each","node",".","If","not","provided",",","assumes","these","probabilities","are","uniform",".","Default","is","None",".","ends",":","list",",","numpy.ndarray",",","torch.Tensor",",","or","None",".","shape=","(","k",",",")",",","optional","The","probability","of","ending","at","each","node",".","If","not","provided",",","assumes","these","probabilities","are","uniform",".","Default","is","None",".","kind",":","str",",","'sparse","'","or","'dense","'",",","optional","The","underlying","implementation","of","the","transition","matrix","to","use",".","Default","is","'sparse","'",".","init",":","str",",","optional","The","initialization","to","use","for","the","k-means","initialization","approach",".","Default","is","'first-k","'",".","Must","be","one","of",":","'first-k","'",":","Use","the","first","k","examples","from","the","data","set","'random","'",":","Use","a","random","set","of","k","examples","from","the","data","set","'submodular-facility-location","'",":","Use","a","facility","location","submodular","objective","to","initialize","the","k-means","algorithm","'submodular-feature-based","'",":","Use","a","feature-based","submodular","objective","to","initialize","the","k-means","algorithm",".","max_iter",":","int",",","optional","The","number","of","iterations","to","do","in","the","EM","step",",","which","for","HMMs","is","sometimes","called","Baum-Welch",".","Default","is","10.","tol",":","float",",","optional","The","threshold","at","which","to","stop","during","fitting","when","the","improvement","goes","under",".","Default","is","0.1.","inertia",":","float",",","[","0",",","1","]",",","optional","Indicates","the","proportion","of","the","update","to","apply","to","the","parameters","during","training",".","When","the","inertia","is","0.0",",","the","update","is","applied","in","its","entirety","and","the","previous","parameters","are","ignored",".","When","the","inertia","is","1.0",",","the","update","is","entirely","ignored","and","the","previous","parameters","are","kept",",","equivalently","to","if","the","parameters","were","frozen",".","frozen",":","bool",",","optional","Whether","all","the","parameters","associated","with","this","distribution","are","frozen",".","If","you","want","to","freeze","individual","pameters",",","or","individual","values","in","those","parameters",",","you","must","modify","the","`","frozen","`","attribute","of","the","tensor","or","parameter","directly",".","Default","is","False",".","random_state",":","int","or","None",",","optional","The","random","state","to","make","randomness","deterministic",".","If","None",",","not","deterministic",".","Default","is","None",".","check_data",":","bool",",","optional","Whether","to","check","properties","of","the","data","and","potentially","recast","it","to","torch.tensors",".","This","does","not","prevent","checking","of","parameters","but","can","slightly","speed","up","computation","when","you","know","that","your","inputs","are","valid",".","Setting","this","to","False","is","also","necessary","for","compiling",".","verbose",":","bool",",","optional","Whether","to","print","the","improvement","and","timings","during","training","."]
docstr: Fit the model to sequences with optional weights and priors.
  
  This method implements the core of the learning process. For hidden
  Markov models, this is a form of EM called "Baum-Welch" or "structured
  EM". This iterative algorithm will proceed until converging, either
  according to the threshold set by `tol` or until the maximum number
  of iterations set by `max_iter` has been hit.
  
  This method is largely a wrapper around the `summarize` and
  `from_summaries` methods. It's primary contribution is serving as a
  loop around these functions and to monitor convergence.
  
  Unlike other HMM methods, this method can handle variable length
  sequences by accepting a list of tensors where each tensor has a
  different sequence length. Then, summarization is done on each tensor
  sequentially. This will provide an exact update as if the entire data
  set was seen at the same time but will allow batched operations to be
  performed on each variable length tensor.
  
  
  Parameters
  ----------
  X: list, numpy.ndarray, torch.Tensor, shape=(-1, len, self.d)
          A set of examples to evaluate. Because sequences can be variable
          length, there are three ways to format the sequences.
          
                  1. Pass in a tensor of shape (n, length, dim), which can only 
                  be done when each sequence is the same length. 
  
                  2. Pass in a list of 3D tensors where each tensor has the shape 
                  (n, length, dim). In this case, each tensor is a collection of 
                  sequences of the same length and so sequences of different 
                  lengths can be trained on. 
  
                  3. Pass in a list of 2D tensors where each tensor has the shape
                  (length, dim). In this case, sequences of the same length will
                  be grouped together into the same tensor and fitting will
                  proceed as if you had passed in data like way 2.
  
  sample_weight: list, numpy.ndarray, torch.Tensor or None, optional
          A set of weights for the examples. These must follow the same format
          as X.
  
  priors: list, numpy.ndarray, torch.Tensor, shape=(-1, -1, self.k)
          Prior probabilities of assigning each symbol to each node. If not
          provided, do not include in the calculations (conceptually
          equivalent to a uniform probability, but without scaling the
          probabilities). This can be used to assign labels to observations
          by setting one of the probabilities for an observation to 1.0.
          Note that this can be used to assign hard labels, but does not
          have the same semantics for soft labels, in that it only
          influences the initial estimate of an observation being generated
          by a component, not gives a target. Must be formatted in the same
          shape as X. Default is None.
  
  
  Returns
  -------
  self
docstr_tok: ["Fit","the","model","to","sequences","with","optional","weights","and","priors",".","This","method","implements","the","core","of","the","learning","process",".","For","hidden","Markov","models",",","this","is","a","form","of","EM","called","``","Baum-Welch","''","or","``","structured","EM","''",".","This","iterative","algorithm","will","proceed","until","converging",",","either","according","to","the","threshold","set","by","`","tol","`","or","until","the","maximum","number","of","iterations","set","by","`","max_iter","`","has","been","hit",".","This","method","is","largely","a","wrapper","around","the","`","summarize","`","and","`","from_summaries","`","methods",".","It","'s","primary","contribution","is","serving","as","a","loop","around","these","functions","and","to","monitor","convergence",".","Unlike","other","HMM","methods",",","this","method","can","handle","variable","length","sequences","by","accepting","a","list","of","tensors","where","each","tensor","has","a","different","sequence","length",".","Then",",","summarization","is","done","on","each","tensor","sequentially",".","This","will","provide","an","exact","update","as","if","the","entire","data","set","was","seen","at","the","same","time","but","will","allow","batched","operations","to","be","performed","on","each","variable","length","tensor",".","Parameters","--","--","--","--","--","X",":","list",",","numpy.ndarray",",","torch.Tensor",",","shape=","(","-1",",","len",",","self.d",")","A","set","of","examples","to","evaluate",".","Because","sequences","can","be","variable","length",",","there","are","three","ways","to","format","the","sequences",".","1",".","Pass","in","a","tensor","of","shape","(","n",",","length",",","dim",")",",","which","can","only","be","done","when","each","sequence","is","the","same","length",".","2",".","Pass","in","a","list","of","3D","tensors","where","each","tensor","has","the","shape","(","n",",","length",",","dim",")",".","In","this","case",",","each","tensor","is","a","collection","of","sequences","of","the","same","length","and","so","sequences","of","different","lengths","can","be","trained","on",".","3",".","Pass","in","a","list","of","2D","tensors","where","each","tensor","has","the","shape","(","length",",","dim",")",".","In","this","case",",","sequences","of","the","same","length","will","be","grouped","together","into","the","same","tensor","and","fitting","will","proceed","as","if","you","had","passed","in","data","like","way","2.","sample_weight",":","list",",","numpy.ndarray",",","torch.Tensor","or","None",",","optional","A","set","of","weights","for","the","examples",".","These","must","follow","the","same","format","as","X.","priors",":","list",",","numpy.ndarray",",","torch.Tensor",",","shape=","(","-1",",","-1",",","self.k",")","Prior","probabilities","of","assigning","each","symbol","to","each","node",".","If","not","provided",",","do","not","include","in","the","calculations","(","conceptually","equivalent","to","a","uniform","probability",",","but","without","scaling","the","probabilities",")",".","This","can","be","used","to","assign","labels","to","observations","by","setting","one","of","the","probabilities","for","an","observation","to","1.0",".","Note","that","this","can","be","used","to","assign","hard","labels",",","but","does","not","have","the","same","semantics","for","soft","labels",",","in","that","it","only","influences","the","initial","estimate","of","an","observation","being","generated","by","a","component",",","not","gives","a","target",".","Must","be","formatted","in","the","same","shape","as","X",".","Default","is","None",".","Returns","--","--","--","-","self"]
code: def fit(self, X, sample_weight=None, priors=None):
      """Fit the model to sequences with optional weights and priors.
  
      This method implements the core of the learning process. For hidden
      Markov models, this is a form of EM called "Baum-Welch" or "structured
      EM". This iterative algorithm will proceed until converging, either
      according to the threshold set by `tol` or until the maximum number
      of iterations set by `max_iter` has been hit.
  
      This method is largely a wrapper around the `summarize` and
      `from_summaries` methods. It's primary contribution is serving as a
      loop around these functions and to monitor convergence.
  
      Unlike other HMM methods, this method can handle variable length
      sequences by accepting a list of tensors where each tensor has a
      different sequence length. Then, summarization is done on each tensor
      sequentially. This will provide an exact update as if the entire data
      set was seen at the same time but will allow batched operations to be
      performed on each variable length tensor.
  
  
      Parameters
      ----------
      X: list, numpy.ndarray, torch.Tensor, shape=(-1, len, self.d)
              A set of examples to evaluate. Because sequences can be variable
              length, there are three ways to format the sequences.
  
                      1. Pass in a tensor of shape (n, length, dim), which can only
                      be done when each sequence is the same length.
  
                      2. Pass in a list of 3D tensors where each tensor has the shape
                      (n, length, dim). In this case, each tensor is a collection of
                      sequences of the same length and so sequences of different
                      lengths can be trained on.
  
                      3. Pass in a list of 2D tensors where each tensor has the shape
                      (length, dim). In this case, sequences of the same length will
                      be grouped together into the same tensor and fitting will
                      proceed as if you had passed in data like way 2.
  
      sample_weight: list, numpy.ndarray, torch.Tensor or None, optional
              A set of weights for the examples. These must follow the same format
              as X.
  
      priors: list, numpy.ndarray, torch.Tensor, shape=(-1, -1, self.k)
              Prior probabilities of assigning each symbol to each node. If not
              provided, do not include in the calculations (conceptually
              equivalent to a uniform probability, but without scaling the
              probabilities). This can be used to assign labels to observations
              by setting one of the probabilities for an observation to 1.0.
              Note that this can be used to assign hard labels, but does not
              have the same semantics for soft labels, in that it only
              influences the initial estimate of an observation being generated
              by a component, not gives a target. Must be formatted in the same
              shape as X. Default is None.
  
  
      Returns
      -------
      self
      """
  
      X, sample_weight, priors = partition_sequences(
          X, sample_weight=sample_weight, priors=priors, n_dists=self.k
      )
  
      # Initialize by concatenating across sequences
      if not self._initialized:
          X_ = torch.cat(X, dim=1)
  
          if sample_weight is None:
              self._initialize(X_)
          else:
              w_ = torch.cat(sample_weight, dim=1)
              self._initialize(X_, sample_weight=w_)
  
      logp, last_logp = None, None
      for i in range(self.max_iter):
          start_time = time.time()
  
          # Train loop across all tensors
          logp = 0
          for j, X_ in enumerate(X):
              w_ = None if sample_weight is None else sample_weight[j]
              p_ = None if priors is None else priors[j]
  
              logp += self.summarize(
                  X_, sample_weight=w_, priors=p_
              ).sum()
  
          # Calculate and check improvement and optionally print it
          if i > 0:
              improvement = logp - last_logp
              duration = time.time() - start_time
  
              if self.verbose:
                  print(
                      "[{}] Improvement: {}, Time: {:4.4}s".format(
                          i, improvement, duration
                      )
                  )
  
              if improvement < self.tol:
                  self._reset_cache()
                  return self
  
          last_logp = logp
          self.from_summaries()
  
      # Calculate for the last iteration
      if self.verbose:
          logp = 0
          for j, X_ in enumerate(X):
              w_ = None if sample_weight is None else sample_weight[j]
              p_ = None if priors is None else priors[j]
  
              logp += self.summarize(
                  X_, sample_weight=w_, priors=p_
              ).sum()
  
          improvement = logp - last_logp
          duration = time.time() - start_time
  
          print(
              "[{}] Improvement: {}, Time: {:4.4}s".format(
                  i + 1, improvement, duration
              )
          )
  
      self._reset_cache()
      return self
  
imports: import time
  import numpy
  import torch
  from .._utils import _cast_as_tensor
  from .._utils import _cast_as_parameter
  from .._utils import _check_parameter
  from .._utils import partition_sequences
  from ..distributions._distribution import Distribution
  from ..kmeans import KMeans
label_desc: Use image node_id 14 for calling the _BaseHMM obj's underlying member method code with example usage: obj.fit(X, sample_weight, priors) and returns: self, self