docs: update docs

unitn-sml · Mar 25, 2018 · f841428 · f841428
1 parent 11c540b
commit f841428
Show file tree

Hide file tree

Showing 248 changed files with 7,545 additions and 1,187 deletions.
diff --git a/docs/.buildinfo b/docs/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: ec1c0fe74ca0e34a685e7ef83366b246
+config: d95d9fafc74e858d83bcd9e7baed02a8
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_images/math/02d3e028612d7bc1888b46a573529b070f4a7d90.png b/docs/_images/math/02d3e028612d7bc1888b46a573529b070f4a7d90.png
diff --git a/docs/_images/math/3332d0883b3e2870152876bd9cb538cc9bd28268.png b/docs/_images/math/3332d0883b3e2870152876bd9cb538cc9bd28268.png
diff --git a/docs/_images/math/9f3bbcdc469b472347a481f299908cfc594fc6bf.png b/docs/_images/math/9f3bbcdc469b472347a481f299908cfc594fc6bf.png
diff --git a/docs/_sources/install.rst.txt b/docs/_sources/install.rst.txt
@@ -1,7 +1,7 @@
 Install
 =======
 
-Weaver can be installed via Pip::
+Pyconstruct can be installed via Pip::
 
     pip install pyconstruct
 
@@ -10,12 +10,16 @@ on `GitHub <https://github.com/unitn-sml/pyconstruct/releases/latest>`__::
 
     python setup.py install
 
-Currently, Pyconstruct is developed and maintained in Python 3.5 with a
-porting to Python 2.7 at every major release (the python2 branch does not always
-contain the most recent changes).
-
 Pyconstruct requires PyMzn to be installed on your machine, together with
-MiniZinc and at least one solver (e.g. `Gecode <http://www.gecode.org/>`__,
-`Gurobi <http://www.gurobi.com/>`__). Check-out `PyMzn installation guide
-<http://paolodragone.com/pymzn/install.html>`__ for details.
+`MiniZinc <https://github.com/MiniZinc/MiniZincIDE/releases/latest>`. Check-out
+`PyMzn installation guide <http://paolodragone.com/pymzn/install.html>`__ for
+details.
+
+Alongside MiniZinc, you will need a constraint solver. PyMzn supports many
+open-source solvers such as `Gecode <http://www.gecode.org/>` and `Chuffed
+<https://github.com/chuffed/chuffed>`. However, we recommend you give `Gurobi
+<http://www.gurobi.com/>`__ a try, it's blazingly fast for the kind of problems
+we usually solve in structured-output prediction, even more so when adding
+constraints to them. If you are in academia, they provide `free licenses
+<http://www.gurobi.com/academia/for-universities>` for research purpose.
 
diff --git a/docs/_sources/quick_start.rst.txt b/docs/_sources/quick_start.rst.txt
@@ -63,7 +63,7 @@ constraints and the features of the objects. To do so, we need to create a
         ]
         {% endcall %}
 
-    {% endset %}
+    {% endcall %}
 
     {{ solve(problem, model, discretize=True) }}
 
@@ -126,13 +126,51 @@ available in Pyconstruct out-of-the-box. You can load the domain by simply::
     ocr_dom = Domain('ocr')
 
 After defining the domain, using the predefined one or the `ocr.pmzn` file, we
-can start learning by instantiating a learner, say a `StructuredPerceptron`, and
-fitting the data::
+can start learning. We first need to instantiate a learner, say a
+`StructuredPerceptron`::
 
     from pyconstruct import StructuredPerceptron
     sp = StructuredPerceptron(domain=ocr_dom)
-    sp.fit(ocr.data, ocr.targets)
 
