update documentation

gnu-octave · May 28, 2023 · 5c277ae · 5c277ae
2 parents c2dc45e + 06b8306
commit 5c277ae
Show file tree

Hide file tree

Showing 49 changed files with 1,178 additions and 132 deletions.
diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@ You can find its documentation at [https://gnu-octave.github.io/statistics/](htt
 
 ## 2. Install statistics
 
-To install the latest version (1.5.4) you need Octave (>=6.1.0) installed on your system. If you have Octave (>=7.2.0) you can install it by typing:
+To install the latest version (1.6.0) you need Octave (>=7.2.0) installed on your system. Install it by typing:
 
   `pkg install -forge statistics`
 
@@ -33,7 +33,7 @@ or alternatively type:
 
   `pkg install "https://github.com/gnu-octave/statistics/archive/refs/heads/main.zip"`
 
-to download and install it.
+to automatically download and install it.
 
 If you need to install a specific release, for example `1.4.2`, type:
 
@@ -42,9 +42,9 @@ If you need to install a specific release, for example `1.4.2`, type:
 After installation, type:
 - `pkg load statistics` to load the **statistics** package.
 - `news statistics` to review all the user visible changes since last version.
-- `pkg test statistics` to run a test suite for all[^1] functions in the package and ensure that they work properly on your system.
+- `pkg test statistics` to run a test suite for all 365 [^1] functions currently available and ensure that they work properly on your system.
 
-[^1]: Some functions are missing BISTs, these are not included in the test suite. But you are welcome to [contribute](https://github.com/gnu-octave/statistics/blob/main/CONTRIBUTING.md)!
+[^1]: Several functions are still missing from the statistics package, but you are welcome to [contribute](https://github.com/gnu-octave/statistics/blob/main/CONTRIBUTING.md)!
 
 ## 3. Provide feedback
 
@@ -62,5 +62,5 @@ If you find a bug and fix it, just [clone](https://github.com/gnu-octave/statist
 
 Make sure you follow the coding style already used in the **statistics** package (similar to GNU Octave). For a summary of the coding style rules used in the package see [Contribute](https://github.com/gnu-octave/statistics/blob/main/CONTRIBUTING.md).
 
-Contributing is not only about fixing bugs. Improving the texinfo of the functions help files or adding BISTs and demos at the end of the function files is also important. Out of a total of 315 functions, there are still 18 functions missing BISTs and it would be invaluable to add tests to these. Fixing a typo in the help file is still of value though. So don't hesitate to contribute! :+1:
+Contributing is not only about fixing bugs or implementing new functions. Improving the texinfo of the functions help files or adding BISTs and demos at the end of the function files is also important. Fixing a typo in the help file is still of value though. So don't hesitate to contribute! :+1:
 
diff --git a/docs/assets/dcov_101.png b/docs/assets/dcov_101.png
diff --git a/docs/assets/dendrogram_201.png b/docs/assets/dendrogram_201.png
diff --git a/docs/assets/fitgmdist_101.png b/docs/assets/fitgmdist_101.png
diff --git a/docs/assets/geofit_101.png b/docs/assets/geofit_101.png
diff --git a/docs/assets/gscatter_101.png b/docs/assets/gscatter_101.png
diff --git a/docs/assets/raylcdf_101.png b/docs/assets/raylcdf_101.png
diff --git a/docs/assets/silhouette_101.png b/docs/assets/silhouette_101.png
diff --git a/docs/assets/tcdf_101.png b/docs/assets/tcdf_101.png
diff --git a/docs/assets/tinv_101.png b/docs/assets/tinv_101.png
diff --git a/docs/assets/tpdf_101.png b/docs/assets/tpdf_101.png
diff --git a/docs/assets/unidcdf_101.png b/docs/assets/unidcdf_101.png
diff --git a/docs/assets/unidfit_101.png b/docs/assets/unidfit_101.png
diff --git a/docs/assets/unidinv_101.png b/docs/assets/unidinv_101.png
diff --git a/docs/assets/unidpdf_101.png b/docs/assets/unidpdf_101.png
diff --git a/docs/assets/unifcdf_101.png b/docs/assets/unifcdf_101.png
diff --git a/docs/assets/unifinv_101.png b/docs/assets/unifinv_101.png
diff --git a/docs/assets/unifit_101.png b/docs/assets/unifit_101.png
diff --git a/docs/assets/unifpdf_101.png b/docs/assets/unifpdf_101.png
diff --git a/docs/chi2gof.html b/docs/chi2gof.html
@@ -280,26 +280,26 @@ <h3 class="d-inline-block mr-2">
  [h, p, stats] = chi2gof (x, "binedges", binedges, "expected", expectedCounts)
 
 h = 0
-p = 0.4559
+p = 0.055361
 stats =
 
   scalar structure containing the fields:
 
-    chi2stat = 8.8000
+    chi2stat = 16.600
     df = 9
     edges =
 
-     Columns 1 through 9:
+     Columns 1 through 8:
 
-       0.029296   0.126158   0.223019   0.319880   0.416742   0.513603   0.610464   0.707325   0.804187
+       6.6704e-03   1.0438e-01   2.0209e-01   2.9980e-01   3.9751e-01   4.9521e-01   5.9292e-01   6.9063e-01
 
-     Columns 10 and 11:
+     Columns 9 through 11:
 
-       0.901048   0.997909
+       7.8834e-01   8.8605e-01   9.8376e-01
 
     O =
 
-       17    6    8   11   10    7   12    8   11   10
+        8   14    5   13    2   13   11    7   12   15
 
     E =
 

diff --git a/docs/geocdf.html b/docs/geocdf.html
@@ -98,6 +98,7 @@ <h3 class="d-inline-block mr-2">
   <a href="geoinv.html">geoinv</a>, 
   <a href="geopdf.html">geopdf</a>, 
   <a href="geornd.html">geornd</a>, 
+  <a href="geofit.html">geofit</a>, 
   <a href="geostat.html">geostat</a>
 </p>
 <p><strong>Source Code: </strong>

diff --git a/docs/geofit.html b/docs/geofit.html
@@ -0,0 +1,186 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Statistics: geofit</title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" integrity="sha512-1ycn6IcaQQ40/MKBW2W4Rhis/DbILU74C1vSrLJxCq57o941Ym01SwNsOMqvEBFlcgUa6xLiPY/NS5R+E6ztJQ==" crossorigin="anonymous" referrerpolicy="no-referrer">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/css/bootstrap.min.css" integrity="sha384-KyZXEAg3QhqLMpG8r+8fhAXLRk2vvoC2f3B09zVXn8CA5QIVfZOJ3BCsw2P0p/We" crossorigin="anonymous">
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-U1DAWAznBHeqEIlVSCgzq+c9gqGAJn5c/t99JyeKa9xxaYpSvHU5awsuZVVFIhvj" crossorigin="anonymous"></script>
+    <script type="text/javascript" async
+      src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_CHTML">
+    </script>
+    <style>
+    var {
+      font-style: italics;
+      font-weight: bold;
+    }
+    td {
+      vertical-align: top;
+    }
+    </style>
+  </head>
+  <body>
+    <div class="bg-dark">
+      <div class="container-xl">
+        <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
+          <div class="container-fluid">
+            <a class="navbar-brand" href=index.html>
+              <img src="assets/statistics.png" alt="statistics" class="d-inline-block align-top" width="25" height="25">
+              Statistics
+            </a>
+            <button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
+              <span class="navbar-toggler-icon"></span>
+            </button>
+            <div class="collapse navbar-collapse" id="navbarNav">
+              <ul class="navbar-nav">
+                <li class="nav-item">
+                  <a class="nav-link" href="index.html#Distribution Fitting">
+                    <i class="fas fa-list-alt"></i>
+                    Distribution Fitting
+                  </a>
+                </li>
+                <li class="nav-item">
+                  <a class="nav-link" href="https://gnu-octave.github.io/packages/">
+                  <img src="assets/octave-logo.svg" alt="GNU Octave logo" class="d-inline-block align-top" width="25" height="25">
+                    Octave Packages
+                  </a>
+                </li>
+                <li class="nav-item">
+                  <a class="nav-link" href="https://www.octave.org">
+                    <i class="fas fa-home"></i>
+                    GNU Octave website
+                  </a>
+                </li>
+              </ul>
+            </div>
+          </div>
+        </nav>
+      </div>
+    </div>
+    <div class="container-xl my-4">
+      <div class="card rounded">
+        <div class="card-header card-header-mod">
+          <div class="row d-flex flex-wrap align-items-center">
+            <div class="col-sm-3 col-md-5 mb-2 mb-sm-0">
+              <h3 class="d-inline-block mr-2">
+              Function&nbsp;Reference: <b><code>geofit</code></b>
+              </h3>
+            </div>
+          </div>
+        </div>
+        <div class="card-body">
+<dl>
+<dt><u>statistics:</u> <var>pshat</var> = <b>geofit</b><i> (<var>x</var>)</i></dt>
+<dt><u>statistics:</u> [<var>pshat</var>, <var>psci</var>] = <b>geofit</b><i> (<var>x</var>)</i></dt>
+<dt><u>statistics:</u> [<var>pshat</var>, <var>psci</var>] = <b>geofit</b><i> (<var>x</var>, <var>alpha</var>)</i></dt>
+<dt><u>statistics:</u> [<var>pshat</var>, <var>psci</var>] = <b>geofit</b><i> (<var>x</var>, <var>alpha</var>, <var>freq</var>)</i></dt>
+</dl>
+
+<p> Estimate parameter and confidence intervals for the geometric distribution.
+</p>
+<div class="ms-5">
+<p> <code><var>pshat</var> = geofit (<var>x</var>)</code> returns the maximum likelihood estimate
+ (MLE) of the probability of success for the geometric distribution.  <var>x</var>
+ must be a vector.
+</p>
+<p> <code>[<var>pshat</var>, <var>psci</var>] = geofit (<var>x</var>, <var>alpha</var>)</code> also returns
+ the <code>100 * (1 - <var>alpha</var>)</code> percent confidence intervals of the
+ estimated parameter.  By default, the optional argument <var>alpha</var> is 0.05
+ corresponding to 95% confidence intervals.  Pass in <code>[]</code> for
+ <var>alpha</var> to use the default values.
+</p>
+<p> <code>[&hellip;] = geofit (<var>x</var>, <var>alpha</var>, <var>freq</var>)</code> accepts a
+ frequency vector, <var>freq</var>, of the same size as <var>x</var>.  <var>freq</var>
+ typically contains integer frequencies for the corresponding elements in
+ <var>x</var>, but it can contain any non-integer non-negative values.  By default,
+ or if left empty, <code><var>freq</var> = ones (size (<var>x</var>))</code>.
+</p>
+<p> The geometric distribution models the number of failures (<var>x</var>) of a
+ Bernoulli trial with probability <var>ps</var> before the first success.
+</p>
+<p> Further information about the geometric distribution can be found at
+ <a href="https://en.wikipedia.org/wiki/Geometric_distribution">https://en.wikipedia.org/wiki/Geometric_distribution</a>
+</p>
+<p> <strong>See also: </strong>
+  <a href="geocdf.html">geocdf</a>, 
+  <a href="geoinv.html">geoinv</a>, 
+  <a href="geopdf.html">geopdf</a>, 
+  <a href="geornd.html">geornd</a>, 
+  <a href="geostat.html">geostat</a>
+</p>
+<p><strong>Source Code: </strong>
+  <a href="https://github.com/gnu-octave/statistics/tree/main/inst/dist_fit/geofit.m">geofit</a>
+</div>
+        <div class="container-xl my-4">
+          <div class="card rounded">
+            <div class="card-header card-header-mod">
+              <div class="row d-flex flex-wrap align-items-center">
+                <div class="col-sm-3 col-md-5 mb-2 mb-sm-0">
+                  <h3 class="d-inline-block mr-2">
+                  Example: 1
+                  </h3>
+                </div>
+              </div>
+            </div>
+            <div class="card-body">
+              <div class="container bg-light">
+                <div class="row">
+                  <table><tbody><tr>
+                    <td>&nbsp;</td>
+                    <td><pre class="example">
+
+ ## Sample 2 populations from different geometric distibutions
+ rande ("seed", 1);    # for reproducibility
+ r1 = geornd (0.15, 1000, 1);
+ rande ("seed", 2);    # for reproducibility
+ r2 = geornd (0.5, 1000, 1);
+ r = [r1, r2];
+
+ ## Plot them normalized and fix their colors
+ hist (r, 0:0.5:20.5, 1);
+ h = findobj (gca, "Type", "patch");
+ set (h(1), "facecolor", "c");
+ set (h(2), "facecolor", "g");
+ hold on
+
+ ## Estimate their probability of success
+ pshatA = geofit (r(:,1));
+ pshatB = geofit (r(:,2));
+
+ ## Plot their estimated PDFs
+ x = [0:15];
+ y = geopdf (x, pshatA);
+ plot (x, y, "-pg");
+ y = geopdf (x, pshatB);
+ plot (x, y, "-sc");
+ xlim ([0, 15])
+ ylim ([0, 0.6])
+ legend ({"Normalized HIST of sample 1 with ps=0.15", ...
+          "Normalized HIST of sample 2 with ps=0.50", ...
+          sprintf("PDF for sample 1 with estimated ps=%0.2f", ...
+                  mean (pshatA)), ...
+          sprintf("PDF for sample 2 with estimated ps=%0.2f", ...
+                  mean (pshatB))})
+ title ("Two population samples from different geometric distibutions")
+ hold off
+
+                    </pre></td></tr></tbody>
+                  </table>
+                  <div class="text-center">
+                    <img src="assets/geofit_101.png" class="rounded img-thumbnail" alt="plotted figure">
+                  </div><p></p>
+
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+
+        </div>
+      </div>
+    </div>
+
+  </body>
+</html>
diff --git a/docs/geoinv.html b/docs/geoinv.html
@@ -92,6 +92,7 @@ <h3 class="d-inline-block mr-2">
   <a href="geocdf.html">geocdf</a>, 
   <a href="geopdf.html">geopdf</a>, 
   <a href="geornd.html">geornd</a>, 
+  <a href="geofit.html">geofit</a>, 
   <a href="geostat.html">geostat</a>
 </p>
 <p><strong>Source Code: </strong>

diff --git a/docs/geopdf.html b/docs/geopdf.html
@@ -92,6 +92,7 @@ <h3 class="d-inline-block mr-2">
   <a href="geocdf.html">geocdf</a>, 
   <a href="geoinv.html">geoinv</a>, 
   <a href="geornd.html">geornd</a>, 
+  <a href="geofit.html">geofit</a>, 
   <a href="geostat.html">geostat</a>
 </p>
 <p><strong>Source Code: </strong>

diff --git a/docs/geornd.html b/docs/geornd.html
@@ -100,6 +100,7 @@ <h3 class="d-inline-block mr-2">
   <a href="geocdf.html">geocdf</a>, 
   <a href="geoinv.html">geoinv</a>, 
   <a href="geopdf.html">geopdf</a>, 
+  <a href="geofit.html">geofit</a>, 
   <a href="geostat.html">geostat</a>
 </p>
 <p><strong>Source Code: </strong>

diff --git a/docs/index.html b/docs/index.html
@@ -1726,31 +1726,32 @@ <h3 class="category">
                    <a href="unifcdf.html">unifcdf</a>
                    </code></b>
                  </td>
-                 <td>Uniform cumulative distribution function (CDF).</td>
+                 <td>Continuous uniform cumulative distribution function (CDF).</td>
                </tr>
                <tr>
                  <td>
                    <b><code>
                    <a href="unifinv.html">unifinv</a>
                    </code></b>
                  </td>
-                 <td>Inverse of the uniform cumulative distribution function (iCDF).</td>
+                 <td>Inverse of the continuous uniform cumulative distribution function
+(iCDF).</td>
                </tr>
                <tr>
                  <td>
                    <b><code>
                    <a href="unifpdf.html">unifpdf</a>
                    </code></b>
                  </td>
-                 <td>Uniform probability density function (PDF).</td>
+                 <td>Continuous uniform probability density function (PDF).</td>
                </tr>
                <tr>
                  <td>
                    <b><code>
                    <a href="unifrnd.html">unifrnd</a>
                    </code></b>
                  </td>
-                 <td>Random arrays from the uniform distribution.</td>
+                 <td>Random arrays from the continuous uniform distribution.</td>
                </tr>
                <tr>
                  <td>
@@ -1965,6 +1966,15 @@ <h3 class="category">
                  </td>
                  <td>Negative log-likelihood for the Gamma distribution.</td>
                </tr>
+               <tr>
+                 <td>
+                   <b><code>
+                   <a href="geofit.html">geofit</a>
+                   </code></b>
+                 </td>
+                 <td>Estimate parameter and confidence intervals for the geometric
+distribution.</td>
+               </tr>
                <tr>
                  <td>
                    <b><code>
@@ -2193,6 +2203,24 @@ <h3 class="category">
                  </td>
                  <td>Negative log-likelihood for the Rayleigh distribution.</td>
                </tr>
+               <tr>
+                 <td>
+                   <b><code>
+                   <a href="unidfit.html">unidfit</a>
+                   </code></b>
+                 </td>
+                 <td>Estimate parameter and confidence intervals for the discrete uniform
+distribution.</td>
+               </tr>
+               <tr>
+                 <td>
+                   <b><code>
+                   <a href="unifit.html">unifit</a>
+                   </code></b>
+                 </td>
+                 <td>Estimate parameter and confidence intervals for the continuous uniform
+distribution.</td>
+               </tr>
                <tr>
                  <td>
                    <b><code>

diff --git a/docs/poissrnd.html b/docs/poissrnd.html
@@ -84,7 +84,8 @@ <h3 class="d-inline-block mr-2">
  chosen from the Poisson distribution with parameter <var>lambda</var>.  The size
  of <var>r</var> is the common size of <var>lambda</var>.  A scalar input functions as a
  constant matrix of the same size as the other inputs.  <var>lambda</var> must be a
- finite real number and greater or equal to 0, otherwise NaN is returned.
+ finite real number and greater or equal to 0, otherwise <code>NaN</code> is
+ returned.
 </p>
 <p> When called with a single size argument, <code>poissrnd</code> returns a square
  matrix with the dimension specified.  When called with more than one scalar

diff --git a/docs/raylcdf.html b/docs/raylcdf.html
@@ -129,7 +129,7 @@ <h3 class="d-inline-block mr-2">
  plot (x, p1, "-b", x, p2, "g", x, p3, "-r", x, p4, "-m", x, p5, "-k")
  grid on
  ylim ([0, 1])
- legend ({"σ = 0,5", "σ = 1", "σ = 2", ...
+ legend ({"σ = 0.5", "σ = 1", "σ = 2", ...
           "σ = 3", "σ = 4"}, "location", "southeast")
  title ("Rayleigh CDF")
  xlabel ("values in x")

diff --git a/docs/raylinv.html b/docs/raylinv.html
@@ -79,7 +79,7 @@ <h3 class="d-inline-block mr-2">
 <div class="ms-5">
 <p> For each element of <var>p</var>, compute the quantile (the inverse of the CDF) of
  the Rayleigh distribution with scale parameter <var>sigma</var>.  The size of
- <var>p</var> is the common size of <var>x</var> and <var>sigma</var>.  A scalar input
+ <var>x</var> is the common size of <var>p</var> and <var>sigma</var>.  A scalar input
  functions as a constant matrix of the same size as the other inputs.
 </p>
 <p> Further information about the Rayleigh distribution can be found at