From 9a7018c5c89af5ef5f782c4a0b54ed2d933ccbf4 Mon Sep 17 00:00:00 2001
From: Krishna Vedala <krishna.vedala@ieee.org>
Date: Thu, 28 May 2020 17:14:39 -0400
Subject: [PATCH] document poisson distribution

---
 probability/poisson_dist.cpp | 61 ++++++++++++++++++++++--------------
 1 file changed, 37 insertions(+), 24 deletions(-)

diff --git a/probability/poisson_dist.cpp b/probability/poisson_dist.cpp
index 345363368..6a2a377c3 100644
--- a/probability/poisson_dist.cpp
+++ b/probability/poisson_dist.cpp
@@ -1,26 +1,32 @@
-#include <iostream>
+/**
+ * @file
+ * @brief [Poisson
+ * statistics](https://en.wikipedia.org/wiki/Poisson_distribution)
+ *
+ * The Poisson distribution counts how many
+ * events occur over a set time interval.
+ */
 #include <cmath>
+#include <iostream>
 
-// The Poisson distribution counts how many
-// events occur over a set time interval
-// https://en.wikipedia.org/wiki/Poisson_distribution
-
-// calculate the events per unit time
-// e.g 5 dollars every 2 mins = 5 / 2 = 2.5
-
+/**
+ * poisson rate:\n
+ * calculate the events per unit time\n
+ * e.g 5 dollars every 2 mins = 5 / 2 = 2.5
+ */
 double poisson_rate(double events, double timeframe) {
     return events / timeframe;
 }
 
-// calculate the expected value over a time
-// e.g rate of 2.5 over 10 mins = 2.5 x 10 = 25
-
-double poisson_expected(double rate, double time) {
-    return rate * time;
-}
-
-// find the factorial of a given number
+/**
+ *  calculate the expected value over a time
+ * e.g rate of 2.5 over 10 mins = 2.5 x 10 = 25
+ */
+double poisson_expected(double rate, double time) { return rate * time; }
 
+/**
+ * Compute factorial of a given number
+ */
 double fact(double x) {
     double x_fact = x;
     for (int i = x - 1; i > 0; i--) {
@@ -33,14 +39,18 @@ double fact(double x) {
     return x_fact;
 }
 
-// find the probability of x successes in a Poisson dist
-
+/**
+ * Find the probability of x successes in a Poisson dist.
+ * \f[p(\mu,x) = \frac{\mu^x e^{-\mu}}{x!}\f]
+ */
 double poisson_x_successes(double expected, double x) {
-    return (pow(expected, x) * exp(-expected)) / fact(x);
+    return (std::pow(expected, x) * std::exp(-expected)) / fact(x);
 }
 
-// probability of a success in range for Poisson dist (inclusive, inclusive)
-
+/**
+ * probability of a success in range for Poisson dist (inclusive, inclusive)
+ * \f[P = \sum_i p(\mu,i)\f]
+ */
 double poisson_range_successes(double expected, double lower, double upper) {
     double probability = 0;
     for (int i = lower; i <= upper; i++) {
@@ -49,6 +59,9 @@ double poisson_range_successes(double expected, double lower, double upper) {
     return probability;
 }
 
+/**
+ * main function
+ */
 int main() {
     double rate, expected;
     rate = poisson_rate(3, 1);
@@ -57,10 +70,10 @@ int main() {
     expected = poisson_expected(rate, 2);
     std::cout << "Poisson expected : " << expected << std::endl;
 
-    std::cout << "Poisson 0 successes : "
-        <<poisson_x_successes(expected, 0) <<std::endl;
+    std::cout << "Poisson 0 successes : " << poisson_x_successes(expected, 0)
+              << std::endl;
     std::cout << "Poisson 0-8 successes : "
-        << poisson_range_successes(expected, 0, 8) <<std::endl;
+              << poisson_range_successes(expected, 0, 8) << std::endl;
 
     return 0;
 }