-This will take a while... If you need a quick benchmark, Pyconstruct contains
-pretrained models for many domains and learners (link).
+Pyconstruct is built to be compatible with most of the available utilities in
+Scikit-learn. One thing one would like to do at this point is to shuffle and
+split the data into training and test set. We can use Scikit-learn like this::
+
+    from sklearn.model_selection import train_test_split
+    X_train, X_test, Y_train, Y_test = train_test_split(ocr.data, ocr.target, test_size=0.05)
+
+Pyconstruct has also its own utilities to deal with structured data. In order
+to use train the `StructuredPerceptron` we will need to divide the data in
+mini-batches and use its `partial_fit` method.::
+
+    from pyconstruct.utils import batches
+
+    for X_batch, Y_batch in batches(X_train, Y_train, batch_size=50):
+        sp.partial_fit(X_batch, Y_batch)
+
+To evaluate the learner we will need a suitable metric. What it usually done
+used with OCR is the normalized Hamming loss. Pyconstruct has a Hamming loss
+function already available::
+
+    from pyconstruct.metrics import hamming
+
+    def loss(Y_pred, Y_true):
+        return hamming(Y_pred, Y_true, key='sequence', normalize=True).mean()
+
+The `hamming` function returns the Hamming distance between each pair of
+elements in the input arrays, so we take the mean. We can then compute the loss
+over the test set while training::
+
+    for X_batch, Y_batch in batches(X_train, Y_train, batch_size=50):
+        sp.partial_fit(X_batch, Y_batch)
+        Y_pred = sp.predict(X_test)
+        print('Loss = {}'.format(loss(Y_pred, Y_test)))
+
+This will take a while, depending on the computational resources you have. You
+can parallelize inference by passing `n_jobs` to the `Domain` constructor, as
+well as to the `hamming` function. Additionally, if you need a quick benchmark,
+Pyconstruct also contains pretrained models for many domains and learners
+(link).
+
+
 
diff --git a/docs/_sources/reference/datasets/generated/pyconstruct.datasets.conll00.rst.txt b/docs/_sources/reference/datasets/generated/pyconstruct.datasets.conll00.rst.txt
diff --git a/docs/_sources/reference/datasets/generated/pyconstruct.datasets.ocr.rst.txt b/docs/_sources/reference/datasets/generated/pyconstruct.datasets.ocr.rst.txt
diff --git a/docs/_sources/reference/datasets/generated/pyconstruct.datasets.utils.rst.txt b/docs/_sources/reference/datasets/generated/pyconstruct.datasets.utils.rst.txt
diff --git a/docs/_sources/reference/datasets/index.rst.txt b/docs/_sources/reference/datasets/index.rst.txt
@@ -9,8 +9,5 @@ Datasets
    load
    load_ocr
    load_conll00
-   ocr
-   conll00
-   utils
 
 .. automodule:: pyconstruct.datasets
diff --git a/docs/_sources/reference/domains/generated/pyconstruct.domains.get_info.rst.txt b/docs/_sources/reference/domains/generated/pyconstruct.domains.get_info.rst.txt
diff --git a/docs/_sources/reference/domains/generated/pyconstruct.domains.get_path.rst.txt b/docs/_sources/reference/domains/generated/pyconstruct.domains.get_path.rst.txt
diff --git a/docs/_sources/reference/domains/generated/pyconstruct.domains.get_source.rst.txt b/docs/_sources/reference/domains/generated/pyconstruct.domains.get_source.rst.txt
diff --git a/docs/_sources/reference/domains/generated/pyconstruct.domains.print_info.rst.txt b/docs/_sources/reference/domains/generated/pyconstruct.domains.print_info.rst.txt
diff --git a/docs/_sources/reference/domains/index.rst.txt b/docs/_sources/reference/domains/index.rst.txt
@@ -3,13 +3,14 @@ Domains
 
 .. currentmodule:: pyconstruct.domains
 
+.. toctree::
+   :maxdepth: 2
+
+   predefined
+
 .. autosummary::
    :toctree: generated/
 
-   get_path
-   get_source
-   get_info
-   print_info
    BaseDomain
    MiniZincDomain
 

diff --git a/docs/_sources/reference/domains/predefined.rst.txt b/docs/_sources/reference/domains/predefined.rst.txt
@@ -0,0 +1,7 @@
+Predefined domains
+------------------
+
+.. currentmodule:: pyconstruct.domains.predefined
+
+.. automodule:: pyconstruct.domains.predefined
+
diff --git a/docs/_sources/reference/index.rst.txt b/docs/_sources/reference/index.rst.txt
@@ -9,7 +9,7 @@ This is the reference manual of Weaver.
    datasets/index
    domains/index
    learners/index
