



Satis documentation

 [Satis

 ![Logo](_static/logo_satis.png)](#)

 stable

 

Contents:

* [Welcome to Satis](index.html#document-readme_copy)

* [Acknowledgements](index.html#acknowledgements)

* [Analyze temporal signals with Satis](index.html#document-tuto_temporal_analysis)

* [satis package](index.html#document-api/satis)

[Satis](#)

* »

* Satis documentation

* [Edit on GitLab](https://gitlab.com/cerfacs/satis/blob/50c3c4b033541316d1a2cf539d0fb11bd5b6cc61/docs/index)

---

Welcome to Satis’s documentation![](#welcome-to-satis-s-documentation "Permalink to this headline")

====================================================================================================

Welcome to Satis[](#welcome-to-satis "Permalink to this headline")

-------------------------------------------------------------------

![https://cerfacs.fr/coop/images/satis/logo_satis.png](https://cerfacs.fr/coop/images/satis/logo_satis.png)logo

*Spectral Analysis for TImes Signals.*

Satis is a python3 / scipy implementation of the Fourier Spectrums in Amplitude ans Power Spectral Density.

It is particularly suited for CFD signals with the following characteristics:

* Short sampling time,

* Potentially short recording time,

* Low signal-to-noise ratio,

* Multiple measures available.

### Installation[](#installation "Permalink to this headline")

The package is available on [PyPI](https://pypi.org/) so you can install it using pip:

```

pip install satis

```

### How to use it[](#how-to-use-it "Permalink to this headline")

```

(my_env)rossi@pluto:~>satis

Usage: satis [OPTIONS] COMMAND [ARGS]...

  ---------------   SATIS  --------------------

  You are now using the Command line interface of Satis, a simple tool for

  spectral analysis optimized to signals from CFD, created at CERFACS

  (https://cerfacs.fr).

  This is a python package currently installed in your python environment.

Options:

  --help  Show this message and exit.

Commands:

  datasetforbeginners  Copy a set of signals to train using Satis.

  fourierconvergence   Plot discrete Fourier transform of the complete...

  fouriervariability   Plot the Fourier variability diagnostic results.

  psdconvergence       Plot the PSD convergence diagnostic results.

  psdvariability       Plot the spectral energy at the target frequency.

  time                 Plot the temporal signal and its time-average.

```

Several command lines are available on satis. You can display them running the command `satis --help`.

#### Dataset for beginners[](#dataset-for-beginners "Permalink to this headline")

```

satis datasetforbeginners

```

With this command , you can copy in your local directory a file `my\_first\_dataset.dat` to start using satis. It contains several signals of a CFD simulation. These signals have been recorded at different locations to create an average signal less sensitive to noise. For your first time with satis, we recommand to do the following diagnostics in the order with `my\_first\_dataset.dat`.

#### Time[](#time "Permalink to this headline")

```

satis time my_first_dataset.dat

```

This diagnostic plots a time graph of your signals. This plot aims at showing you if the average signal is well converged or if there is a transient behavior. To delete a transient behavior, you can add at the end of the diagnostic command `-t \*starting\_time\*` to declare the beginning of the converged behavior.

If a periodic pattern is visible, you should calculate its frequency and declare it with `-f \*calculated\_frequency\*`

There is also a cumulative time-average. If this curve is not almost flat, you did probably not remove enough transient behavior.

![https://cerfacs.fr/coop/images/satis/time.png](https://cerfacs.fr/coop/images/satis/time.png)time diagnostic

#### Fourier variability[](#fourier-variability "Permalink to this headline")

```

satis fouriervariability my_first_dataset.dat -t 0.201 -f 560

```

In this diagnostic, the Fourier coefficients of each signal at the specified frequency is plotted so that you can check the signals are equivalent. If a signal seems have different characteristics to the others, you should think about removing it. The average signal would be cleaner. To do so, declare the subset of signals you want to use with: `--subset 1 3 14 ...`

![https://cerfacs.fr/coop/images/satis/fouriervariability.png](https://cerfacs.fr/coop/images/satis/fouriervariability.png)fourier variability diagnostic

#### Fourier convergence[](#fourier-convergence "Permalink to this headline")

```

satis fourierconvergence my_first_dataset.dat -t 0.201 -f 560

```

Since this diagnostic is based on the average signal, the user should have checked beforehand that all input signals are equivalent thanks to the `fouriervariability` diagnostic.

The top plots show the amplitude of the Discrete Fourier Transform performed on the complete average signal, the last “half” of the signal and the last “quarter” of the signal.

The bottom plots show the convergence over increasing time of the amplitude and phase of the signal at the specified frequency.

![https://cerfacs.fr/coop/images/satis/fourierconvergence.png](https://cerfacs.fr/coop/images/satis/fourierconvergence.png)fourier convergence diagnostic

#### PSD variability[](#psd-variability "Permalink to this headline")

```

satis psdvariability my_first_dataset.dat -t 0.201 -f 560

```

This diagnostic shows the distribution of the spectral energy of fluctuations on the target

frequency, its first and second harmonic and the rest of the frequencies.

Note that this distribution is related to the fluctuations and that the time-average has

been removed from the signal.

![https://cerfacs.fr/coop/images/satis/psdvariability.png](https://cerfacs.fr/coop/images/satis/psdvariability.png)psd variability diagnostic

#### PSD convergence[](#psd-convergence "Permalink to this headline")

```

satis psdconvergence my_first_dataset.dat -t 0.201 -f 560

```

Just as the Fourier convergence, the PSD convergence diagnostic shows the Power

Spectral Density obtained on the complete signal, the last half and the last quarter. The left

uses a standard linear scale while the right plot shows the same result with log scales.

![psd convergence diagnostic]https://cerfacs.fr/coop/images/satis/psdconvergence.png)

### Satis as a package[](#satis-as-a-package "Permalink to this headline")

Of course, you can use satis in your own project importing it as a package:

```

import os 

import glob

import satis

import matplotlib.pyplot as plt

\*you awesome code\*

time, signals = satis.read\_signal('your\_dataset.dat')

clean\_time = satis.define\_good\_time\_array(time, signals)

clean\_signals = satis.interpolate\_signals(time, signals, clean\_time)

new\_time, new\_signals = satis.get\_clean\_signals(clean\_time, signals, 

												calculated\_frequency)

plt.plot(new\_time, new\_signals)

fourier = satis.get\_coeff\_fourier(new\_time, new\_signals,

									calculated\_frequency)

\*your awesome code

```

Acknowledgements[](#acknowledgements "Permalink to this headline")

-------------------------------------------------------------------

This package is the result of work done at Cerfacs’s COOP Team.

The contributors of this project are:

* Franchine Ni

* Antoine Dauptain

* Tamon Nakano

* Matthieu Rossi

Analyze temporal signals with Satis[](#analyze-temporal-signals-with-satis "Permalink to this headline")

---------------------------------------------------------------------------------------------------------

### Introduction[](#introduction "Permalink to this headline")

Analyzing a temporal signal may seem a staightforward task. However, when you dive into this topic, several question may arise:

* What is the mean value of my signal?

* Does my signal capture all the frequencies of interest?

* If this signal is the result of a simulation,

	+ is my signal well discretized?

	+ is my signal periodic?

	+ what is the spectral power of my signal?

	+ …

A canonical example of what we want to discuss here should be the following one:

![_images/mean_pitfalls.png](_images/mean_pitfalls.png)Mean pitfalls

In this graph we have a sinus-shaped signal (blue curve). What is the mean value of this signal?

> 

> Well, it seems to be 0…

> 

> 

> 

Ok, let’s keep this value in mind.

Imagine the signal is the result of a very complex numerical simulation and your time record makes the signal has been discretized at different time steps (black crosses). If we want to calculate the mean value of our signal, the ingenuous mind would calculate:

![_images/classical_mean.png](_images/classical_mean.png)Classical mean

Doing so, one would get a mean value of approximatively 0.35.

> 

> Yes, but obviously the signal is poorly discretized!

> 

> 

> 

Alright, if one had the same finite signal discretized at high frequency, averaging over the time record the value of the signal (to get close to the integral of the blue curve), one would have get a mean value of approx. 0.22.

> 

> …

> 

> 

> 

The point of this example is to highlight the need to be aware of some traps in signal analysis. Cleaning up the signal before doing any calculation is a good practice. Hopefully, Satis provides a module named `temporal\_analysis\_tool` full of functions to help you avoiding these traps (see more information about Satis [here](https://cerfacs.fr/coop/satis).

### Temporal\_analysis\_tool[](#temporal-analysis-tool "Permalink to this headline")

Hereafter are detailed the functions you can find in the module `temporal\_analysis\_tool` plus how to use them. Generally, you will have to get your signal and put it in a time array and signal array:

```

record = numpy.genfromtxt("my\_record.dat")

time = record[:,0]

signal = record[:,1]

```

#### resample\_signal[](#resample-signal "Permalink to this headline")

Resample the initial signal at a constant time interval.

```

rescaled\_time, rescaled\_signal = resample\_signal(time, 

												 signal, 

												 dtime=0.01)

```

**NB:** If a dtime is given, the interpolation is made to have a signal with a time interval of dtime. Else, the dt is the smallest time interval between

two values of the signal.

#### calc\_autocorrelation\_time[](#calc-autocorrelation-time "Permalink to this headline")

Estimate the autocorrelation time at a given threshold.

The idea is: if you have a finite time record, you can always refine your signal, but at some point, you will not add any further information getting more points. This function returns the first time at which the signal is correlated **under** the threshold.

```

auto\_time = calc\_autocorrelation\_time(time, signal, threshold=0.2)

```

#### sort\_spectral\_power[](#sort-spectral-power "Permalink to this headline")

Determine the harmonic power contribution of the signal.

It calculates the Power Spectral Density (PSD) of the complete signal and of a downsampled version of the signal. The difference of the two PSD contains only harmonic components.

```

harmonic\_power, total\_power = sort\_spectral\_power(time, signal)

```

#### power\_representative\_frequency[](#power-representative-frequency "Permalink to this headline")

Calculate the frequency that captures a level of spectral power.

It calculates the cumulative power spectral density and returns the frequency that reaches the threshold in percent of spectral power.

```

threshold\_frequency = power\_representative\_frequency(time, 

												     signal,

												     threshold=0.8)

```

#### duration\_for\_uncertainty[](#duration-for-uncertainty "Permalink to this headline")

Give a suggestion of simulation duration to get an confidence interval range (around the mean) of the target value with a certain level of confidence.

This calculation is based on the Central Limit Theorem (CLT). It supposes several assumptions detailed in this [notebook](https://gitlab.com/cerfacs/notebooks/-/blob/master/spectral_analysis/Mean_convergence.ipynb).

```

duration = duration\_for\_uncertainty(time, 

									signal, 

									target=10, 

									confidence=0.95)

```

#### uncertainty\_from\_duration[](#uncertainty-from-duration "Permalink to this headline")

Give a confidence interval range given the time step, the standard deviation, the duration and the level of confidence.

```

range = uncertainty\_from\_duration(dtime, 

								  sigma,

								  duration,

								  confidence=0.95)

```

#### calculate\_std[](#calculate-std "Permalink to this headline")

Give the standard deviation of a signal at a given frequency.

```

std = calculate\_std(time, signal, frequency)

```

#### power\_spectral\_density[](#power-spectral-density "Permalink to this headline")

Automate the computation of the Power Spectral Density of a signal.

```

frequency, psd = power\_spectral\_density(time, signal)

```

satis package[](#satis-package "Permalink to this headline")

-------------------------------------------------------------

### Submodules[](#submodules "Permalink to this headline")

### satis.avbp2global module[](#satis-avbp2global-module "Permalink to this headline")

### satis.avbp2global\_compute\_ftf module[](#satis-avbp2global-compute-ftf-module "Permalink to this headline")

### satis.avbp2global\_diagnostics module[](#satis-avbp2global-diagnostics-module "Permalink to this headline")

### satis.avbp2global\_read\_inputs module[](#satis-avbp2global-read-inputs-module "Permalink to this headline")

### satis.cerfacs\_plot module[](#satis-cerfacs-plot-module "Permalink to this headline")

### satis.cli module[](#satis-cli-module "Permalink to this headline")

### satis.io module[](#satis-io-module "Permalink to this headline")

### satis.satis\_library module[](#satis-satis-library-module "Permalink to this headline")

### satis.temporal\_analysis\_tool module[](#satis-temporal-analysis-tool-module "Permalink to this headline")

Indices and tables[](#indices-and-tables "Permalink to this headline")

=======================================================================

* [Index](genindex.html)

* [Module Index](py-modindex.html)

* [Search Page](search.html)

