[0.2.dev9] Small fixes and doc improvements

CHANGELOG.md

@@ -0,0 +1,63 @@
+# ChoiceModels change log
+
+### 0.2.dev9 (2019-01-22)
+
+- improves documentation and packaging
+
+### 0.2.dev8 (2019-01-21)
+
+- prevents an infinite loop in `interative_lottery_choices()` when none of the remaining alternatives can accommodate any of the remaining choosers
+
+### 0.2.dev7 (2018-12-12)
+
+- adds a check to the `MergedChoiceTable` constructor to make sure there aren't any column names that overlap between the observations and alternatives tables
+
+### 0.2.dev6 (2018-11-23)
+
+- resolves deprecation warnings from older code
+
+- removes `choicemodels.tools.mnl_simulate()` (originally from `urbansim.urbanchoice.mnl`), because this functionality has been fully replaced
+
+- removes `choicemodels.Logit`, which wrapped a StatsModels estimator as proof of concept for MNL and didn't provide much value on its own
+
+### 0.2.dev5 (2018-11-12)
+
+- adds a `chooser_batch_size` parameter to `iterative_lottery_choices()`, to support batch simulation for very large datasets
+
+### 0.2.dev4 (2018-10-15)
+
+- adds a function `choicemodels.tools.iterative_lottery_choices()` for simulation of choices where the alternatives have limited capacity and choosers have varying probability distributions over the alternatives
+
+- in `MergedChoiceTable`, empty choosers or alternatives now produces an empty choice table (rather than an exception)
+
+- adds support for multiple tables of interaction terms in `MergedChoiceTable`
+
+### 0.2.dev3 (2018-10-03)
+
+- adds a function `choicemodels.tools.monte_carlo_choices()` for efficient simulation of choices for a list of scenarios that have differing probability distributions, but no capacity constraints on the alternatives
+
+### 0.2.dev2 (2018-09-12)
+
+- adds a `probabilities()` method to the `MultinomialLogitResults` class, which uses the fitted model coefficients to generate predicted probabilities for a table of choice scenarios
+
+- adds a required `model_experssion` parameter to the `MultinomialLogitResults` constructor
+
+### 0.2.dev1 (2018-08-06)
+
+- improves the reliability of the native MNL estimator: (a) reduces the chance of a memory overflow when exponentiating utilities and (b) reports warnings from SciPy if the likelihood maximization algorithm may not have converged correctly
+
+- adds substantial functionality to the `MergedChoiceTable` utility: sampling of alternatives with or without replacement, alternative-specific weights, interaction weights that apply to combinations of choosers and alternatives, automatic joining of interaction terms onto the merged table, non-sampling (all the alternatives available for each chooser), and estimation/simulation support for all combinations
+
+- `LargeMultinomialLogit` class now optionally accepts a `MergedChoiceTable` as input
+
+### 0.2.dev0 (2018-07-09)
+
+- adds additional information to the summary table for the native MNL estimator: number of observations, df of the model, df of the residuals, rho-squared, rho-bar-squared, BIC, AIC, p values, timestamp
+
+### 0.1.1 (2018-03-08)
+
+- packaging improvements
+
+### 0.1 (2018-03-08)
+
+- initial release

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+Thanks for using ChoiceModels! This is an open source project that's part of the Urban Data Science Toolkit. Development and maintenance is a collaboration between UrbanSim Inc and U.C. Berkeley's Urban Analytics Lab. You can contact Sam Maurer, the lead developer, at `[email protected]`.
+
+### If you encounter an error or find a bug:
+
+- Take a look at the [open issues](https://github.com/UDST/choicemodels/issues) and [closed issues](https://github.com/UDST/choicemodels/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a discussion of the problem
+
+- Open a new issue describing the problem: circumstances, error messages, operating system you are using, version of python, and version of any libraries that may be relevant
+
+### If you have a feature proposal:
+
+- Take a look at the [open issues](https://github.com/UDST/choicemodels/issues) and [closed issues](https://github.com/UDST/choicemodels/issues?q=is%3Aissue+is%3Aclosed) to see if there's already a discussion of the topic
+
+- Post your proposal as a new issue, so we can discuss it (some proposals may not be a good fit for the project)
+
+### Adding a feature or fixing a bug:
+
+- Create a new branch of UDST/choicemodels, or fork the repository to your own account
+
+- Make your changes, adhering to the existing styles for coding, commenting, and especially the documentation strings at the beginning of functions
+
+- Add [tests](https://github.com/UDST/choicemodels/tree/master/tests) if possible
+
+- When you're ready to begin code review, open a pull request to the UDST/choicemodels master branch
+
+- The pull request writeup should be clear and thorough, to facilitate code review, documentation, and release notes (see [example here](https://github.com/UDST/choicemodels/pull/43)). First, briefly summarize the changes, referencing any associated issue threads. Then describe the changes in more detail: implementation, usage, performance, and anything else that's relevant
+
+- Make note in the pull request writeup of any API changes (class/method/function names, parameters, and behavior), particularly changes that could affect users' existing code
+
+- Each substantial pull request should increment the development version number, e.g. from 0.2.dev7 to 0.2.dev8
+
+- If incrementing the version number: (1) update `setup.py`, (2) update `choicemodels/__init__.py`, (3) add a section to `CHANGELOG.md`, and (4) add the version number to the beginning of the pull request name
+
+### Preparing a production release:
+
+- Create a branch for release prep
+
+- Make sure all the tests are passing
+
+- Update the version number (e.g. from 0.2.dev8 to 0.2) in `setup.py` and `choicemodels/__init__.py`
+
+- Update `CHANGELOG.md`, collapsing development release sections into a single, reorganized list
+
+- Check if updates are needed to `README.md` and to the documentation source files
+
+- Rebuild the documentation webpages (DETAILS TK)
+
+- Open a pull request to the master branch
+
+- Merge the pull request
+
+- Tag the release on Github
+
+- Update the Python Package Index (DETAILS TK)
+
+- Update the UDST Conda channel (DETAILS TK)

README.md

@@ -17,13 +17,37 @@ Package documentation is available on [readthedocs](https://choicemodels.readthe
 
 ## Installation
 
-Install with pip:
+### Production releases
 
-`pip install choicemodels`
+Production releases of ChoiceModels can be installed with pip or conda:
 
-or with conda-forge.
+```
+pip install choicemodels
+```
 
+```
+conda install --channel conda-forge choicemodels
+```
 
+### Development releases
+
+The latest development release can be installed using the Github URL. You may want to remove prior installations first to avoid version conflicts.
+
+```
+pip list
+pip uninstall choicemodels
+pip install git+git://github.com/udst/choicemodels.git
+```
+
+### Cloning the repository
+
+If you will be editing ChoiceModels code or frequently updating to newer development versions, you can clone the repository and link it to your Python environment:
+
+```
+git clone https://github.com/udst/choicemodels.git
+cd choicemodels
+python setup.py develop
+```
 
 ## Current functionality
 

choicemodels/__init__.py

@@ -3,4 +3,4 @@
 
 from .mnl import MultinomialLogit, MultinomialLogitResults
 
-version = __version__ = '0.2.dev8'
+version = __version__ = '0.2.dev9'

choicemodels/tools/mergedchoicetable.py

@@ -133,15 +133,11 @@ def __init__(self, observations, alternatives, chosen_alternatives=None,
         # Check for duplicate column names
         obs_cols = list(observations.columns) + list(observations.index.names)
         alt_cols = list(alternatives.columns) + list(alternatives.index.names)
-        dupes = [c for c in obs_cols if c in alt_cols]
-
-        if len(dupes) == 1:
-            raise ValueError("Column '{}' appears in both input tables. Please ensure "
-                             "column names are unique before merging".format(dupes[0]))
-        elif len(dupes) > 1:
-            raise ValueError("Columns '{}' appear in both input tables. Please ensure "
-                             "column names are unique before merging"\
-                             .format("', '".join(dupes)))
+        dupes = set(obs_cols) & set(alt_cols)
+
+        if len(dupes) > 0:
+            raise ValueError("Both input tables contain column {}. Please ensure "
+                             "column names are unique before merging".format(dupes))
 
         # Normalize weights to a pd.Series
         if (weights is not None) & isinstance(weights, str):