From 17fecbe30b9d91a455008f7772db9a2d1870fd3e Mon Sep 17 00:00:00 2001 From: addisonlynch Date: Wed, 22 May 2019 14:04:44 -0400 Subject: [PATCH] Refactor learn.py docstrings to numpydoc format --- fecon236/ml/learn.py | 111 ++++++++++++++++++++++++++----------------- 1 file changed, 68 insertions(+), 43 deletions(-) diff --git a/fecon236/ml/learn.py b/fecon236/ml/learn.py index 63a36ec..57c0b70 100644 --- a/fecon236/ml/learn.py +++ b/fecon236/ml/learn.py @@ -1,23 +1,34 @@ # Python Module for import Date : 2018-06-13 # vim: set fileencoding=utf-8 ff=unix tw=78 ai syn=python : per PEP 0263 -''' -_______________| learn.py :: Fundamentals from Machine Learning +"""Fundamentals from Machine Learning -- softmax() for cross-entropy, MLE, neural networks, Boltzmann portfolio. -- softmax_sort() for ordering and filtering info on the probabilities. +- `softmax` for cross-entropy, MLE, neural networks, Boltzmann portfolio. +- `softmax_sort` for ordering and filtering info on the probabilities. -USAGE: tests/test_learn.py contains numerical examples. +Usage +----- +`tests/test_learn.py` contains numerical examples. + +Notes +----- +For LATEST version, see https://git.io/fecon236 + +References +---------- -REFERENCES - David J.C. MacKay (2008), Information theory, Inference, and Learning Algorithms, 7th printing from Cambridge U. Press. - Softmax, https://compute.quora.com/What-is-softmax?share=1 -CHANGE LOG For LATEST version, see https://git.io/fecon236 -2018-06-13 Spin-off doctests to tests/test_learn.py. -2018-06-12 learn.py, fecon236 fork. Fix imports, pass flake8, pass doctest. -2017-06-09 ys_mlearn.py, fecon235 v5.18.0312, https://git.io/fecon235 -''' +Change Log +---------- + +* 2018-06-13 Spin-off doctests to `tests/test_learn.py`. +* 2018-06-12 `learn.py`, `fecon236` fork. Fix imports, pass flake8, pass + doctest. +* 2017-06-09 `ys_mlearn.py`, fecon235 v5.18.0312, https://git.io/fecon235 + +""" from __future__ import absolute_import, print_function, division @@ -28,15 +39,46 @@ def softmax(it, temp=55, n=4): - '''Softmax probabilities for iterable where temp sets temperature tau. - Temperature tau is set as a temp percent of ensemble mean so that - the scaling of tau works well across many different scenarios. - Experiment with temp around 40 to 70; higher temp (100+) - will make it-scores more equi-probable, whereas probabilities - can be sharpened by decreasing temp towards 1. - Setting temp to 0 results in generic softmax without temperature. - Results are rounded to n decimal places. - ''' + """Softmax probabilities for iterable where temp sets temperature tau. + + Temperature tau is set as a `temp` percent of ensemble mean so that + the scaling of tau works well across many different scenarios. + Experiment with `temp` around 40 to 70; higher `temp` (100+) + will make it-scores more equi-probable, whereas probabilities + can be sharpened by decreasing `temp` towards 1. + Setting `temp` to `0` results in generic softmax without temperature. + Results are rounded to `n` decimal places. + + Notes + ----- + `softmax_sort` is obviously slower to compute than `softmax`. + They serve different purposes, for example, + `softmax()[-1][i]` can track a particular i-th class of it, whereas + `softmax_sort()[:3]` will give information on the top 3 classes. + + The TEMPERATURE is a proxy for the degree of uncertainty + in the relative estimation of it-scores, but can also serve + to diffuse errors, i.e. a diversification technique with + mathematical reasoning rooted in statistical mechanics, + information theory, and maximum likelihood statistics. + To test temperature variations, `softmax` will be much faster. + + Usage + ----- + + .. code-block:: python + + from fecon236.ml.learn import softmax_sort + + softmax_sort([-16, -8, 0, 4, 8, 16], temp=50, drop=0.05, renorm=False) + # [(0.5733, 5, 16.0), (0.2019, 4, 8.0), (0.1198, 3, 4.0), (0.0711, 2, + # 0.0)] + + softmax_sort([-16, -8, 0, 4, 8, 16], temp=50, drop=0.05, renorm=True) + # [(0.5934, 5, 16.0), (0.209, 4, 8.0), (0.124, 3, 4.0), (0.0736, 2, + # 0.0)] + + """ # Convert iterable to numpy array, then find index of its maximum value: arr = tool.toar(it) idmax = np.argmax(arr) @@ -71,31 +113,14 @@ def softmax(it, temp=55, n=4): hardprob = softmax_approx[idmax] return [idmax, hardmax, hardprob, temp, softmax_approx] - # __________ SOFTMAX USAGE NOTES - # softmax_sort() is obviously slower to compute than softmax(). - # They serve different purposes, for example, - # softmax()[-1][i] can track a particular i-th class of it, whereas - # softmax_sort()[:3] will give information on the top 3 classes. - # - # The TEMPERATURE is a proxy for the degree of uncertainty - # in the relative estimation of it-scores, but can also serve - # to diffuse errors, i.e. a diversification technique with - # mathematical reasoning rooted in statistical mechanics, - # information theory, and maximum likelihood statistics. - # To test temperature variations, softmax() will be much faster. - -# >>> softmax_sort([-16, -8, 0, 4, 8, 16], temp=50, drop=0.05, renorm=False) -# [(0.5733, 5, 16.0), (0.2019, 4, 8.0), (0.1198, 3, 4.0), (0.0711, 2, 0.0)] -# -# >>> softmax_sort([-16, -8, 0, 4, 8, 16], temp=50, drop=0.05, renorm=True) -# [(0.5934, 5, 16.0), (0.209, 4, 8.0), (0.124, 3, 4.0), (0.0736, 2, 0.0)] - def softmax_sort(it, temp=55, n=4, drop=0.00, renorm=False): - '''Softmax results sorted, include index; option to drop and renormalize. - Probabilities less than drop are ignored. - Setting renorm=True will make probabilities sum to 1. - ''' + """Softmax results sorted, include index; option to drop and renormalize. + + Probabilities less than drop are ignored. + + Setting `renorm=True` will make probabilities sum to 1. + """ arr = tool.toar(it) softmax_approx = softmax(arr, temp, n)[-1] # Tuples are formatted as (probability, index, it-value)