.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "emd_tutorials/01_sifting/emd_tutorial_01_sift_06_siftconfig.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_emd_tutorials_01_sifting_emd_tutorial_01_sift_06_siftconfig.py: SiftConfig Specification ======================== Here we look at how to customise the different parts of the sift algorithm. There are many options which can be customised from top level sift parameters all the way down to extrema detection. .. GENERATED FROM PYTHON SOURCE LINES 11-26 The SiftConfig object ^^^^^^^^^^^^^^^^^^^^^ EMD can create a config dictionary which contains all the options that can be customised for a given sift function. This can be created using the get_config function in the sift submodule. Lets import emd and create the config for a standard sift - we can view the options by calling print on the config. The SiftConfig dictionary contains all the arguments for functions that are used in the sift algorithm. - "sift" contains arguments for the high level sift functions such as ``emd.sift.sift`` or ``emd.sift.ensemble_sift`` - "imf" contains arguments for ``emd.sift.get_next_imf`` - "envelope" contains arguments for ``emd.sift.interpolate_envelope`` - "extrema", "mag_pad" and "loc_pad" have arguments for extrema detection and padding .. GENERATED FROM PYTHON SOURCE LINES 26-35 .. code-block:: Python # sphinx_gallery_thumbnail_path = '_static/emd_siftconfig_thumb.png' import emd import numpy as np config = emd.sift.get_config('sift') print(config) .. rst-class:: sphx-glr-script-out .. code-block:: none sift sift_thresh : 1e-08 energy_thresh : 50 rilling_thresh : None max_imfs : None verbose : None return_residual : True imf_opts: env_step_size : 1 max_iters : 1000 energy_thresh : 50 stop_method : sd sd_thresh : 0.1 rilling_thresh : (0.05, 0.5, 0.05) envelope_opts: interp_method : splrep extrema_opts: pad_width : 2 parabolic_extrema : False method : rilling mag_pad_opts : {'mode': 'median', 'stat_length': 1} loc_pad_opts : {'mode': 'reflect', 'reflect_type': 'odd'} .. GENERATED FROM PYTHON SOURCE LINES 36-37 These arguments are specific for the each type of sift (particularly at the top "sift" level). .. GENERATED FROM PYTHON SOURCE LINES 37-41 .. code-block:: Python config = emd.sift.get_config('complete_ensemble_sift') print(config) .. rst-class:: sphx-glr-script-out .. code-block:: none complete_ensemble_sift nensembles : 4 ensemble_noise : 0.2 nprocesses : 1 noise_seed : None sift_thresh : 1e-08 energy_thresh : 50 rilling_thresh : None max_imfs : None verbose : None imf_opts: env_step_size : 1 max_iters : 1000 energy_thresh : 50 stop_method : sd sd_thresh : 0.1 rilling_thresh : (0.05, 0.5, 0.05) envelope_opts: interp_method : splrep extrema_opts: pad_width : 2 parabolic_extrema : False method : rilling mag_pad_opts : {'mode': 'median', 'stat_length': 1} loc_pad_opts : {'mode': 'reflect', 'reflect_type': 'odd'} .. GENERATED FROM PYTHON SOURCE LINES 42-56 The SiftConfig dictionary contains arguments and default values for functions which are called internally within the different sift implementations. The dictionary can be used for viewing and editing the options before they are passed into the sift function. The SiftConfig dictionary is nested, in that some items in the dictionary store further dictionaries of options. This hierarchy of options reflects where the options are used in the sift process. The top-level of the dictionary contains arguments which may be passed directly to the sift functions, whilst options needed for internal function calls are stored in nested subdictionaries. The parameters in the config can be changed in the same way we would change the key-value pairs in a nested dictionary or using a h5py inspiried shorthand. .. GENERATED FROM PYTHON SOURCE LINES 56-72 .. code-block:: Python # This is a top-level argument used directly by ensemble_sift config['nensembles'] = 20 config['nprocesses'] = 4 config['max_imfs'] = 5 # This is a sub-arguemnt used by interp_envelope, which is called within # ensemble_sift. # Standard config['extrema_opts']['pad_width'] = 4 # Shorthard config['extrema_opts/pad_width'] = 4 print(config) .. rst-class:: sphx-glr-script-out .. code-block:: none complete_ensemble_sift nensembles : 20 ensemble_noise : 0.2 nprocesses : 4 noise_seed : None sift_thresh : 1e-08 energy_thresh : 50 rilling_thresh : None max_imfs : 5 verbose : None imf_opts: env_step_size : 1 max_iters : 1000 energy_thresh : 50 stop_method : sd sd_thresh : 0.1 rilling_thresh : (0.05, 0.5, 0.05) envelope_opts: interp_method : splrep extrema_opts: pad_width : 4 parabolic_extrema : False method : rilling mag_pad_opts : {'mode': 'median', 'stat_length': 1} loc_pad_opts : {'mode': 'reflect', 'reflect_type': 'odd'} .. GENERATED FROM PYTHON SOURCE LINES 73-74 This nested shorthand can be used to customise the low level extrema padding options .. GENERATED FROM PYTHON SOURCE LINES 74-90 .. code-block:: Python # Standard #config['extrema_opts']['loc_pad_opts']['reflect_type'] = 'even' # Shorthand config['extrema_opts/mag_pad_opts/stat_length'] = 3 config['extrema_opts'] = {} print(config) # This nested structure is passed as an unpacked dictionary to our sift function. # Create some random data x = np.random.randn(1000,) imf = emd.sift.complete_ensemble_sift(x, **config) .. rst-class:: sphx-glr-script-out .. code-block:: none complete_ensemble_sift nensembles : 20 ensemble_noise : 0.2 nprocesses : 4 noise_seed : None sift_thresh : 1e-08 energy_thresh : 50 rilling_thresh : None max_imfs : 5 verbose : None imf_opts: env_step_size : 1 max_iters : 1000 energy_thresh : 50 stop_method : sd sd_thresh : 0.1 rilling_thresh : (0.05, 0.5, 0.05) envelope_opts: interp_method : splrep extrema_opts: .. GENERATED FROM PYTHON SOURCE LINES 91-103 Customised sifting with functools.partial ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you are going to be repeatedly calling a sift function with the same arguments many times, you could consider creating a partial function to simplify the code. Partial functions are a part of the ``functools`` module in python. They act like normal functions but with fixed values for certain arguments. This means we could specify our sift config and use it to create a partial function which only needs the data to be passed in as an argument. For example: .. GENERATED FROM PYTHON SOURCE LINES 103-118 .. code-block:: Python # Create a mask sift config object and customise some options config = emd.sift.get_config('mask_sift') config['max_imfs'] = 5 config['mask_amp_mode'] = 'ratio_sig' config['envelope_opts/interp_method'] = 'mono_pchip' # Create a partial function - my_mask_sift is now a function with the arguments # in config fixed as defaults. from functools import partial my_mask_sift = partial(emd.sift.mask_sift, **config) # my_mask_sift can then be called with the input data as the only argument. imfs = my_mask_sift(x) .. GENERATED FROM PYTHON SOURCE LINES 119-122 We can compare the different options for ``emd.sift.mask_sift`` and ``my_mask_sift`` using the python inspect module to print the default arguments (or function signature) for each function. .. GENERATED FROM PYTHON SOURCE LINES 122-130 .. code-block:: Python import inspect print('emd.sift.mask_sift') print(inspect.signature(emd.sift.mask_sift)) print() print('my_mask_sift') print(inspect.signature(my_mask_sift)) .. rst-class:: sphx-glr-script-out .. code-block:: none emd.sift.mask_sift (X, mask_amp=1, mask_amp_mode='ratio_sig', mask_freqs='zc', mask_step_factor=2, ret_mask_freq=False, max_imfs=9, sift_thresh=1e-08, nphases=4, nprocesses=1, verbose=None, imf_opts=None, envelope_opts=None, extrema_opts=None) my_mask_sift (X, *, mask_amp=1, mask_amp_mode='ratio_sig', mask_freqs='zc', mask_step_factor=2, ret_mask_freq=False, max_imfs=5, sift_thresh=1e-08, nphases=4, nprocesses=1, verbose=None, imf_opts={'env_step_size': 1, 'max_iters': 1000, 'energy_thresh': 50, 'stop_method': 'sd', 'sd_thresh': 0.1, 'rilling_thresh': (0.05, 0.5, 0.05)}, envelope_opts={'interp_method': 'mono_pchip'}, extrema_opts={'pad_width': 2, 'parabolic_extrema': False, 'method': 'rilling', 'mag_pad_opts': {'mode': 'median', 'stat_length': 1}, 'loc_pad_opts': {'mode': 'reflect', 'reflect_type': 'odd'}}) .. GENERATED FROM PYTHON SOURCE LINES 131-134 We can see that the input arguments in the signature of ``my_mask_sift`` contains all the specified options from the ``config`` so is much longer than for ``emd.sift.mask_sift``. .. GENERATED FROM PYTHON SOURCE LINES 136-153 Saving and loading sift config files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We might often want to store, reuse and share sift configurations during a project. To help with this, a SiftConfig specification can be stored as a raw text file in the YAML format. The config can be saved into a text file and loaded back into a SiftConfig object for use in a script. We can also directly edit the text file to customise the sift parameters from there if preferred. The save and load operations are performed by ``emd.sift.SiftConfig.to_yaml_file`` and ``emd.sift.SiftConfig.from_yaml_file`` respectively. Lets look at an example. We're going to store this config in a temporary file on your system for this tutorial. This avoids clutter and should work on all systems. If you would prefer to use a specific file on your system please comment out this section and simply specify ``config_file`` to be a path to the file of your choice. .. GENERATED FROM PYTHON SOURCE LINES 153-170 .. code-block:: Python # Create a temporary file OR specify your own file path import tempfile config_file = tempfile.NamedTemporaryFile(prefix="ExampleSiftConfig_").name # Or uncomment the following line and specify your own file #config_file = '/path/to/my/file' # Save the config into yaml format config.to_yaml_file(config_file) # Open the text file and print its contents with open(config_file, 'r') as f: txt = f.read() print(txt) # Load the config back into a SiftConfig object for use in a script new_config = emd.sift.SiftConfig.from_yaml_file(config_file) .. rst-class:: sphx-glr-script-out .. code-block:: none sift_type: mask_sift --- mask_amp: 1 mask_amp_mode: ratio_sig mask_freqs: zc mask_step_factor: 2 ret_mask_freq: false max_imfs: 5 sift_thresh: 1.0e-08 nphases: 4 nprocesses: 1 verbose: null imf_opts: env_step_size: 1 max_iters: 1000 energy_thresh: 50 stop_method: sd sd_thresh: 0.1 rilling_thresh: - 0.05 - 0.5 - 0.05 envelope_opts: interp_method: mono_pchip extrema_opts: pad_width: 2 parabolic_extrema: false method: rilling mag_pad_opts: mode: median stat_length: 1 loc_pad_opts: mode: reflect reflect_type: odd .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.656 seconds) .. _sphx_glr_download_emd_tutorials_01_sifting_emd_tutorial_01_sift_06_siftconfig.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: emd_tutorial_01_sift_06_siftconfig.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: emd_tutorial_01_sift_06_siftconfig.py ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_