=======
symfer
=======

|symfer| is a tool suite, written mostly in `Python <http://www.python.org>`_, for performing probabilistic inference: calculating arbitrary probabilities like :math:`\cprob{X}{Z{=}z}`, given a model :math:`\prob{X,Y,Z}` and observation :math:`Z{=}z`. A script for this specific query is constructed during a *symbolic* phase in Python, and executed in a separate numeric phase (possibly on a different platform/machine).

Basic usage
===========

From the Python prompt, load a Bayesian network model (stored in `Hugin <http://www.hugin.com>`_ format)::

    >>> import symfer as s
    >>> model = s.loadhugin('extended-student.net')
    
Select a query variable :math:`H` and set observation :math:`S{=}s_1`::

    >>> query = ['H']
    >>> obs = {'S':'s1'}

*Symbolic phase*: construct an inference script (here using variable elimination with minweight heuristic).

    >>> ve = s.ve_minweight(model,query)
    >>> ve_obs = s.indextree(obs,ve)

.. note::
    
    It is easy to tweak the supplied :ref:`inference algorithms` or even roll your own.
    
*Numeric phase*: Execute the script, here using the internal evaluator.

    >>> s.evaluate(ve_obs)
    Multinom(dom=[{'H': ['h0', 'h1']}],par=[0.0677442825, 0.20725571750000002])

This result represents the distribution :math:`\prob{H,S{=}s_1}`.

.. note::

    Instead of directly executing the script from the same Python interpreter, it can also be evaluated at a
    different machine and/or using Java/C. See :ref:`evaluation options`.


Download
============

Source distribution:

- |sdist-tar-file|
- |sdist-zip-file|

See :ref:`installing` for other options and further instructions.


Tutorial
=================

.. toctree::
   :maxdepth: 2
   
   installing
   models
   factor_algebra
   inference
   evaluation_options
   yaml

Reference
==================

* :ref:`genindex`
* :ref:`modindex`

License
=========

|symfer| is licensed under the :download:`2-clause BSD license <../../LICENSE.txt>`.

If you use it in published research, please refer to the following article:
`[pdf] <http://leo.ugr.es/pgm2012/proceedings/eproceedings/evers_a_framework.pdf>`_

    Sander Evers and Peter J.F. Lucas,
    *A framework for development, teaching and deployment of inference algorithms*.
    In: Andrés Cano, Manuel Gómez-Olmedo, Thomas D. Nielsen (Eds.), *PGM 2012, Sixth European workshop on Probabilistic Graphical Models,
    Electronic proceedings*, pp. 99--106, http://leo.ugr.es/pgm2012/proceedings/proceedings.pdf


Development
===========

Currently, |symfer| has only one developer: Sander Evers. However, he is happy to accept any contributions, or team up with you if you'd like
to share some responsibility. Reach him at ``sandr {at} dds {dot} nl``.

Acknowledgements
================

This software has evolved from a research tool developed at the University of Twente `(DB group) <http://db.ewi.utwente.nl>`_ and Radboud University Nijmegen `(MBSD group) <http://www.mbsd.cs.ru.nl>`_.

.. image:: python-powered-w-100x40.png