add example for new random seed spec

cjekel · May 1, 2022 · 050c693 · 050c693
1 parent 09d7058
commit 050c693
Show file tree

Hide file tree

Showing 9 changed files with 72 additions and 2 deletions.
diff --git a/docs/_sources/examples.rst.txt b/docs/_sources/examples.rst.txt
@@ -79,6 +79,7 @@ All of these examples will use the following data and imports.
 16. `obtain the equations of fitted
     pwlf <#obtain-the-equations-of-fitted-pwlf>`__
 17. `weighted least squares fit <#weighted-least-squares-fit>`__
+18. `reproducible results <#reproducible results>`__
 
 fit with known breakpoint locations
 -----------------------------------
@@ -840,3 +841,20 @@ and a weighted fit.
 We can see that the weighted pwlf fit tries fit data with low variance
 better than data with high variance, however the ordinary pwlf fits the
 data assuming a uniform variance.
+
+reproducible results
+--------------------
+
+The `fit` and `fitfast` methods are stochastic and may not give the same
+result every time the program is run. To have reproducible results you can
+manually specify a numpy.random.seed on init. Now everytime the following
+program is run, the results of the fit(2) should be the same.
+
+.. code:: python
+
+   # initialize piecewise linear fit with a random seed
+   my_pwlf = pwlf.PiecewiseLinFit(x, y, seed=123)
+
+   # Now the fit() method will be reproducible
+   my_pwlf.fit(2)
+
diff --git a/docs/examples.html b/docs/examples.html
@@ -114,6 +114,7 @@ <h1>Examples<a class="headerlink" href="#examples" title="Permalink to this head
 <li><p><a class="reference external" href="#obtain-the-equations-of-fitted-pwlf">obtain the equations of fitted
 pwlf</a></p></li>
 <li><p><a class="reference external" href="#weighted-least-squares-fit">weighted least squares fit</a></p></li>
+<li><p><a class="reference external" href="#reproducibleresults">reproducible results</a></p></li>
 </ol>
 <section id="fit-with-known-breakpoint-locations">
 <h2>fit with known breakpoint locations<a class="headerlink" href="#fit-with-known-breakpoint-locations" title="Permalink to this headline">¶</a></h2>
@@ -887,6 +888,20 @@ <h2>weighted least squares fit<a class="headerlink" href="#weighted-least-square
 better than data with high variance, however the ordinary pwlf fits the
 data assuming a uniform variance.</p>
 </section>
+<section id="reproducible-results">
+<h2>reproducible results<a class="headerlink" href="#reproducible-results" title="Permalink to this headline">¶</a></h2>
+<p>The <cite>fit</cite> and <cite>fitfast</cite> methods are stochastic and may not give the same
+result every time the program is run. To have reproducible results you can
+manually specify a numpy.random.seed on init. Now everytime the following
+program is run, the results of the fit(2) should be the same.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># initialize piecewise linear fit with a random seed</span>
+<span class="n">my_pwlf</span> <span class="o">=</span> <span class="n">pwlf</span><span class="o">.</span><span class="n">PiecewiseLinFit</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">seed</span><span class="o">=</span><span class="mi">123</span><span class="p">)</span>
+
+<span class="c1"># Now the fit() method will be reproducible</span>
+<span class="n">my_pwlf</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
+</pre></div>
+</div>
+</section>
 </section>
 
 
@@ -927,6 +942,7 @@ <h3>Navigation</h3>
 <li class="toctree-l2"><a class="reference internal" href="#non-linear-standard-errors-and-p-values">non-linear standard errors and p-values</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#obtain-the-equations-of-fitted-pwlf">obtain the equations of fitted pwlf</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#weighted-least-squares-fit">weighted least squares fit</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#reproducible-results">reproducible results</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="pwlf.html">pwlf package contents</a></li>

