Skip to content

Plot

This page discusses aspects of the plot-module of parrot.

After processing the data with the process module, a single Python dictionary called data is returned. This dictionary contains general metadata about the dataset, such as the number of traces, but also the data itself, specifically each sliced & averaged individual trace, as well as averaged traces in the time and frequency domains.

The plot module currently supports two different functions that can work with data.

# Simple Plot giving an overview of the data
parrot.plot.simple_multi_cycle(data)
plt.savefig("Simple_plot.png", dpi=600)
# Extended plot, showing increase in dynamic range and standard deviation in time domain
parrot.plot.extended_multi_cycle(data)
plt.savefig("Extended_plot.png", dpi=600)

Both are discussed in detail in the following sections:

Simple multi cycle

def simple_multi_cycle(data,
                       min_THz_frequency=0e12,
                       max_THz_frequency=10e12,
                       threshold_dB=10,
                       figsize=None,
                       water_absorption_lines=True,
                       debug=False):

Creates three subplots showing the averaged THz trace in both the time and frequency domains along with the measured dark traces. For the frequency domain, two perspectives are given, one on a normalized linear scale and one on a logarithmic scale. Additional information is given in the title of the figure as well as in the plots, consisting of the signal-to-noise ratio (SNR) in the time domain, the dynamic range in the frequency domain as well as two different bandwidths, full-width at half-maximum (FWHM) and a bandwidth on a logarithmic scale depending on threshold_dB. The input parameters of simple_multi_cycle() are discussed below.

min_THz_frequency, max_THz_frequency

Input: float. When reading the data, the sampling rate is checked and, if filter_signal=True in process.run(), the maximum displayable internal THz frequency is typically limited to 50 THz, which should be sufficient for most THz experiments. (It can, of course, be adjusted in the process module if an even higher THz frequency is required).

However, this large frequency is not very suitable for display purposes. For this reason, the min. and max. THz frequency are further restricted for plotting the data. The default settings of simple_multi_cycle() set these to 0 THz and 10 THz.

threshold_dB

Input: float. 🦜 tries to give an estimate of the received THz pulse by analyzing the full width at half maximum (FWHM) and the bandwidth of the spectrum on a logarithmic scale. Since there is no official definition for a logarithmic bandwidth and the definition of the signal hitting the noise floor can often be arbitrary in time (due to the fluctuations of the noise floor itself), a threshold of 10 dB is set as a standard parameter. This means that the largest frequency bandwidth of the THz signal that is at least 10 dB above the noise floor is selected. Any dip in the signal or peak in the noise floor at a given frequency will interrupt the bandwidth. Only the largest continuous portion of the THz signal above the specified threshold is selected.

While the linear FWHM bandwidth is suitable for nonlinear THz spectroscopy (because the frequencies covered by this bandwidth should have the relatively highest amplitude to induce nonlinear effects), the logarithmic bandwidth with a 10 dB threshold is suitable for linear THz spectroscopy. Programs such as phoeniks offer to extract the refractive index and absorption coefficient from (averaged) THz time-domain data of a reference and sample measurement. The algorithms are typically stable enough to extract the relative information when the signal is 10 dB above the noise floor.

figsize

Input: None or (float, float). This parameter is used as a shortcut to get suitable plots in the right size directly. For example, if you are characterizing your THz source and/or detection scheme and want to tell others about it at the next meeting, you can specify a figsize here that will scale the plot to the dimensions you need, e.g. for a presentation. You have to give the width and height as a tuple and the unit is unfortunately in inches. However, you can get the appropriate dimension in [cm] by dividing the input by 2.54.

For example:

simple_multi_cycle(data, figsize=(30 / 2.54, 18 / 2.54))
plt.savefig("Plot.png", dpi=600)  # Saves the plot in the current working directory

water_absorption_lines

Input: bool. For convenience, the water absorption lines at THz frequencies can be enabled or disabled and are extracted from the HITRAN online database using HAPI.

Reference

R.V. Kochanov, I.E. Gordon, L.S. Rothman, P. Wcislo, C. Hill, J.S. Wilzewski,

HITRAN Application Programming Interface (HAPI): A comprehensive approach to working with spectroscopic data,

J. Quant. Spectrosc. Radiat. Transfer 177, 15-30 (2016)

https://hitran.org/hapi/

debug

Input: bool. For debugging purposes.

Extended multi cycle

def extended_multi_cycle(data,
                         min_THz_frequency=0e12,
                         max_THz_frequency=10e12,
                         threshold_dB=10,
                         figsize=None,
                         snr_timedomain=False,
                         water_absorption_lines=True):

Creates three subplots that provide more information, particularly regarding the averaging effect of using an ensemble of individual traces. The plot consists of the time domain trace as before, a frequency domain trace, and a plot that shows the dynamic range for a cumulative average of the light trace versus the averaged dark trace. Ideally, this double-log plot should show a line. Due to nonstationary noise or other drifts in the setup, the dynamic range can become saturated or even degraded as more individual traces are averaged.

snr_timedomain

Input: bool. Enables/disables whether to calculate and display the signal-to-noise ratio (SNR) in time domain.

min_THz_frequency, max_THz_frequency, threshold_dB, figsize, water_absorption_lines

See description at Simple multi cycle.