-   metrics
+   metrics/index
    models/index
    utils/index
 
diff --git a/...rated/pyconstruct.metrics.hamming.rst.txt → ...rated/pyconstruct.metrics.hamming.rst.txt b/...rated/pyconstruct.metrics.hamming.rst.txt → ...rated/pyconstruct.metrics.hamming.rst.txt
diff --git a/docs/_sources/reference/metrics.rst.txt → .../_sources/reference/metrics/index.rst.txt b/docs/_sources/reference/metrics.rst.txt → .../_sources/reference/metrics/index.rst.txt
diff --git a/...ference/models/generated/pyconstruct.models.BaseModel.decision_function.rst.txt b/...ference/models/generated/pyconstruct.models.BaseModel.decision_function.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.BaseModel.decision\_function
+===============================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: BaseModel.decision_function
diff --git a/docs/_sources/reference/models/generated/pyconstruct.models.BaseModel.loss.rst.txt b/docs/_sources/reference/models/generated/pyconstruct.models.BaseModel.loss.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.BaseModel.loss
+=================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: BaseModel.loss
diff --git a/..._sources/reference/models/generated/pyconstruct.models.BaseModel.margin.rst.txt b/..._sources/reference/models/generated/pyconstruct.models.BaseModel.margin.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.BaseModel.margin
+===================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: BaseModel.margin
diff --git a/docs/_sources/reference/models/generated/pyconstruct.models.BaseModel.phi.rst.txt b/docs/_sources/reference/models/generated/pyconstruct.models.BaseModel.phi.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.BaseModel.phi
+================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: BaseModel.phi
diff --git a/...sources/reference/models/generated/pyconstruct.models.BaseModel.predict.rst.txt b/...sources/reference/models/generated/pyconstruct.models.BaseModel.predict.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.BaseModel.predict
+====================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: BaseModel.predict
diff --git a/docs/_sources/reference/models/generated/pyconstruct.models.BaseModel.rst.txt b/docs/_sources/reference/models/generated/pyconstruct.models.BaseModel.rst.txt
@@ -0,0 +1,31 @@
+pyconstruct.models.BaseModel
+============================
+
+.. currentmodule:: pyconstruct.models
+
+.. autoclass:: BaseModel
+
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree:
+
+      ~BaseModel.decision_function
+      ~BaseModel.loss
+      ~BaseModel.margin
+      ~BaseModel.phi
+      ~BaseModel.predict
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~BaseModel.parameters
+
+
diff --git a/...rence/models/generated/pyconstruct.models.LinearModel.decision_function.rst.txt b/...rence/models/generated/pyconstruct.models.LinearModel.decision_function.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.LinearModel.decision\_function
+=================================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: LinearModel.decision_function
diff --git a/..._sources/reference/models/generated/pyconstruct.models.LinearModel.loss.rst.txt b/..._sources/reference/models/generated/pyconstruct.models.LinearModel.loss.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.LinearModel.loss
+===================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: LinearModel.loss
diff --git a/...ources/reference/models/generated/pyconstruct.models.LinearModel.margin.rst.txt b/...ources/reference/models/generated/pyconstruct.models.LinearModel.margin.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.LinearModel.margin
+=====================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: LinearModel.margin
diff --git a/.../_sources/reference/models/generated/pyconstruct.models.LinearModel.phi.rst.txt b/.../_sources/reference/models/generated/pyconstruct.models.LinearModel.phi.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.LinearModel.phi
+==================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: LinearModel.phi
diff --git a/...urces/reference/models/generated/pyconstruct.models.LinearModel.predict.rst.txt b/...urces/reference/models/generated/pyconstruct.models.LinearModel.predict.rst.txt
@@ -0,0 +1,6 @@
+pyconstruct.models.LinearModel.predict
+======================================
+
+.. currentmodule:: pyconstruct.models
+
+.. automethod:: LinearModel.predict