diff --git a/docs/index.html b/docs/index.html
@@ -64,6 +64,7 @@ <h1>pwlf: piecewise linear fitting<a class="headerlink" href="#pwlf-piecewise-li
 <li class="toctree-l2"><a class="reference internal" href="examples.html#non-linear-standard-errors-and-p-values">non-linear standard errors and p-values</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#obtain-the-equations-of-fitted-pwlf">obtain the equations of fitted pwlf</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#weighted-least-squares-fit">weighted least squares fit</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#reproducible-results">reproducible results</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="pwlf.html">pwlf package contents</a><ul>

diff --git a/docs/searchindex.js b/docs/searchindex.js
diff --git a/doctrees/environment.pickle b/doctrees/environment.pickle
diff --git a/doctrees/examples.doctree b/doctrees/examples.doctree
diff --git a/examples/README.md b/examples/README.md
@@ -65,6 +65,7 @@ x = np.array([0.00000000e+00, 8.82678000e-03, 3.25615100e-02,
 15. [non-linear standard errors and p-values](#non-linear-standard-errors-and-p-values)
 16. [obtain the equations of fitted pwlf](#obtain-the-equations-of-fitted-pwlf)
 17. [weighted least squares fit](#weighted-least-squares-fit)
+18. [reproducible results](#reproducible-resultss)
 
 
 ## fit with known breakpoint locations
@@ -714,3 +715,19 @@ plt.show()
 ![Weighted pwlf fit.](https://raw.githubusercontent.com/cjekel/piecewise_linear_fit_py/master/examples/weighted_least_squares_example.png)
 
 We can see that the weighted pwlf fit tries fit data with low variance better than data with high variance, however the ordinary pwlf fits the data assuming a uniform variance.
+
+## reproducible results
+
+The `fit` and `fitfast` methods are stochastic and may not give the same
+result every time the program is run. To have reproducible results you can
+manually specify a numpy.random.seed on init. Now everytime the following
+program is run, the results of the fit(2) should be the same.
+
+```python
+
+# initialize piecewise linear fit with a random seed
+my_pwlf = pwlf.PiecewiseLinFit(x, y, seed=123)
+
+# Now the fit() method will be reproducible
+my_pwlf.fit(2)
+```
diff --git a/examples/README.rst b/examples/README.rst
@@ -79,6 +79,7 @@ All of these examples will use the following data and imports.
 16. `obtain the equations of fitted
     pwlf <#obtain-the-equations-of-fitted-pwlf>`__
 17. `weighted least squares fit <#weighted-least-squares-fit>`__
+18. `reproducible results <#reproducible results>`__
 
 fit with known breakpoint locations
 -----------------------------------
@@ -840,3 +841,20 @@ and a weighted fit.
 We can see that the weighted pwlf fit tries fit data with low variance
 better than data with high variance, however the ordinary pwlf fits the
 data assuming a uniform variance.
+
+reproducible results
+--------------------
+
+The `fit` and `fitfast` methods are stochastic and may not give the same
+result every time the program is run. To have reproducible results you can
+manually specify a numpy.random.seed on init. Now everytime the following
+program is run, the results of the fit(2) should be the same.
+
+.. code:: python
+
+   # initialize piecewise linear fit with a random seed
+   my_pwlf = pwlf.PiecewiseLinFit(x, y, seed=123)
+
+   # Now the fit() method will be reproducible
+   my_pwlf.fit(2)
+
diff --git a/sphinxdocs/source/examples.rst b/sphinxdocs/source/examples.rst
@@ -79,7 +79,7 @@ All of these examples will use the following data and imports.
 16. `obtain the equations of fitted
     pwlf <#obtain-the-equations-of-fitted-pwlf>`__
 17. `weighted least squares fit <#weighted-least-squares-fit>`__
-18. `reproducible results <#reproducible-results>`__
+18. `reproducible results <#reproducible results>`__
 
 fit with known breakpoint locations
 -----------------------------------