uwacan._core.time_frame_settings#

time_frame_settings(duration=None, step=None, overlap=None, resolution=None, num_frames=None, signal_length=None, samplerate=None)[source]#

Calculate time frame overlap settings from various input parameters.

Parameters:
durationfloat

How long each frame is, in seconds

stepfloat

The time between frame starts, in seconds

overlapfloat

How much overlap there is between the frames, as a fraction of the duration. If this is negative the frames will have extra space between them.

resolutionfloat

Desired frequency resolution in Hz. Equals 1/duration

num_framesint

The total number of frames in the signal

signal_lengthfloat, optional

The total length of the signal, in seconds

sampleratefloat, optional

The samplerate of the signal, in Hz. Only used to compute sample versions of the outputs.

Returns:
settingsdict
The settings dict has keys:

"duration", "step", "overlap", "resolution"

and if signal_length was given:

"num_frames", "signal_length"

and if samplerate was given:

"samples_per_frame", "sample_step", "sample_overlap"

and if both samplerate and signal_length was given:

"sample_total"

Raises:
ValueError

If the inputs are not sufficient to determine the frame, or if priorities cannot be disambiguated.

Notes

The parameters will be used in the following priority:

  1. signal_length and num_frames

  2. step and duration

  3. resolution and overlap

Each frame idx=[0, ..., num_frames - 1] has:

start = idx * step
stop = idx * step + duration

The last frame thus ends at (num_frames - 1) step + duration. The overlap relations are:

duration = step / (1 - overlap)
step = duration (1 - overlap)
overlap = 1 - step / duration

If both resolution and overlap are given, they will be treated as “minimum” parameters. This means that the output will have at least an overlap as specified (overlap_out >= overlap_in) and at least the specified spectral resolution (resolution_out <= resolution_in). If the other input parameters are sufficient to fully determine the frame settings, the output will be checked to meet the requested resolution and overlap criteria. The overlap will default to a minimum of 0 if not given, i.e. frames that are edge to edge (unless more overlap is required from other parameters).

This gives us the following total list of priorities:

  1. signal_length and num_frames are given

    1. step or duration (not both!) given

    2. resolution is given

    3. overlap is given

  2. step and duration given

  3. step given

    1. resolution is given

    2. overlap is given

  4. duration given (resolution is ignored, overlap is used)

  5. resolution given

For cases 2-5, num_frames is calculated if signal_length is given, and a new truncated signal_length is returned.

If a samplerate was given, the number of samples in an output is also computed. This is done with:

samples_per_frame = ceil(duration * samplerate)
sample_step = floor(step * samplerate)
sample_overlap = samples_per_frame - sample_step

We use ceil for the duration since it is often chosen to obtain a minimum frequency resolution. We use floor for the step to make sure we fit all the frames in the total length. Note that this means that the sample overlap might not equal round(duration * overlap * samplerate), due to how the rounding is done. It can at most be two samples larger than the rounded value.