Release 1.0

.gitignore

@@ -24,6 +24,9 @@ var/
 .installed.cfg
 *.egg
 setup.cfg
+doc/_build
+doc/_static
+doc/_templates
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -90,4 +93,7 @@ ENV/
 .ropeproject
 
 # IDEA project settings
-.idea
+.idea
+
+# VSCode settings
+.vscode

README.md

@@ -1,12 +1,51 @@
-# balsa
-Collection of modelling utilities. Works with both Python 2.7 and Python 3.5+
+# Balsa
 
-The current documentation can be found [on the Wiki page](https://github.com/pbsag/balsa/wiki). Some components are under construction.
+Balsa is a collection of functions and tools for Python to facilitate travel demand 
+forecasting applications and analyses. It is designed to work the the “scientific 
+stack” of Python, namely NumPy, Pandas, and Matplotlib; which are optimized for speed
+and usability. Most of balsa consists of standalone functions - for input/output, for
+analysis, etc. - as well as a few lightweight class-based data structures for specific
+applications.
 
-## Contents:
+Balsa is published by the Systems Analytics for Policy group inside WSP Canada.
+
+## Key features
+
+ + I/O routines to convert from binary matrix formats (INRO, OMX, and more) to
+ Pandas DataFrames and Series.
+ + Matrix operations such as balancing, dis/aggregation, and bucket rounding.
+ + Plotting functions such a Trip Length Frequency Distributions
+ + Pretty Logging utilities for use in program applications
+ + Management of JSON configuration files, including comments.
+ + and more! 
+
+ Balsa is compatible with Python 2.7 and 3.5+
+
+## Installation
+
+As a private package, Balsa **is not hosted on PyPI or other services that do not
+permit private code**. Currently the best way to install Balsa is using `pip` to
+install directly from GitHub:
+
+`pip install git+https://github.com/wsp-sag/balsa.git`
+
+Git will prompt you to login to your account (also works with 2FA) before installing.
+This requires you to download and install a 
+[standalone Git client](https://git-scm.com/downloads) to communicate with GitHub.
+
+**Windows Users:** It is recommended to install Balsa from inside an activated Conda
+environment. Balsa uses several packages (NumPy, Pandas, etc.) that will otherwise 
+not install correctly from `pip` otherwise. For example:
+
+```
+C:\> conda activate base
+
+(base) C:\> pip install git+https://github.com/wsp-sag/balsa.git
+...
+``` 
+
+## Documentation
+
+HTML documentation is available upon request - until we can find a suitable hosting
+service. Just email peter.kucirek@wsp.com to request. 
 
-* __cheval__: High-performance engine for evaluating discrete-choice (logit) models over DataFrames where utilities can be specified as expressions. Works with multinomial or nested models. Also includes the LinkedDataFrame class, a subclass of Pandas DataFrame which can be linked to other data frames.
-* __matrices__: Matrix balancing, as well as I/O for binary matrices.
-* __pandas_utils__: Utilities (such as `fast_stack`, and `align_cateogires`) for the Pandas library
-* __configuration__: Parsing and validation of JSON-based configuration files
-* __scribe__: Convenient functions for logging model information during a run.

balsa/__init__.py

@@ -1,12 +1,3 @@
-import balsa.configuration
-import balsa.cheval
-import balsa.matrices
-import balsa.pandas_utils
-import balsa.utils
-
-from balsa.cheval import LinkedDataFrame, ChoiceModel, sample_from_weights
-from balsa.configuration import Config
-from balsa.matrices import *
-from balsa.logging import *
-from balsa.pandas_utils import fast_stack, fast_unstack
-from balsa.models import *
+from .routines import *
+from .logging import get_model_logger, init_root, log_to_file, ModelLogger
+from .configuration import Config, ConfigParseError, ConfigSpecificationError, ConfigTypeError