adding the z_score_scaler

Author: amirberenji1995

docs/utils.md

@@ -84,4 +84,41 @@ from damavand.damavand.utils import zoomed_fft_freq_axis
 
 # Generating a frequency axis for zoomed frequency spectrum, covering from 0 Hz to 2500 Hz using 2500 points
 zoomed_freq_axis = zoomed_fft_freq_axis(0, 2500, 2500)
+```
+
+## `z_score_scaler(signals, axis=1, return_df=True, eps=1e-8)`
+
+### Z-score standardization of time-series signals
+
+##### Arguments:
+- **signals**: A `pandas.DataFrame` or `numpy.ndarray` including signals in its rows.
+- **axis**: An `int` (`0` or `1`) specifying the normalization direction. 
+ - `axis=1` (default): each signal is independently standardized over time (row-wise). 
+ - `axis=0`: each time step is standardized across signals (column-wise).
+- **return_df**: A `bool` indicating whether to return a `pandas.DataFrame` when the input is a DataFrame.
+- **eps**: A small `float` added to the standard deviation to avoid division by zero.
+
+##### Return Values:
+- A scaled `pandas.DataFrame` or `numpy.ndarray` (matching the input type by default), where each signal has zero mean and unit variance according to the selected axis.
+
+##### Descriptions:
+This function applies **Z-score standardization** (also known as standardization or Z-score normalization) to time-series signals. 
+Each signal (or time step) is centered by subtracting its mean and scaled by its standard deviation, improving numerical stability and convergence behavior during model training.
+
+##### Usage example:
+
+```Python
+# Importings
+import pandas as pd
+import numpy as np
+from damavand.damavand.augmentations import z_score_scaler
+
+# Example signals (rows = signals, columns = time steps)
+signals = pd.DataFrame(np.random.randn(5, 1000))
+
+# Apply row-wise Z-score standardization (each signal independently)
+signals_scaled = z_score_scaler(signals, axis=1)
+
+# Convert output to NumPy array
+signals_scaled_np = z_score_scaler(signals, axis=1, return_df=False)
 ```