Feature/survival probability (#6)

* Change testing from unittest to pytest

* Add survival probability method

* Update test to use parametrizations

* Test output index matches input.

* Fix method so input index persists.

* Update Gamestop Power Law notebook

* Update README.md

* Update README.md

Author: FergM

README.md

@@ -15,19 +15,29 @@ See the [notebooks/README.md](./notebooks/) for more detail.
 My favourite notebooks so far:
 * [Central Limit Theorem: How the sum of Uniform values is Gaussian](./notebooks/NB-22%20-%20Visual%20Central%20Limit%20Theorem.ipynb)
 * [S&P500: How geometric average return is impossible](./notebooks/Notebook-11%20-%20Ergodicity%20and%20S%26P500.ipynb)
+* [GameStop: January 2021 was not an outlier if you assume Power Law tails.](./notebooks/NB-25%20-%20Survival%20Plot%20-%20Gamestop.ipynb)
 
 ### Functions
 * `fattails.metrics.mad()`: Calculates mean absolute deviation.
+* `fattails.metrics.get_survival_probability()`: Calculate survival probabilities for a given dataset.
 
 Example:
 ```
 $ pip install fattails
 $ python
 
->>> import fattails
->>> from fattails.metrics import mad
->>> mad([1,2,3]) # Calculate Mean Absolute Deviation of [1,2,3]
+>>> import fattails.metrics as fattails
+>>>
+>>>
+>>> fattails.mad([1,2,3]) # Calculate Mean Absolute Deviation of [1,2,3]
 0.6666666666666666
+>>>
+>>>
+>>> fattails.get_survival_probability([1,2,3]) # Get survival probability for each value in your data
+0    0.75
+1    0.50
+2    0.25
+Name: survival_probability, dtype: float64
 ```
 
 ### Derivations

fattails/metrics.py

@@ -1,4 +1,6 @@
+from copy import copy
 import numpy as np
+import pandas as pd
 
 def mad(x):
     """Calculate Mean Absolute Deviation
@@ -24,4 +26,62 @@ def mad(x):
 
     mad = np.mean(absolute_deviation)
 
-    return mad
+    return mad
+
+def get_survival_probability(arr):
+    """Calculate sample probability of X >= x, for each value in `arr`.
+
+    Duplicate values are treated as ascending values based on
+    their position in `arr`.
+
+    Parameters
+    ----------
+    arr : array_like
+        Numeric values on the real number line
+
+    Returns
+    -------
+    survival_probability_sr : Pandas Series
+    """
+    #---------------------------------------------------
+    # PREPARE
+    ## Sort values from low to high. Keep track of original
+    ## index and order.
+
+    arr = copy(arr)     # Copy to avoid accidental mutation
+    sr = pd.Series(arr) # Ensure we have a pandas series
+
+    ## Keep a copy of the original index
+    input_index = sr.index.copy()
+
+    ## Create index of input order
+    df = sr.reset_index(name='input_values') # Keeps the input index as a column
+    df.index.name = 'input_order' # Name the new index
+
+    ## Sort from low to high and reindex
+    df = df.sort_values(by='input_values') # sort from low to high
+    df = df.reset_index()
+    df.index.name = 'sorted_order' # Name the new index
+
+    #---------------------------------------------------
+    # CALCULATE
+
+    # Label relative positions
+    gap_count = len(sr) + 1           # Think of the Posts and Fences analogy
+    df['left_gap_count'] = df.index + 1                   # Count values <= x
+    df['right_gap_count'] = gap_count - df.left_gap_count # Count values >= x
+
+    # Get survival Probability
+    df['survival_probability'] = df.right_gap_count / gap_count
+
+    #---------------------------------------------------
+    # FORMAT THE OUTPUT
+
+    #Reset Input Order and Index
+    df = df.sort_values(by='input_order') # sort from low to high
+    df.index = input_index
+
+    #Extract the output series
+    survival_probability_sr = df.survival_probability
+
+    return survival_probability_sr