=======
The API
=======

pomegranate has a minimal core API that is made possible because all models are treated as probability distributions regardless of their complexity. This point is repeated throughout the documentation because it has important consequences for how the package is designed and also for how one should think about designing probabilistic models. Although each model documentation page has an API reference showing the full set of methods and parameters for each model, each models has the following methods:. 

.. code-block:: python

	>>> model.probability(X)

This method takes in a set of examples (either 2D or 3D depending on the model) and returns a vector of probabilities.

.. code-block:: python

	>>> model.log_probability(X)

This method takes in a set of examples (either 2D or 3D depending on the model) and returns a vector of log probabilities. Log probabilities are more numerically stable and, in fact, calls to `model.probability` just exponentiate the value returned from this call.

.. code-block:: python

	>>> model.fit(X, sample_weight=None)

This method will fit the model to the given data that is optionally weighted. If the model is a simple probability distribution, a Bayes classifier, or a Bayesian network with fully observed features, the method will use maximum likelihood estimates. For other models and settings, the method will use expectation-maximization to fit the model parameters. When a structure is not provided for hidden Markov models or Bayesian networks, this method will jointly learn the structure and the parameters of the model. The shape of data should be (n, d) or (n, l, d) depending on if there is a length dimension, where n is the number of samples, l is the length of the data, and d is the dimensionality. Sample weights should either be a vector of non-negative numbers of size (n,) or a matrix of size (n, d).

.. code-block:: python

	>>> model.summarize(X, sample_weight=None)

This method is the first step of the two step out-of-core learning API. The method will take in a data and optional weights and extract the sufficient statistics that allow for an exact update and added to the cached values. Because these sufficient statistics are additive one can derive an exact update from multiple calls to this method without having to store an entire data set in memory.

.. code-block:: python

	>>> model.from_summaries() 

This method is the second step in the out-of-core learning API. The method uses the extracted and aggregated sufficient statistics to derive exact parameter updates for the model. After the parameters are updated, the stored sufficient statistics will be zeroed out.


Compositional Methods
---------------------

For models that are composed of other models/distributions, e.g. mixture models, hidden Markov models, and Bayesian networks, there are additional methods that relate to inferring how the data relates to each of these distributions. For example, instead of just calculating the log probability of an example under an entire mixture model, one might want to calculate the posterior probability that the data was generated by each of the distributions. These posterior probabilities are found by applying Bayes' rule, which connects prior probabilities and likelihoods to posterior probabilities.

.. code-block:: python

	>>> model.predict(X)

This method will return the most likely inferred value for each example in the data. In the case of Bayesian networks operating on incomplete data, this inferred value is the most likely value that each variable takes given the structure of the model and the observed data. For all other methods, this is the most likely component that explains the data, P(M|D).

.. code-block:: python

	>>> model.predict_proba(X)

This returns the matrix of posterior probabilities P(M|D) directly. The predict method simply runs an argmax over this matrix.

.. code-block:: python

	>>> model.predict_log_proba(X)

This returns the matrix of log posterior probabilities for numerical stability.


API Reference
-------------

Distributions
=============

.. automodule:: pomegranate.distributions
   :members: Bernoulli, Categorical, ConditionalCategorical, JointCategorical, DiracDelta, Exponential, Gamma, Normal, Poisson, StudentT, Uniform, ZeroInflated

Models
======

.. autoclass:: pomegranate.bayes_classifier.BayesClassifier

.. autoclass:: pomegranate.gmm.GeneralMixtureModel

.. autoclass:: pomegranate.hmm.DenseHMM

.. autoclass:: pomegranate.hmm.SparseHMM

.. autoclass:: pomegranate.markov_chain.MarkovChain

.. autoclass:: pomegranate.bayesian_network.BayesianNetwork

.. autoclass:: pomegranate.factor_graph.FactorGraph