WaLSAtools

WaLSAtools is designed for ease of use and accessibility. Its interactive interface guides you through the analysis process, providing clear instructions and helpful information at each step. This section demonstrates how to use WaLSAtools and highlights its key features.

Before diving into the interactive demonstration, we recommend familiarizing yourself with the various analysis methods available in WaLSAtools. You can find detailed descriptions of these methods in the Introduction section. Additionally, this page provides several Worked Examples of different analysis techniques applied to synthetic datasets (see the left menu). To learn more about its capabilities and how to apply it to your research, we encourage you to explore the WaLSAtools documentation, the associated Nature Reviews Methods Primers article, and the provided examples. If you use WaLSAtools in your work, please remember to cite it appropriately (see Citation).

The "Under the Hood" section provides details on the individual routines used for wave analysis within the WaLSAtools package, for those interested in exploring the underlying code. However, we strongly encourage all users to perform their analyses by running WaLSAtools directly, as this ensures the correct execution of the analysis workflow and provides a more user-friendly experience.

Interactive Demonstration

WaLSAtools provides an interactive interface that simplifies wave analysis. To launch the interface, simply import the WaLSAtools package and run the WaLSAtools command in a Python terminal or Jupyter notebook.

The interface will guide you through the following steps:

1. Select a category of analysis: Choose from single time series analysis or cross-correlation analysis.
2. Choose the data type: Specify the type of data you are working with (e.g., 1D signal, 3D datacube).
3. Pick a specific analysis method: Select the method most suitable for your data and research question.

The interface will then provide information on the selected method, including its calling sequence, input parameters, and expected outputs.

Here's an example of the execution of WaLSAtools in a Jupyter notebook:

1
2

from WaLSAtools import WaLSAtools
WaLSAtools

[1]

Python

© WaLSA Team (www.WaLSA.team)

---

WaLSAtools v1.0 - Wave analysis tools

Documentation: www.WaLSA.tools

GitHub repository: www.github.com/WaLSAteam/WaLSAtools

---

If you use WaLSAtools in your research, please cite:

Jafarzadeh, S., Jess, D. B., Stangalini, M. et al. 2025, Nature Reviews Methods Primers, in press

---

Choose a category, data type, and analysis method from the list below,

to get hints on the calling sequence and parameters:

Category: Select Category Single Time Series Analysis Cross-Correlation Between Two Time Series

Data Type: Select Data Type

Method: Select Method

Sub-method: Select Sub-method FFT Wavelet Lomb-Scargle Welch

Please select appropriate options from all dropdown menus.

Calling Sequence:

Parameters (**kwargs)
Parameter	Type	Description

Source code

# -----------------------------------------------------------------------------------------------------
# WaLSAtools - Wave analysis tools
# Copyright (C) 2025 WaLSA Team - Shahin Jafarzadeh et al.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
# http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# 
# Note: If you use WaLSAtools for research, please consider citing:
# Jafarzadeh, S., Jess, D. B., Stangalini, M. et al. 2025, Nature Reviews Methods Primers, in press.
# -----------------------------------------------------------------------------------------------------

import numpy as np # type: ignore
from .analysis_modules.WaLSA_speclizer import WaLSA_speclizer
from .analysis_modules.WaLSA_k_omega import WaLSA_k_omega
from .analysis_modules.WaLSA_pod import WaLSA_pod
from .analysis_modules.WaLSA_cross_spectra import WaLSA_cross_spectra
from .analysis_modules.WaLSA_interactive import interactive

class WaLSAtools:
    """
    Main class to perform spectral analysis using different methods.

    It runs interactively if called without (or empty
    and acts as a function if called with parentheses and parameters.
    """

    def __call__(self, signal=None, time=None, method=None, **kwargs):
        """
        Main function to perform spectral analysis using different methods.

        Parameters:
            signal (array): The input signal (1D, or 3D).
            time (array): The time array of the signal.
            method (str): The method to use for spectral analysis ('fft', 'lombscargle', 'k-omega', etc.)
            **kwargs: Additional parameters for data preparation and analysis methods.

        Returns:
            Results of the selected analysis method.
        """
        if signal is None and time is None and method is None:
            interactive()  # Run interactive (help) mode if no inputs are provided
            return None

        method_map = {
            'fft': WaLSA_speclizer,
            'lombscargle': WaLSA_speclizer,
            'wavelet': WaLSA_speclizer,
            'welch': WaLSA_speclizer,
            'emd': WaLSA_speclizer,
            'k-omega': WaLSA_k_omega,
            'pod': WaLSA_pod
        }

        if method not in method_map:
            raise ValueError(f"Unknown method '{method}'. Please choose from {list(method_map.keys())}.")

        func = method_map[method]

        if method in ['fft', 'lombscargle', 'wavelet', 'welch', 'emd'] and 'data1' in kwargs and 'data2' in kwargs:
            return WaLSA_cross_spectra(signal=np.ones(10), time=time, method=method, **kwargs)
        else:
            return func(signal=signal, time=time, method=method, **kwargs)

    def __repr__(self):
        """
        Custom representation to allow interactive mode when 'WaLSAtools' is typed without parentheses.
        """
        interactive()  # Call the interactive (help) function
        return ''  # Return an empty string so that no additional output is shown

# Instantiate the object so that it works like a function and runs interactively
WaLSAtools = WaLSAtools()