DOC: Shorten blurb in index.rst and move the rest to intro.rst

docs/api.rst

@@ -1,4 +1,4 @@
-PyBroom API Documentation
+Pybroom API Documentation
 =========================
 
 .. automodule :: pybroom

docs/index.rst

@@ -8,52 +8,19 @@ Welcome to pybroom's documentation!
 
 :Latest Version: |version|
 
-**Pybroom** is a small python 3 library for converting fitting results
-(curve fitting or other optimizations)
+**Pybroom** is a small python 3+ library for converting collections of
+fit results (curve fitting or other optimizations)
 to `Pandas <http://pandas.pydata.org/>`__
 `DataFrame <http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe>`__
-in tidy format
+in tidy format (or long-form)
 `(Wickham 2014) <http://dx.doi.org/10.18637/jss.v059.i10>`__.
-DataFrames in tidy format (or long-form) follow a simple rule:
-one "observation" per row and one "variable" per column.
-This simple structure makes it easy to process the data with clear and
-`well-understood idioms <http://tomaugspurger.github.io/modern-5-tidy.html>`__
-(for filtering, aggregation, etc.) and allows
-plot libraries to automatically generate complex plots in which many
-variables are compared. Plotting libraries supporting tidy DataFrames
-include `seaborn <https://web.stanford.edu/~mwaskom/software/seaborn/>`__,
-recent versions of `matplotlib <http://matplotlib.org/>`__,
-`bokeh <http://bokeh.pydata.org/>`__ and
-`altair <https://github.com/ellisonbg/altair>`__.
-pybroom development was inspired by the R library
-`broom <https://github.com/dgrtwo/broom>`__.
-See `this video <https://www.youtube.com/watch?v=eM3Ha0kTAz4>`__
-for details of the philosophy behind broom and pybroom.
+Once fit results are in tidy DataFrames, it is possible to leverage
+`common patterns <http://tomaugspurger.github.io/modern-5-tidy.html>`__
+for tidy data analysis. Furthermore powerful visual
+explorations using multi-facet plots becomes easy thanks to libraries
+like `seaborn <https://pypi.python.org/pypi/seaborn/>`__ natively
+supporting tidy DataFrames.
 
-Like the R library broom, pybroom provides 3 functions: `glance`, `tidy` and
-`augment`. The `glance` function returns fit statistics, one for each
-fit result (e.g. fit method, number of iterations, chi-square etc.).
-The `tidy` function returns data for each fitted parameter
-(e.g. fitted value, gradient, bounds, etc.).
-The `augment` function returns data with the same size as the fitted
-data points (evaluated best-fit model, residuals, etc.).
-Additionally, pybroom has two functions `tidy_to_dict` and `dict_to_tidy`
-for conversion between dictionaries and 2-columns tidy DataFrames.
-
-Currently, supported fit result object are:
-
-- `scipy.optimize.OptimizeResult`
-- `lmfit.model.ModelResult` (returned by `lmfit.Model.fit()`)
-- `lmfit.minimizer.MinimizerResult` (returned by `lmfit.minimizer()`)
-
-Note that the 3 functions (glance, tidy and augment) are implemented only for
-the fit-result objects that are relevant. For example, `augment` cannot
-process lmfit's `MinimizerResult` or scipy's `OptimizeResult` because
-there is little or no data relevant to each data point.
-
-Support for result objects from other libraries such as
-`sklearn` can be added based on user request
-(`PR welcome! <https://github.com/tritemio/pybroom>`__).
 
 Installation
 ------------
@@ -66,23 +33,23 @@ Dependencies are only pandas and lmfit (0.9.5+, which in turn requires scipy).
 However, matplotlib and seaborn are strongly recommended (and necessary
 to run the example notebooks).
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Documentation
+
+    intro
+    whatsnew
+    api
 
 .. toctree::
    :maxdepth: 1
-   :caption: Example Notebooks
+   :caption: Notebook Tutorials
 
    notebooks/pybroom-example.ipynb
    notebooks/pybroom-example-multi-datasets.ipynb
    notebooks/pybroom-example-multi-datasets-minimize.ipynb
    notebooks/pybroom-example-multi-datasets-scipy-robust-fit.ipynb
 
-.. toctree::
-    :maxdepth: 1
-    :caption: Reference
-
-    whatsnew
-    api
-
 
 Indices and tables
 ==================

docs/intro.rst

