HSTransform 0.1.1__tar.gz

HSTransform-0.1.1/HSTransform.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.1
+Name: HSTransform
+Version: 0.1.1
+Summary: A Package to Compute S-transform with Hyperbolic Window
+Home-page: https://github.com/nvlinhvn/HSTransform
+Author: Linh V Nguyen
+Author-email: linhvietnguyen.ee@gmail.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Hyperbolic S-Transform
+
+Package for Hyperbolic S-transform
+
+## 1. Introduction
+
+HS Transform is a Python package for performing Hyperbolic [S-transform](https://en.wikipedia.org/wiki/S_transform) [[1]](#1). The S-transform is a time-frequency representation that combines the best properties of the Short-time Fourier Transform and the Wavelet Transform. It provides simultaneous information on both the frequency content and temporal localization of a signal.
+
+This is a work of my [published paper](https://ieeexplore.ieee.org/document/8423487)
+
+### References
+
+<a id="1">[1]</a>
+Stockwell, R.G., Mansinha, L. & Lowe, R.P., (1996).
+Localization of the complex spectrum: the S transform.
+IEEE Trans. Signal Process., 44(4), 998–1001, doi:10.1109/78.492555
+
+## 2. Dependencies
+
+HS Transform requires the following Python packages:
+
+- numpy
+- scipy
+- pandas
+- matplotlib
+- pytest
+
+## 3. How to Install
+
+After that, you can install HS Transform using pip:
+
+```
+pip install HSTransform
+```
+
+You can also install all dependencies and package in 1 statement
+
+```
+pip install numpy scipy pandas matplotlib pytest HSTransform
+```
+
+## 4. Run tests
+
+After installation, you can test the package using the included test scripts:
+`pytest tests/`
+
+## 5. Example
+
+Here’s an example of how to use HS Transform to analyze a signal with voltage disturbance and power system fault:
+
+It's noted sometimes you need to include the installed HSTransform package location into sys
+
+```python
+import sys
+import os
+
+# Add the package directory to sys.path
+package_path = os.path.abspath('/usr/local/Caskroom/miniconda/base/envs/YOUR_ENVIRONMENT/lib/python3.10/site-packages/')
+if package_path not in sys.path:
+    sys.path.insert(0, package_path)
+
+import numpy as np
+from hstransform import HSTransform
+
+# Create input signal (for example: Voltage signal)
+t = np.linspace(0, 10, 100) # timeseries
+V_m = 220*np.sqrt(2)  # peak voltage
+f_V = 50  # frequency
+phi_V = 0  # phase
+
+V_clean = V_m * np.sin(2 * np.pi * f_V * t + phi_V)
+# Create voltage sag/dip (80% of the nominal voltage for 0.15 second)
+V_sag = np.where((t >= 2) & (t <= 3.5), 0.5 * V_clean, V_clean)
+
+# Create an instance of HSTransform
+
+hs = HSTransform()
+
+# Perform the transform
+signal = V_sag
+S_transformed = hs.fit_transform(t, signal)
+```
+
+### 5.1 Power Quality Disturbance
+
+Compare HS-transform vs. Morlet Wavelet Transform:
+![Voltage Disturbance](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/power_quality_disturbance.png)
+
+The figure showed HS-transform is able to detect the transient disturbances like notch, spike. Meanwhile, those signals from Morlet Wavelet transform are not obviously recognized.
+
+######
+
+![Real-Imag Trajectory](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/power_quality_disturbance_trajectory.png)
+We can see also different types of voltage disturbance can generate different real-imaginary trajectory in S-transform at different frequencies.
+
+### 5.2 Power System Faults
+
+![Different Faults](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/fault_current.png)
+
+As can be seen, both Wavelet and S-transform are able to detect when the fault occur (huge change in current magnitude). Wavelet transform seems more sensitive with noise with high distortion compared with HS-transform.
+
+######
+
+![Real-Imag Trajectory](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/fault_trajectory.png)
+
+We can also observe different types of faults can generate different real-imaginary trajectory in S-transform at varying levels of frequencies.
+
+## 6. Communication
+
+If you have any questions, issues, or suggestions for HS Transform, please open an issue on the GitHub repository.
+or contact email: linhvietnguyen.ee@gmail.com
+
+## 7. Citation
+
+If you use HS Transform in your research, please cite it as follows:
+Linh V Nguyen (2024). HS Transform (Version 0.1) [Computer software]. GitHub: github.com/nvlinhvn/hstransform

HSTransform-0.1.1/HSTransform.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+setup.py
+HSTransform.egg-info/PKG-INFO
+HSTransform.egg-info/SOURCES.txt
+HSTransform.egg-info/dependency_links.txt
+HSTransform.egg-info/requires.txt
+HSTransform.egg-info/top_level.txt
+hstransform/__init__.py
+hstransform/hstransform.py
+tests/__init__.py
+tests/test_hstransform.py

HSTransform-0.1.1/HSTransform.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

HSTransform-0.1.1/HSTransform.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.21.2
+scipy>=1.7.1
+pandas>=1.3.3
+pytest>=6.2.5

HSTransform-0.1.1/HSTransform.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+hstransform
+tests

HSTransform-0.1.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.1
+Name: HSTransform
+Version: 0.1.1
+Summary: A Package to Compute S-transform with Hyperbolic Window
+Home-page: https://github.com/nvlinhvn/HSTransform
+Author: Linh V Nguyen
+Author-email: linhvietnguyen.ee@gmail.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Hyperbolic S-Transform
+
+Package for Hyperbolic S-transform
+
+## 1. Introduction
+
+HS Transform is a Python package for performing Hyperbolic [S-transform](https://en.wikipedia.org/wiki/S_transform) [[1]](#1). The S-transform is a time-frequency representation that combines the best properties of the Short-time Fourier Transform and the Wavelet Transform. It provides simultaneous information on both the frequency content and temporal localization of a signal.
+
+This is a work of my [published paper](https://ieeexplore.ieee.org/document/8423487)
+
+### References
+
+<a id="1">[1]</a>
+Stockwell, R.G., Mansinha, L. & Lowe, R.P., (1996).
+Localization of the complex spectrum: the S transform.
+IEEE Trans. Signal Process., 44(4), 998–1001, doi:10.1109/78.492555
+
+## 2. Dependencies
+
+HS Transform requires the following Python packages:
+
+- numpy
+- scipy
+- pandas
+- matplotlib
+- pytest
+
+## 3. How to Install
+
+After that, you can install HS Transform using pip:
+
+```
+pip install HSTransform
+```
+
+You can also install all dependencies and package in 1 statement
+
+```
+pip install numpy scipy pandas matplotlib pytest HSTransform
+```
+
+## 4. Run tests
+
+After installation, you can test the package using the included test scripts:
+`pytest tests/`
+
+## 5. Example
+
+Here’s an example of how to use HS Transform to analyze a signal with voltage disturbance and power system fault:
+
+It's noted sometimes you need to include the installed HSTransform package location into sys
+
+```python
+import sys
+import os
+
+# Add the package directory to sys.path
+package_path = os.path.abspath('/usr/local/Caskroom/miniconda/base/envs/YOUR_ENVIRONMENT/lib/python3.10/site-packages/')
+if package_path not in sys.path:
+    sys.path.insert(0, package_path)
+
+import numpy as np
+from hstransform import HSTransform
+
+# Create input signal (for example: Voltage signal)
+t = np.linspace(0, 10, 100) # timeseries
+V_m = 220*np.sqrt(2)  # peak voltage
+f_V = 50  # frequency
+phi_V = 0  # phase
+
+V_clean = V_m * np.sin(2 * np.pi * f_V * t + phi_V)
+# Create voltage sag/dip (80% of the nominal voltage for 0.15 second)
+V_sag = np.where((t >= 2) & (t <= 3.5), 0.5 * V_clean, V_clean)
+
+# Create an instance of HSTransform
+
+hs = HSTransform()
+
+# Perform the transform
+signal = V_sag
+S_transformed = hs.fit_transform(t, signal)
+```
+
+### 5.1 Power Quality Disturbance
+
+Compare HS-transform vs. Morlet Wavelet Transform:
+![Voltage Disturbance](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/power_quality_disturbance.png)
+
+The figure showed HS-transform is able to detect the transient disturbances like notch, spike. Meanwhile, those signals from Morlet Wavelet transform are not obviously recognized.
+
+######
+
+![Real-Imag Trajectory](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/power_quality_disturbance_trajectory.png)
+We can see also different types of voltage disturbance can generate different real-imaginary trajectory in S-transform at different frequencies.
+
+### 5.2 Power System Faults
+
+![Different Faults](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/fault_current.png)
+
+As can be seen, both Wavelet and S-transform are able to detect when the fault occur (huge change in current magnitude). Wavelet transform seems more sensitive with noise with high distortion compared with HS-transform.
+
+######
+
+![Real-Imag Trajectory](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/fault_trajectory.png)
+
+We can also observe different types of faults can generate different real-imaginary trajectory in S-transform at varying levels of frequencies.
+
+## 6. Communication
+
+If you have any questions, issues, or suggestions for HS Transform, please open an issue on the GitHub repository.
+or contact email: linhvietnguyen.ee@gmail.com
+
+## 7. Citation
+
+If you use HS Transform in your research, please cite it as follows:
+Linh V Nguyen (2024). HS Transform (Version 0.1) [Computer software]. GitHub: github.com/nvlinhvn/hstransform

HSTransform-0.1.1/README.md

@@ -0,0 +1,116 @@
+# Hyperbolic S-Transform
+
+Package for Hyperbolic S-transform
+
+## 1. Introduction
+
+HS Transform is a Python package for performing Hyperbolic [S-transform](https://en.wikipedia.org/wiki/S_transform) [[1]](#1). The S-transform is a time-frequency representation that combines the best properties of the Short-time Fourier Transform and the Wavelet Transform. It provides simultaneous information on both the frequency content and temporal localization of a signal.
+
+This is a work of my [published paper](https://ieeexplore.ieee.org/document/8423487)
+
+### References
+
+<a id="1">[1]</a>
+Stockwell, R.G., Mansinha, L. & Lowe, R.P., (1996).
+Localization of the complex spectrum: the S transform.
+IEEE Trans. Signal Process., 44(4), 998–1001, doi:10.1109/78.492555
+
+## 2. Dependencies
+
+HS Transform requires the following Python packages:
+
+- numpy
+- scipy
+- pandas
+- matplotlib
+- pytest
+
+## 3. How to Install
+
+After that, you can install HS Transform using pip:
+
+```
+pip install HSTransform
+```
+
+You can also install all dependencies and package in 1 statement
+
+```
+pip install numpy scipy pandas matplotlib pytest HSTransform
+```
+
+## 4. Run tests
+
+After installation, you can test the package using the included test scripts:
+`pytest tests/`
+
+## 5. Example
+
+Here’s an example of how to use HS Transform to analyze a signal with voltage disturbance and power system fault:
+
+It's noted sometimes you need to include the installed HSTransform package location into sys
+
+```python
+import sys
+import os
+
+# Add the package directory to sys.path
+package_path = os.path.abspath('/usr/local/Caskroom/miniconda/base/envs/YOUR_ENVIRONMENT/lib/python3.10/site-packages/')
+if package_path not in sys.path:
+    sys.path.insert(0, package_path)
+
+import numpy as np
+from hstransform import HSTransform
+
+# Create input signal (for example: Voltage signal)
+t = np.linspace(0, 10, 100) # timeseries
+V_m = 220*np.sqrt(2)  # peak voltage
+f_V = 50  # frequency
+phi_V = 0  # phase
+
+V_clean = V_m * np.sin(2 * np.pi * f_V * t + phi_V)
+# Create voltage sag/dip (80% of the nominal voltage for 0.15 second)
+V_sag = np.where((t >= 2) & (t <= 3.5), 0.5 * V_clean, V_clean)
+
+# Create an instance of HSTransform
+
+hs = HSTransform()
+
+# Perform the transform
+signal = V_sag
+S_transformed = hs.fit_transform(t, signal)
+```
+
+### 5.1 Power Quality Disturbance
+
+Compare HS-transform vs. Morlet Wavelet Transform:
+![Voltage Disturbance](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/power_quality_disturbance.png)
+
+The figure showed HS-transform is able to detect the transient disturbances like notch, spike. Meanwhile, those signals from Morlet Wavelet transform are not obviously recognized.
+
+######
+
+![Real-Imag Trajectory](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/power_quality_disturbance_trajectory.png)
+We can see also different types of voltage disturbance can generate different real-imaginary trajectory in S-transform at different frequencies.
+
+### 5.2 Power System Faults
+
+![Different Faults](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/fault_current.png)
+
+As can be seen, both Wavelet and S-transform are able to detect when the fault occur (huge change in current magnitude). Wavelet transform seems more sensitive with noise with high distortion compared with HS-transform.
+
+######
+
+![Real-Imag Trajectory](https://raw.githubusercontent.com/nvlinhvn/HSTransform/main/img/fault_trajectory.png)
+
+We can also observe different types of faults can generate different real-imaginary trajectory in S-transform at varying levels of frequencies.
+
+## 6. Communication
+
+If you have any questions, issues, or suggestions for HS Transform, please open an issue on the GitHub repository.
+or contact email: linhvietnguyen.ee@gmail.com
+
+## 7. Citation
+
+If you use HS Transform in your research, please cite it as follows:
+Linh V Nguyen (2024). HS Transform (Version 0.1) [Computer software]. GitHub: github.com/nvlinhvn/hstransform

HSTransform-0.1.1/hstransform/__init__.py

@@ -0,0 +1 @@
+from .hstransform import HSTransform

HSTransform-0.1.1/hstransform/hstransform.py

@@ -0,0 +1,133 @@
+import dataclasses
+from typing import Union
+
+import numpy as np
+from scipy.fft import fft, ifft
+import pandas as pd
+
+
+@dataclasses.dataclass
+class HSTransform:
+    """
+    A class used to represent the S-transform with a hyperbolic Gaussian window.
+
+    ...
+
+    Attributes
+    ----------
+    forwardtaper : float
+        forward taper value
+    backwardtaper : float
+        backward taper value
+    curvature : float
+        curvature value
+    """
+
+    forwardtaper: float = 0.2
+    backwardtaper: float = 0.1
+    curvature: float = 312.5
+
+    def _input_validation(self, input_signal):
+        """
+        Validates the input signal.
+
+        Parameters
+        ----------
+            input_signal : np.ndarray, pd.Series, or list
+
+        Raises
+        ------
+            TypeError: If input_signal is not a numpy array, pandas Series, or list.
+            ValueError: If input_signal contains non-numerical values.
+        """
+        valid_types = (np.ndarray, pd.Series, list)
+        if not isinstance(input_signal, valid_types):
+            raise TypeError(f"input_signal must be one of the following types: {valid_types}, not {type(input_signal)}.")
+
+        input_array = np.array(input_signal)
+        if np.isnan(input_array).any():
+            raise ValueError("input_signal contains null values.")
+
+        if not np.issubdtype(input_array.dtype, np.number):
+            raise ValueError("input_signal should only contain numerical values.")
+
+    def _compute_hyperbolic_gaussian(self, l: int, n: int, time: np.ndarray) -> np.ndarray:
+        """
+        Computes the hyperbolic Gaussian window.
+
+        Parameters
+        ----------
+            l : int
+                length of the signal
+            n : int
+                frequency point
+            time : np.ndarray
+                time values of the signal
+
+        Returns
+        -------
+            g : np.ndarray
+                hyperbolic Gaussian window
+        """
+        vectorf = np.arange(0, l)
+        vectorf1 = vectorf**2
+        lambdaf = self.forwardtaper
+        lambdab = self.backwardtaper
+        lambda_val = self.curvature
+        x = (lambdaf + lambdab) * time / (2 * lambdaf * lambdab) + (lambdaf - lambdab) * np.sqrt(time**2 + lambda_val) / (2 * lambdaf * lambdab)
+        x = np.tile(x, (1, 2)).T
+        vectorf2 = -vectorf1 * x**2 / (2 * n**2)
+        g = 2 * np.abs(vectorf) * np.exp(vectorf2) / ((lambdaf + lambdab) * np.sqrt(2 * np.pi))
+        return np.sum(g)
+
+    def fit_transform(self,
+                      time_values: Union[pd.Series, np.ndarray, list],
+                      input_signal: Union[pd.Series, np.ndarray, list],
+                      minf: int = 0,
+                      fsamplingrate: int = 1) -> np.ndarray:
+        """
+        Computes the S-transform of the input signal.
+
+        Parameters
+        ----------
+            time_values : np.ndarray
+                time values of the signal
+            input_signal : np.ndarray
+                input signal
+            minf : int
+                minimum frequency point
+            fsamplingrate : int
+                frequency sampling rate
+
+        Returns
+        -------
+            S : np.ndarray
+                S-transform of the input signal
+        """
+        # Validate the input
+        self._input_validation(input_signal)
+
+        # Convert to numpy arrays if they are not array types
+        if not isinstance(time_values, np.ndarray):
+            time_values = np.array(time_values)
+        if not isinstance(input_signal, np.ndarray):
+            input_signal = np.array(input_signal)
+
+        n = len(input_signal)
+        # Make sure the max frequency to be optimized (Cover the 6th, 12th, or 18th harmonic respectively)
+        maxf = min(900, n // 2)
+
+        # Compute the fft of input
+        h = fft(input_signal)
+        h = np.concatenate((h, h))
+
+        # S output
+        s = np.zeros(((maxf - minf + 1) // fsamplingrate, n), dtype='complex')
+        s[0, :] = np.mean(input_signal) * (1 & np.arange(1, n + 1))
+
+        # Increment the frequency point
+        for k in range(fsamplingrate, maxf - minf + 1, fsamplingrate):
+            w_hy = self._compute_hyperbolic_gaussian(n, minf + k, time_values)
+            s[k // fsamplingrate, :] = ifft(h[minf + k + 1:minf + k + n+1] * w_hy)
+
+        return s

HSTransform-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

HSTransform-0.1.1/setup.py

@@ -0,0 +1,38 @@
+"""
+This is the setup module for the HSTransform package. (Beta test)
+
+S-transform with Hyperbolic Window
+Combines the best properties of the Short-time Fourier Transform 
+and the Wavelet Transform.
+"""
+
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name='HSTransform',
+    version='0.1.1',
+    url='https://github.com/nvlinhvn/HSTransform',
+    packages=find_packages(),
+    license='MIT',
+    author='Linh V Nguyen',
+    author_email='linhvietnguyen.ee@gmail.com',
+    description='A Package to Compute S-transform with Hyperbolic Window',
+    python_requires='>=3.10',
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    install_requires=[
+        'numpy>=1.21.2',
+        'scipy>=1.7.1',
+        'pandas>=1.3.3',
+        'pytest>=6.2.5'
+    ],
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3.10',
+    ],
+    test_suite='tests'
+)

HSTransform-0.1.1/tests/test_hstransform.py

@@ -0,0 +1,50 @@
+"""
+Unit Test for HS functions
+- Test Gaussian Windowed
+- Test HS-transform output
+"""
+import numpy as np
+import pytest
+from hstransform import HSTransform
+
+def test_hyperbolic_gaussian():
+    """
+    Tests aims to validate the output 
+    of Gaussian Window of a time array
+    """
+    # Create a sinusoidal signal
+    t = np.linspace(0, 1, 100)
+
+    # Compute the S-transform
+    st = HSTransform()
+
+    # Test the _compute_hyperbolic_gaussian method
+    result = st._compute_hyperbolic_gaussian(1000, 50, t)
+    assert isinstance(result, np.float64)
+
+def test_fit_transform():
+    """
+    Tests aims to validate the S-transform output 
+    - shape
+    - type 
+    - check any null
+    """
+    # Create a sinusoidal signal
+    t = np.linspace(0, 2, 100)
+    signal = np.sin(2 * np.pi * 50 * t)
+
+    # Compute the S-transform
+    st = HSTransform()
+    s_transformed = st.fit_transform(t, signal)
+
+    # Add some assertions here to test the S-transform output
+    # Dimension
+    assert s_transformed.shape == (min(900, len(signal) // 2)+1, len(signal))
+    # Type of output
+    assert isinstance(s_transformed, np.ndarray)
+    assert np.issubdtype(s_transformed.dtype, np.complexfloating)
+    # any null
+    assert not np.isnan(s_transformed).any()
+
+if __name__ == "__main__":
+    pytest.main()