diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ab93dd..55c7d96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ # Changelog +## 1.1.2 - 2024-12-14 +- Implementing `add()` method for NormalDist + ## 1.1.1 - 2024-12-13 - Implementing fromSample method for NormalDist diff --git a/README.md b/README.md index d6a3f53..33e145e 100644 --- a/README.md +++ b/README.md @@ -489,6 +489,7 @@ $normalDist = new NormalDist(float $mu = 0.0, float $sigma = 1.0); ### Methods #### Creating a normal distribution instance from sample data + The `fromSamples()` static method creates a normal distribution instance with mu and sigma parameters estimated from the sample data. Example: @@ -508,8 +509,8 @@ Calculates the **Probability Density Function** at a given value xxx: $normalDist->pdf(float $x): float ``` -**Input**: The value `$x` at which to evaluate the PDF. -**Output**: The relative likelihood of `$x` in the distribution. +- Input: the value `$x` at which to evaluate the PDF. +- Output: the relative likelihood of `$x` in the distribution. Example: @@ -527,8 +528,9 @@ Calculates the **Cumulative Distribution Function** at a given value `$x`: ```php $normalDist->cdf(float $x): float ``` -**Input**: The value `$x` at which to evaluate the CDF. -**Output**: The probability that a random variable `$x` is less than or equal to `$x`. +- Input: the value `$x` at which to evaluate the CDF. +- Output: the probability that a random variable `$x` is less than or equal to `$x`. + Example: ```php @@ -536,9 +538,7 @@ $normalDist = new NormalDist(10.0, 2.0); echo $normalDist->cdf(12.0); // Output: 0.8413447460685429 ``` ------- - -### Use case example +Calculating both, CDF and PDF: ```php $normalDist = new NormalDist(10.0, 2.0); @@ -554,6 +554,29 @@ echo "CDF at x = 12: $cdf\n"; // Output: 0.8413447460685429 ------ +#### Combining a normal distribution via `add()` method + +The `add()` method allows you to combine a NormalDist instance with either a constant or another NormalDist object. +This operation supports mathematical transformations and the combination of distributions. + +The use cases are: +- Shifting a distribution: add a constant to shift the mean, useful in translating data. +- Combining distributions: combine independent or jointly normally distributed variables, commonly used in statistics and probability. + +```php +$birth_weights = NormalDist::fromSamples([2.5, 3.1, 2.1, 2.4, 2.7, 3.5]); +$drug_effects = new NormalDist(0.4, 0.15); +$combined = $birth_weights->add($drug_effects); + +$combined->getMeanRounded(1); // 3.1 +$combined->getSigmaRounded(1); // 0.5 + +$birth_weights->getMeanRounded(5); // 2.71667 +$birth_weights->getSigmaRounded(5); // 0.50761 +``` + +------ + ### References for NormalDist This class is inspired by Python’s `statistics.NormalDist` and provides similar functionality for PHP users. diff --git a/src/NormalDist.php b/src/NormalDist.php index f1781ca..60ed114 100644 --- a/src/NormalDist.php +++ b/src/NormalDist.php @@ -111,5 +111,30 @@ public function cdfRounded(float $x, int $precision = 3): float } + /** + * Adds a constant or another NormalDist instance to this distribution. + * + * If the argument is: + * - A constant (float): Adjusts the mean (mu), leaving sigma unchanged. + * - A NormalDist instance: Combines the means and variances. + * + * @param float|NormalDist $x2 The value or NormalDist to add. + * @return NormalDist A new NormalDist instance with the updated parameters. + * @throws InvalidDataInputException If the argument is not a float or NormalDist. + */ + public function add(float|NormalDist $x2): NormalDist + { + if ($x2 instanceof NormalDist) { + // Add the means and combine the variances (using the Pythagorean theorem) + $newMu = $this->mu + $x2->mu; + $newSigma = hypot($this->sigma, $x2->sigma); + // sqrt(sigma1^2 + sigma2^2) + return new NormalDist($newMu, $newSigma); + } + // Add a constant to the mean, sigma remains unchanged + return new NormalDist($this->mu + $x2, $this->sigma); + } + + } diff --git a/tests/NormalDistTest.php b/tests/NormalDistTest.php index 485d47d..50112e6 100644 --- a/tests/NormalDistTest.php +++ b/tests/NormalDistTest.php @@ -42,3 +42,25 @@ $normalDist->getSigmaRounded(5), )->toEqual(0.50761); }); + + +it(' add to Normal Dist', function (): void { + $birth_weights = NormalDist::fromSamples([2.5, 3.1, 2.1, 2.4, 2.7, 3.5]); + $drug_effects = new NormalDist(0.4, 0.15); + $combined = $birth_weights->add($drug_effects); + expect( + $combined->getMeanRounded(1), + )->toEqual(3.1); + expect( + $combined->getSigmaRounded(1), + )->toEqual(0.5); + + expect( + $birth_weights->getMeanRounded(5), + )->toEqual(2.71667); + expect( + $birth_weights->getSigmaRounded(5), + )->toEqual(0.50761); + + +});