Preparing release 0.4.0, documentation improvements.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2024 Dialid Santiago (Quant Girl)
+Copyright (c) 2022-2024 Dialid Santiago (@Quant_Girl)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,7 +1,6 @@
 # *aleatory*
 
 [![PyPI version fury.io](https://badge.fury.io/py/aleatory.svg)](https://pypi.org/project/aleatory/) [![Downloads](https://static.pepy.tech/personalized-badge/aleatory?period=total&units=international_system&left_color=black&right_color=blue&left_text=Downloads)](https://pepy.tech/project/aleatory)
-
 ![example workflow](https://github.com/quantgirluk/aleatory/actions/workflows/python-package.yml/badge.svg) [![Documentation Status](https://readthedocs.org/projects/aleatory/badge/?version=latest)](https://aleatory.readthedocs.io/en/latest/?badge=latest)
 
 - [Git Homepage](https://github.com/quantgirluk/aleatory)
@@ -22,19 +21,21 @@ stochastic processes $X = (X_t : t\geq 0)$ and provides methods to:
 <img src="https://raw.githubusercontent.com/quantgirluk/aleatory/main/docs/source/_static/vasicek_process_drawn.png"   style="display:block;float:none;margin-left:auto;margin-right:auto;width:80%">
 </p>
 
-Currently, `aleatory` supports the following processes:
+Currently, `aleatory` supports the following 13 processes:
 
 - Brownian Motion
 - Brownian Bridge
 - Brownian Excursion
 - Brownian Meander
-- Geometric Brownian Motion
-- Ornstein–Uhlenbeck
-- Vasicek
-- Cox–Ingersoll–Ross
-- Constant Elasticity
-- Bessel Process
-- Squared Bessel Processs
+- Geometric Brownian Motion (GBM) process
+- Ornstein–Uhlenbeck (OU) process
+- Vasicek process
+- Cox–Ingersoll–Ross (CIR) process
+- Constant Elasticity Variance (CEV) process
+- Chan-Karolyi-Longstaff-Sanders (CKLS) process
+- Bessel (BES) process
+- Squared Bessel (BESQ) process
+- Poisson process
 
 ## Installation
 

aleatory/processes/analytical/bes.py

@@ -117,9 +117,9 @@ def simulate(self, n, N):
         """
         Simulate paths/trajectories from the instanced stochastic process.
 
-        param n: number of steps in each path
-        param N: number of paths to simulate
-        return: list with N paths (each one is a numpy array of size n)
+        :param int n: number of steps in each path
+        :param int N: number of paths to simulate
+        :return: list with N paths (each one is a numpy array of size n)
         """
         self.n = n
         self.N = N

aleatory/processes/analytical/brownian_bridge.py

@@ -27,12 +27,12 @@ class BrownianBridge(BrownianMotion):
 
     More generally, a Brownian Bridge is  subject to the conditions :math:`W(0) = a` and :math:`W(T) = b`.
 
-    Parameters
-        :param float initial: initial condition
-        :param float end: end condition
-        :param float T: the right hand endpoint of the time interval :math:`[0,T]`
+
+    :param float initial: initial condition
+    :param float end: end condition
+    :param float T: the right hand endpoint of the time interval :math:`[0,T]`
         for the process
-        :param numpy.random.Generator rng: a custom random number generator
+    :param numpy.random.Generator rng: a custom random number generator
 
     """
     def __init__(self, initial=0.0, end=0.0, T=1.0, rng=None):

aleatory/processes/analytical/brownian_excursion.py

@@ -18,10 +18,9 @@ class BrownianExcursion(BrownianBridge):
     to be positive and to take the value 0 at time 1. Alternatively, it can be defined as a Brownian
     Bridge process conditioned to be positive.
 
-    Parameters
-        :param float T: the right hand endpoint of the time interval :math:`[0,T]`
+    :param float T: the right hand endpoint of the time interval :math:`[0,T]`
         for the process
-        :param numpy.random.Generator rng: a custom random number generator
+    :param numpy.random.Generator rng: a custom random number generator
 
     """
     def __init__(self, T=1.0, rng=None):

aleatory/processes/analytical/brownian_meander.py

@@ -25,8 +25,11 @@ class BrownianMeander(BrownianMotion):
     .. math::
         W_t^{+} = \frac{1}{\sqrt{1-\tau}} |W(\tau  + t (1-\tau))|, \ \ \ \   t\in (0,1].
 
-
-    Parameters
+    :param float T: the right hand endpoint of the time interval :math:`[0,T]`
+        for the process
+    :param bool fixed_end: flag to indicate if the process has a fixed end point. Defaults to `False`
+    :param float end: end point for the Meander, in the case of `fixed_end` equal `True`
+    :param numpy.random.Generator rng: a custom random number generator
 
     """
 

aleatory/processes/analytical/brownian_motion.py

@@ -32,7 +32,7 @@ class BrownianMotion(SPAnalytical):
 
     - :math:`\mu` is the drift
     - :math:`\sigma>0` is the volatility
-    - :math:`W_t` is a standard Brownian Motion.
+    - :math:`W_t` is a standard Brownian Motion
 
     Clearly, the solution to this equation can be written as
 
@@ -42,14 +42,12 @@ class BrownianMotion(SPAnalytical):
 
     and each :math:`X_t \sim N(\mu t, \sigma^2 t)`.
 
-    Parameters:
 
-    :param float drift: the parameter :math:`\mu` in the above SDE
-    :param float scale: the parameter :math:`\sigma>0` in the above SDE
-    :param float initial: the initial condition :math:`x_0` in the above SDE
-    :param float T: the right hand endpoint of the time interval :math:`[0,T]`
-        for the process
-    :param numpy.random.Generator rng: a custom random number generator
+    :parameter float drift: the parameter :math:`\mu` in the above SDE
+    :parameter float scale: the parameter :math:`\sigma>0` in the above SDE
+    :parameter float initial: the initial condition :math:`x_0` in the above SDE
+    :parameter float T: the right hand endpoint of the time interval :math:`[0,T]` for the process
+    :parameter numpy.random.Generator rng: a custom random number generator
 
     """
 
@@ -116,7 +114,7 @@ def sample(self, n):
         """
         Generates a discrete time sample from a Brownian Motion instance.
 
-        :param n: the number of steps
+        :param int n: the number of steps
         :return: numpy array
         """
         return self._sample_brownian_motion(n)
@@ -190,13 +188,12 @@ def draw(self, n, N, marginal=True, envelope=False, type='3sigma', title=None, *
         - probability density function of the marginal distribution :math:`X_T` (optional when ``marginal = True``)
         - envelope of confidence intervals across time (optional when ``envelope = True``)
 
-
-        :param n: number of steps in each path
-        :param N: number of paths to simulate
-        :param marginal: bool, default: True
-        :param envelope: bool, default: False
-        :param type: string, default: '3sigma'
-        :param title: string to customise plot title
+        :param int n: number of steps in each path
+        :param int N: number of paths to simulate
+        :param bool marginal:  defaults to True
+        :param bool envelope:   defaults to False
+        :param str type:   defaults to  '3sigma'
+        :param str title:  to be used to customise plot title. If not passed, the title defaults to the name of the process.
         :return:
         """
 

aleatory/processes/base_analytical.py

@@ -26,8 +26,8 @@ def simulate(self, n, N):
         """
         Simulate paths/trajectories from the instanced stochastic process.
 
-        :param n: number of steps in each path
-        :param N: number of paths to simulate
+        :param int n: number of steps in each path
+        :param int N: number of paths to simulate
         :return: list with N paths (each one is a numpy array of size n)
         """
         self.n = n
@@ -94,10 +94,11 @@ def plot(self, n, N, title=None, **fig_kw):
         Simulates and plots paths/trajectories from the instanced stochastic process.
         Simple plot of times versus process values as lines and/or markers.
 
-        :param n: number of steps in each path
-        :param N: number of paths to simulate
-        :param title: string to customise plot title
+        :parameter int n: number of steps in each path
+        :parameter int N: number of paths to simulate
+        :parameter str title: string to customise plot title
         :return:
+
         """
         self.simulate(n, N)
         if title:
@@ -155,11 +156,11 @@ def draw(self, n, N, marginal=True, envelope=False, title=None, **fig_kw):
         - probability density function of the marginal distribution :math:`X_T`
         - envelope of confidence intervals
 
-        :param n: number of steps in each path
-        :param N: number of paths to simulate
-        :param marginal: bool, default: True
-        :param envelope: bool, default: False
-        :param title: string optional default to None
+        :param int n: number of steps in each path
+        :param int N: number of paths to simulate
+        :param bool marginal: defaults to True
+        :param bool envelope: defaults to False
+        :param str title: string optional default to the name of the process
         :return:
         """
         return self._draw_qqstyle(n, N, marginal=marginal, envelope=envelope, title=title, **fig_kw)

aleatory/processes/euler_maruyama/ckls_process.py

@@ -22,7 +22,7 @@ class CKLSProcess(CKLSProcessGeneric):
     with initial condition :math:`X_0 = x_0`, where
 
     - :math:`\alpha \in \mathbb{R}`
-    - :math:`\beata \in \mathbb{R}`
+    - :math:`\beta \in \mathbb{R}`
     - :math:`\sigma>0` is the scale of the volatility
     - :math:`\gamma\geq 0` is the elasticity term
     - :math:`W_t` is a standard Brownian Motion.
@@ -31,6 +31,16 @@ class CKLSProcess(CKLSProcessGeneric):
     An Empirical Comparison of Alternative Models of the Short-Term Interest Rate. The Journal of Finance,
     47: 1209-1227. https://doi.org/10.1111/j.1540-6261.1992.tb04011.x
 
+
+    :param float alpha: the parameter :math:`\alpha` in the above SDE
+    :param float beta: the parameter :math:`\beta` in the above SDE
+    :param float sigma: the parameter :math:`\sigma>0` in the above SDE
+    :param float gamma: the parameter :math:`\gamma\geq 0` in the above SDE
+    :param float initial: the initial condition :math:`x_0` in the above SDE
+    :param float T: the right hand endpoint of the time interval :math:`[0,T]`
+        for the process
+    :param numpy.random.Generator rng: a custom random number generator
+
     """
     def __new__(cls, *args, **kwargs):
         alpha = kwargs['alpha'] if  'alpha' in kwargs else 0.5

aleatory/processes/jump/poisson.py

@@ -18,10 +18,10 @@ class PoissonProcess(BaseProcess):
     A Poisson point process is a type of random mathematical object that consists of points randomly located on
     a mathematical space with the essential feature that the points occur independently of one another.
 
-    A Poisson process :math:`{N(t) : t\geq 0}` with intensity rate :math:`\lambda>0` is defined by the following properties:
+    A Poisson process :math:`{N(t) : t\geq 0}` with intensity rate :math:`\lambda>0`, is defined by the following properties:
 
-    1. :math:`N(t)` has a Poisson distribution with parameter :math:`\lambda t`, for each :math:`t> 0`.
-    2. It has independent increments
+    -  :math:`N(t)` has a Poisson distribution with parameter :math:`\lambda t`, for each :math:`t> 0`.
+    -  It has independent increments
 
     """
 
@@ -81,17 +81,30 @@ def marginal_expectation(self, times):
     def simulate(self, N, jumps=None, T=None):
         """
         Simulate paths/trajectories from the instanced stochastic process.
+        It requires either the number of jumps (`jumps`) or the  time (`T`)
+        for the simulation to end.
 
-        :param N: number of paths to simulate
-        :param jumps: number of jumps
-        :param T: time T
+        - If `jumps` is provided, the function returns :math:`N` paths each one with exactly
+            that number of jumps.
+
+        - If `T` is provided, the function returns :math:`N` paths over the time :math:`[0,T]`. Note
+            that in this case each path can have a different number of jumps.
+
+        :param int N: number of paths to simulate
+        :param int jumps: number of jumps
+        :param float T: time T
         :return: list with N paths (each one is a numpy array of size n)
+
         """
         self.N = N
         self.paths = [self.sample(jumps=jumps, T=T) for _ in range(N)]
         return self.paths
 
     def plot(self, N, jumps=None, T=None, style="seaborn-v0_8-whitegrid", title=None, **fig_kw):
+        """
+        Simulates and plots paths/trajectories from the instanced stochastic process. Simple plot of times
+        versus process values as lines and/or markers.
+        """
 
         plot_title = title if title else self.name
         self.simulate(N, jumps=jumps, T=T)

docs/source/conf.py

@@ -24,7 +24,7 @@
 author = 'Dialid Santiago'
 
 # The full version, including alpha/beta/rc tags
-release = '0.3.0'
+release = '0.4.0'
 
 # -- General configuration ---------------------------------------------------
 

docs/source/index.rst

@@ -33,17 +33,19 @@ functionality to:
 
 Currently, `aleatory` supports the following processes:
 
-- Brownian Motion
-- Brownian Bridge
-- Brownian Excursion
-- Brownian Meander
-- Geometric Brownian Motion
-- Ornstein–Uhlenbeck
-- Vasicek
-- Cox–Ingersoll–Ross
-- Constant Elasticity
-- Bessel
-- Squared Bessel
+1. Brownian Motion
+2. Brownian Bridge
+3. Brownian Excursion
+4. Brownian Meander
+5. Geometric Brownian Motion
+6. Ornstein–Uhlenbeck (OU) process
+7. Vasicek process
+8. Cox–Ingersoll–Ross (CIR) process
+9. Constant Elasticity Variance (CEV) process
+10. Chan-Karolyi-Longstaff-Sanders (CKLS) process
+11. Bessel processes
+12. Squared Bessel processes
+13. Poisson process
 
 
 

docs/source/processes_analytical.rst

@@ -13,6 +13,8 @@ analytical form.
 * :py:class:`aleatory.processes.GBM`
 * :py:class:`aleatory.processes.BESProcess`
 * :py:class:`aleatory.processes.BESQProcess`
+* :py:class:`aleatory.processes.PoissonProcess`
+
 
 
 .. autoclass:: aleatory.processes.BrownianMotion
@@ -36,4 +38,5 @@ analytical form.
 .. autoclass:: aleatory.processes.BESQProcess
     :members: T, sample, simulate, plot, draw
 
-
+.. autoclass:: aleatory.processes.PoissonProcess
+    :members: sample, simulate, plot, draw

docs/source/processes_euler_maruyama.rst

@@ -9,6 +9,7 @@ cannot be expressed in analytical form. These processes are simulated via the
 * :py:class:`aleatory.processes.Vasicek`
 * :py:class:`aleatory.processes.CIRProcess`
 * :py:class:`aleatory.processes.CEVProcess`
+* :py:class:`aleatory.processes.CKLSProcess`
 
 
 .. autoclass:: aleatory.processes.OUProcess
@@ -21,4 +22,7 @@ cannot be expressed in analytical form. These processes are simulated via the
     :members: T, sample, simulate, plot, draw
 
 .. autoclass:: aleatory.processes.CEVProcess
+    :members: T, sample, simulate, plot, draw
+
+.. autoclass:: aleatory.processes.CKLSProcess
     :members: T, sample, simulate, plot, draw

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aleatory"
-version = "0.3.0"
+version = "0.4.0"
 authors = [{ name = "Dialid Santiago", email = "[email protected]" }, ]
 description = "Stochastic Processes Simulation and Visualisation"
 readme = "README.md"

requirements.txt

@@ -1,6 +1,6 @@
 pandas>=1.5.2
 numpy>=1.23.5
-scipy>=1.9.3
+scipy>=1.10.0
 matplotlib>=3.6.2
 statsmodels>=0.13.5
 parameterized>=0.8.1