Python Wrapper for Hilbert–Huang Transform MATLAB Package

HHTpywrapper instantaneously tracks frequency and amplitude variations of a signal generated by non-stationary and nonlinear processes (e.g., quasi-periodic oscillations of astronomical objects). It uses Python as an interface to call the Hilbert–Huang Transform (HHT) MATLAB package. HHT is a time-frequency analysis method to adaptively decompose a signal into basis components at different timescales (i.e., the empirical mode decomposition), and then Hilbert transform these components into instantaneous phases, frequencies and amplitudes as functions of time (i.e., Hilbert spectral analysis). HHT has been successfully applied to analyzing X-ray quasi-periodic oscillations from the active galactic nucleus RE J1034+396 (Hu et al. 2014) and two black hole X-ray binaries, XTE J1550–564 (Su et al. 2015) and GX 339-4 (Su et al. 2017). HHTpywrapper provides examples of reproducing HHT analysis results in Su et al. (2015) and Su et al. (2017). This project is originated from the Astro Hack Week 2015.

Requirements

Linux or Windows operating system (The fast EEMD code in the HHT MATLAB package has not supported Mac yet)
Python 3.x+
MATLAB
Numpy
Scipy
Astropy
Matplotlib
pymatbridge (A simple Python => MATLAB(R) interface and a matlab magic for ipython)
pyunpack and patool (For extracting the .zip/.rar HHT MATLAB package files)
UNZIP and UNRAR (sudo apt-get install unzip unrar)

Installation

Clone this project from GitHub:

 $ git clone https://github.com/HHTpy/HHTpywrapper.git

In the project directory, install required packages:
```
 $ pip install -r requirements.txt
```
In the project directory, execute:
```
 $ python setup.py install
```

Examples of Package Usage

Example of reproducing HHT analysis results in Su et al. 2015
Example of reproducing HHT analysis results in Su et al. 2017
Example of characterizing intermittency of an intermittent, frequency varying oscillation (To be added)

Directory Structure

After finishing the installation, you can see the below directory structure:

/Your Python site-packages path/hhtpywrapper/ :

This is the root directory of the package, including the directory of HHT MATLAB package and the Python API for calling the MATLAB package (eemd.py and hsa.py).
/Your Python site-packages path/hhtpywrapper/HHT_MATLAB_package/ :

This is the base directory of HHT MATLAB package. There are three subdirectories: EEMD, checkIMFs and HSA.
/Your Python site-packages path/hhtpywrapper/HHT_MATLAB_package/EEMD/ :

This directory collects MATLAB M-files for decomposing a signal into basis components (intrinsic mode functions, IMFs) defined by the signal itself. This adaptive decomposition method is called empirical mode decomposition (EMD). The M-files accomplished the most recently developed modified version of EMD, fast complementary ensemble empirical mode decomposition (CEEMD). Reference:
/Your Python site-packages path/hhtpywrapper/HHT_MATLAB_package/checkIMFs/ :

This directory collects MATLAB M-files for checking IMF properties, including significance, index of orthogonality, and excessive extrema value. Reference:
/Your Python site-packages path/hhtpywrapper/HHT_MATLAB_package/HSA/ :

This directory collects MATLAB M-files for calculating instantaneous amplitudes, phases and frequencies of IMFs (that is, the Hilbert Spectral Analysis, HSA). Reference:
- The empirical mode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis
- On instantaneous frequency

Important Links

Other HHT-related Python Codes

PyHHT ; PyHHT’s documentation (by Jaidev Deshpande)
pyeemd (by Perttu Luukko)
Python implementation of EMD/EEMD (by Dawid Laszuk)

Authors

Yi-Hao Su (yhsu@astro.ncu.edu.tw) <br> HHTpywrapper is my project during the Astro Hack Week 2015. It is currently in development phase. Welcome any contributions and feedbacks!

HHTpywrapper

Install / Use

README