Add multiply() Method to Scale NormalDist by a Constant

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.1.3 - 2024-12-14
+- Adding `multiply()` method to scale NormalDist by a constant
+
 ## 1.1.2 - 2024-12-14
 - Implementing `add()` method for NormalDist
 

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)
 
 
 

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"

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
+        );
+    }
+
+
 
 }

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);
+
+
+});