From 64c41ff9ef2058555d5a371d37db39f42c3d5bb4 Mon Sep 17 00:00:00 2001
From: Roberto Butti <roberto.butti@gmail.com>
Date: Sat, 14 Dec 2024 11:00:17 +0100
Subject: [PATCH] Add multiply() Method to Scale NormalDist by a Constant

closes #81
---
 README.md                | 22 +++++++++++++++++++++-
 composer.json            |  2 +-
 src/NormalDist.php       | 19 +++++++++++++++++++
 tests/NormalDistTest.php | 21 +++++++++++++++++++++
 4 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 33e145e..3d2cd42 100644
--- a/README.md
+++ b/README.md
@@ -575,11 +575,31 @@ $birth_weights->getMeanRounded(5); // 2.71667
 $birth_weights->getSigmaRounded(5); // 0.50761
 ```
 
+#### Scaling a normal distribution by a costant via `multiply()` method
+
+The `multiply()` method for NormalDist multiplies both the mean (mu) and standard deviation (sigma) by a constant.
+This method is useful for rescaling distributions, such as when changing measurement units.
+The standard deviation is scaled by the absolute value of the constant to ensure it remains non-negative.
+
+The method does not modify the existing object but instead returns a new NormalDist instance with the updated values.
+
+Use Cases:
+- Rescaling distributions: useful when changing units (e.g., from meters to kilometers, or Celsius to Farenhait).
+- Transforming data: apply proportional scaling to statistical data.
+
+```php
+$tempFebruaryCelsius = new NormalDist(5, 2.5); # Celsius
+$tempFebFahrenheit = $tempFebruaryCelsius->multiply(9 / 5)->add(32); # Fahrenheit
+$tempFebFahrenheit->getMeanRounded(1); // 41.0
+$tempFebFahrenheit->getSigmaRounded(1); // 4.5
+```
+
+
 ------
 
 ### References for NormalDist
 
-This class is inspired by Python’s `statistics.NormalDist` and provides similar functionality for PHP users.
+This class is inspired by Python’s `statistics.NormalDist` and aims to provide similar functionality for PHP users. (Work in Progress)
 
 
 
diff --git a/composer.json b/composer.json
index adb3fba..ff19a54 100644
--- a/composer.json
+++ b/composer.json
@@ -18,7 +18,7 @@
         "php": "^8.1|^8.2|^8.3|^8.4"
     },
     "require-dev": {
-        "laravel/pint": "^1.13",
+        "laravel/pint": "^1.18",
         "pestphp/pest": "^2.0",
         "phpstan/phpstan": "^2",
         "rector/rector": "^2"
diff --git a/src/NormalDist.php b/src/NormalDist.php
index 60ed114..a3b4e68 100644
--- a/src/NormalDist.php
+++ b/src/NormalDist.php
@@ -136,5 +136,24 @@ public function add(float|NormalDist $x2): NormalDist
     }
 
 
+    /**
+     * Multiplies both the mean (mu) and standard deviation (sigma) by a constant.
+     *
+     * This method is useful for rescaling distributions, such as when changing
+     * measurement units. The standard deviation is scaled by the absolute value
+     * of the constant to ensure it remains non-negative.
+     *
+     * @param float $constant The constant by which to scale mu and sigma.
+     * @return NormalDist A new NormalDist instance with scaled mu and sigma.
+     */
+    public function multiply(float $constant): NormalDist
+    {
+        return new self(
+            $this->mu * $constant,                  // Scale the mean
+            $this->sigma * abs($constant),          // Scale the standard deviation by the absolute value of the constant
+        );
+    }
+
+
 
 }
diff --git a/tests/NormalDistTest.php b/tests/NormalDistTest.php
index 50112e6..f23bff5 100644
--- a/tests/NormalDistTest.php
+++ b/tests/NormalDistTest.php
@@ -64,3 +64,24 @@
 
 
 });
+
+
+it(' multiply Normal Dist', function (): void {
+    $tempFebruaryCelsius = new NormalDist(5, 2.5); # Celsius
+    $tempFebFahrenheit = $tempFebruaryCelsius->multiply(9 / 5)->add(32); # Fahrenheit
+    expect(
+        $tempFebFahrenheit->getMeanRounded(1),
+    )->toEqual(41.0);
+    expect(
+        $tempFebFahrenheit->getSigmaRounded(1),
+    )->toEqual(4.5);
+
+    expect(
+        $tempFebruaryCelsius->getMeanRounded(1),
+    )->toEqual(5.0);
+    expect(
+        $tempFebruaryCelsius->getSigmaRounded(1),
+    )->toEqual(2.5);
+
+
+});