Doc content

choicemodels/tools/__init__.py

@@ -1,5 +1,6 @@
 # ChoiceModels
 # See full license in LICENSE
 
+from .distancematrix import *
 from .mergedchoicetable import *
 from .simulation import *

docs/source/choice-table-utilities.rst

@@ -0,0 +1,29 @@
+Choice table utilities API
+==========================
+
+Working with discrete choice models can require a lot of data preparation. Each chooser has to be matched with hypothetical alternatives, either to simulate choice probabilities or to compare them with the chosen alternative for model estimation. 
+
+ChoiceModels includes a class called ``MergedChoiceTable`` that automates this. To build a merged table, create an instance of the class and pass it one ``pd.DataFrame`` of choosers and another of alternatives, with whatever other arguments are needed (see below for full API). 
+
+The merged data table can be output to a DataFrame, or passed directly to other ChoiceModels tools as a ``MergedChoiceTable`` object. (This retains metadata about indexes and other special columns.)
+
+.. code-block:: python
+   
+   mct = choicemodels.tools.MergedChoiceTable(obs, alts, ..)
+   df = mct.to_frame()
+
+This tool is designed especially for models that need to sample from large numbers of alternatives. It supports:
+
+- uniform random sampling of alternatives, with or without replacement
+- weighted random sampling based either on characteristics of the alternatives or on combinations of chooser and alternative
+- interaction terms to be merged onto the final data table
+- cartesian merging of all the choosers with all the alternatives, without sampling
+
+All of the sampling procedures work for both estimation (where the chosen alternative is known) and simulation (where it is not).
+
+
+MergedChoiceTable
+-----------------
+
+.. autoclass:: choicemodels.tools.MergedChoiceTable
+   :members:

docs/source/conf.py

@@ -23,6 +23,8 @@
 # go up two levels from /docs/source to the package root
 sys.path.insert(0, os.path.abspath('../..'))
 
+import sphinx_rtd_theme
+
 
 # -- General configuration ------------------------------------------------
 
@@ -36,7 +38,8 @@
 extensions = ['sphinx.ext.autodoc',
              #'sphinx.ext.napoleon',
               'sphinx.ext.viewcode',
-              'sphinx.ext.githubpages']
+              'sphinx.ext.githubpages',
+              'numpydoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -52,7 +55,7 @@
 
 # General information about the project.
 project = 'ChoiceModels'
-copyright = '2018, Urban Data Science Toolkit'
+copyright = '2019, Urban Data Science Toolkit'
 author = 'Urban Data Science Toolkit'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -90,7 +93,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -103,21 +106,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    '**': [
-        'about.html',
-        'navigation.html',
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-        'donate.html',
-    ]
-}
-
 
 # -- Options for HTMLHelp output ------------------------------------------
 

docs/source/distance-utilities.rst

@@ -0,0 +1,20 @@
+Distance utilities API
+======================
+
+ChoiceModels also includes tools for constructing pairwise distance matrices and calculating which geographies are within various distance bands of some reference geography.
+
+
+Distance matrices
+-----------------
+
+.. autofunction:: choicemodels.tools.great_circle_distance_matrix
+
+.. autofunction:: choicemodels.tools.euclidean_distance_matrix
+
+.. autofunction:: choicemodels.tools.distance_matrix
+
+
+Distance bands
+--------------
+
+.. autofunction:: choicemodels.tools.distance_bands

docs/source/getting-started.rst

@@ -0,0 +1,21 @@
+Getting started
+===============
+
+Intro
+-----
+
+ChoiceModels is a Python library for discrete choice model estimation, with utilities for sampling, simulation, and other ancillary tasks. It's part of the `Urban Data Science Toolkit <https://github.com/udst>`__ (UDST).
+
+MORE TK
+
+
+Installation
+------------
+
+TK
+
+
+Basic usage
+-----------
+
+TK

docs/source/index.rst

@@ -3,19 +3,22 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ChoiceModels's documentation!
-========================================
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+ChoiceModels
+============
 
+ChoiceModels is a Python library for discrete choice model estimation, with utilities for sampling, simulation, and other ancillary tasks. It's part of the `Urban Data Science Toolkit <https://github.com/udst>`__ (UDST).
 
+v0.2.dev9, released January 2019
 
 
-Indices and tables
-==================
+Contents
+--------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 2
+
+   getting-started
+   choice-table-utilities
+   multinomial-logit
+   simulation-utilities
+   distance-utilities

docs/source/multinomial-logit.rst

@@ -0,0 +1,20 @@
+Multinomial Logit API
+=====================
+
+ChoiceModels has built-in functionality for Multinomial Logit estimation and simulation. This can use either the `PyLogit <https://github.com/timothyb0912/pylogit>`__ MNL estimation engine or a custom engine optimized for fast performance with large numbers of alternatives. The custom engine is originally from ``urbansim.urbanchoice``.
+
+Fitting a model yields a results object that can generate choice probabilities for out-of-sample scenarios.
+
+
+MultinomialLogit
+----------------
+
+.. autoclass:: choicemodels.MultinomialLogit
+   :members:
+
+
+MultinomialLogitResults
+-----------------------
+
+.. autoclass:: choicemodels.MultinomialLogitResults
+   :members:

docs/source/simulation-utilities.rst

@@ -0,0 +1,20 @@
+Simulation utilities API
+========================
+
+ChoiceModels provides general-purpose tools for Monte Carlo simulation of choices among alternatives, given probability distributions generated from fitted models. 
+
+``monte_carlo_choices()`` is equivalent to applying ``np.random.choice()`` in parallel for many independent choice scenarios, but it's implemented as a single-pass matrix calculation that is much faster.
+
+``iterative_lottery_choices()`` is for cases where the alternatives have limited capacity, requiring multiple passes to match choosers and alternatives. Effectively, choices are simulated sequentially, each time removing the chosen alternative or reducing its available capacity. (It's actually done in batches for better performance.)
+
+
+Independent choices
+-------------------
+
+.. autofunction:: choicemodels.tools.monte_carlo_choices
+
+
+Capacity-constrained choices
+----------------------------
+
+.. autofunction:: choicemodels.tools.iterative_lottery_choices

requirements-dev.txt

@@ -1,4 +1,7 @@
 coverage >= 4.5
 coveralls >= 1.3
 pytest >= 3.4
-urbansim >= 3.1
+urbansim >= 3.1
+sphinx
+numpydoc
+sphinx_rtd_theme