@@ -0,0 +1,64 @@
+Why Pybroom?
+============
+
+Which problem we are trying to solve?
+------------------------------------
+
+DataFrames in tidy format (or long-form) follow a simple rule:
+one "observation" per row and one "variable" per column.
+This simple structure makes it easy to process the data with clear and
+`well-understood idioms <http://tomaugspurger.github.io/modern-5-tidy.html>`__
+(filtering, aggregation, etc.) and allows
+plot libraries to automatically generate complex plots in which many
+variables are compared. Plotting libraries supporting tidy DataFrames
+include `seaborn <https://web.stanford.edu/~mwaskom/software/seaborn/>`__,
+recent versions of `matplotlib <http://matplotlib.org/>`__,
+`bokeh <http://bokeh.pydata.org/>`__ and
+`altair <https://github.com/ellisonbg/altair>`__.
+
+But, while data is oftentimes represented in tidy DataFrames, fit results
+are usually stored in a variety of custom objects and are harder
+to manipulate, compare and plot.
+
+Pybroom to the rescue!
+----------------------
+
+Pybroom allows to convert several types of fit results to tidy
+DataFrames, and is particularly useful for handling collections
+of such fit results.
+Pybroom development was inspired by the R library
+`broom <https://github.com/dgrtwo/broom>`__.
+You can watch `this video <https://www.youtube.com/watch?v=eM3Ha0kTAz4>`__
+for details of the philosophy behind broom (and by extension pybroom).
+
+Like the R library broom, pybroom provides 3 functions: `glance`, `tidy` and
+`augment`. The `glance` function returns fit statistics, one for each
+fit result (e.g. fit method, number of iterations, chi-square etc.).
+The `tidy` function returns data for each fitted parameter
+(e.g. fitted value, gradient, bounds, etc.).
+The `augment` function returns data with the same size as the fitted
+data points (evaluated best-fit model, residuals, etc.).
+Additionally, pybroom has two functions `tidy_to_dict` and `dict_to_tidy`
+for conversion between dictionaries and 2-columns tidy DataFrames.
+
+Collections of fit results can be in `list`, `dict`,
+or any nested `dict`/`list` combination.
+When a collection of fit result is used as input, pybroom functions
+return a DataFrame with additional "categorical" column(s) containing
+the dict keys or the list index.
+
+Currently, supported fit result object are:
+
+- `scipy.optimize.OptimizeResult` returned by several functions in
+  `scipy.optimize`;
+- `lmfit.model.ModelResult` (returned by `lmfit.Model.fit()`);
+- `lmfit.minimizer.MinimizerResult` (returned by `lmfit.minimizer()`).
+
+Note that the 3 functions (glance, tidy and augment) are implemented only for
+the fit-result objects that are relevant. For example, `augment` cannot
+process lmfit's `MinimizerResult` or scipy's `OptimizeResult` because
+there is little or no data relevant to each data point.
+
+Support for result objects from other libraries such as
+`sklearn` can be added based on user request
+(`PR welcome! <https://github.com/tritemio/pybroom>`__).

setup.py

@@ -15,26 +15,18 @@ def get_version():
 pybroom
 =======
 
-**Pybroom** is a small python 3 library for converting fitting results
-(curve fitting or other optimizations)
+**Pybroom** is a small python 3+ library for converting collections of
+fit results (curve fitting or other optimizations)
 to `Pandas <http://pandas.pydata.org/>`__
 `DataFrame <http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe>`__
-in tidy format
+in tidy format (or long-form)
 `(Wickham 2014) <http://dx.doi.org/10.18637/jss.v059.i10>`__.
-The DataFrames in tidy format (or long-form) follow a simple rule:
-one "observation" per row and one "variable" per column.
-This simple structure makes it easy to process the data with clear and
-well-understood idioms (for filtering, aggregation, etc.) and allows
-plot libraries to automatically generate complex plots in which many
-variables are compared. Plotting libraries supporting tidy DataFrames
-include `seaborn <https://web.stanford.edu/~mwaskom/software/seaborn/>`__,
-recent versions of `matplotlib <http://matplotlib.org/>`__,
-`bokeh <http://bokeh.pydata.org/>`__ and
-`altair <https://github.com/ellisonbg/altair>`__.
-pybroom development was inspired by the R library
-`broom <https://github.com/dgrtwo/broom>`__.
-See `this video <https://www.youtube.com/watch?v=eM3Ha0kTAz4>`__
-for details of the philosophy behind broom and pybroom.
+Once fit results are in tidy DataFrames, it is possible to leverage
+`common patterns <http://tomaugspurger.github.io/modern-5-tidy.html>`__
+for tidy data analysis. Furthermore powerful visual
+explorations using multi-facet plots becomes easy thanks to libraries
+like `seaborn <https://pypi.python.org/pypi/seaborn/>`__ natively
+supporting tidy DataFrames.
 
 See the `pybroom homepage <http://pybroom.readthedocs.io/>`__ for more info.
 """