spectrogram module

Classes for spectral analysis.

class spectrogram.LinearTimeSpectrogram(data, time_axis, freq_axis, start, end, t_init=None, t_delt=None, t_label='Time', f_label='Frequency', content='', instruments=None)

Bases: spectrogram.Spectrogram

Spectrogram evenly sampled in time.

Parameters

t_delt (float) – difference between the items on the time axis.

COPY_PROPERTIES = [('time_axis', 1), ('freq_axis', 1), ('instruments', 1), ('start', 0), ('end', 0), ('t_label', 0), ('f_label', 0), ('content', 0), ('t_init', 0), ('t_delt', 0)]

JOIN_REPEAT = <object object>

check_linearity(err=None, err_factor=None)

Check linearity of time axis. If err is given, tolerate absolute derivation from average delta up to err. If err_factor is given,tolerate up to err_factor * average_delta. If both are given, TypeError is raised. Default to err=0.

Parameters

• err (float) – Absolute difference each delta is allowed to diverge from the average. Cannot be used in combination with err_factor.

• err_factor (float) – Relative difference each delta is allowed to diverge from the average, i.e. err_factor * average. Cannot be used in combination with err.

classmethod combine_frequencies(specs)

Return new spectrogram that contains frequencies from all the spectrograms in spec. Only returns time intersection of all of them.

Parameters

spec (list) – List of spectrograms of which to combine the frequencies into one.

in_interval(start=None, end=None)

Return part of spectrogram that lies in [start, end).

Parameters

• start (None or datetime.datetime or sunpy.time.parse_time) – compatible string or time string Start time of the part of the spectrogram that is returned. If the measurement only spans over one day, a colon separated string representing the time can be passed.

• end (None or datetime.datetime or sunpy.time.parse_time) – compatible string or time string See start.

static intersect_time(specs)

Return slice of spectrograms that is present in all of the ones passed.

Parameters

specs (list) – List of spectrograms of which to find the time intersections.

classmethod join_many(specs, mk_arr=None, nonlinear=False, maxgap=0, fill=<object object>)

Produce new Spectrogram that contains spectrograms joined together in time.

Parameters

• specs (list) – List of spectrograms to join together in time.

• nonlinear (bool) – If True, leave out gaps between spectrograms. Else, fill them with the value specified in fill.

• maxgap (float, int or None) – Largest gap to allow in second. If None, allow gap of arbitrary size.

• fill (float or int) – Value to fill missing values (assuming nonlinear=False) with. Can be LinearTimeSpectrogram.JOIN_REPEAT to repeat the values for the time just before the gap.

• mk_array (function) – Function that is called to create the resulting array. Can be set to LinearTimeSpectrogram.memap(filename) to create a memory mapped result array.

static make_array(shape, dtype=dtype('float32'))

Function to create an array with shape and dtype.

Parameters

• shape (tuple) – shape of the array to create.

• dtype (numpy.dtype) – data-type of the array to create.

static memmap(filename)

Return function that takes shape and dtype and returns a memory mapped array.

Parameters

filename (str) – File to store the memory mapped array in.

resample_time(new_delt)

Rescale image so that the difference in time between pixels is new_delt seconds.

Parameters

new_delt (float) – New delta between consecutive values.

time_to_x(time)

Return x-coordinate in spectrogram that corresponds to the passed datetime value.

Parameters

time – sunpy.time.parse_time compatible str datetime.datetime to find the x coordinate for.

class spectrogram.Spectrogram(data, time_axis, freq_axis, start, end, t_init=None, t_label='Time', f_label='Frequency', content='', instruments=None)

Bases: radiospectra.util.Parent

Spectrogram Class.

Warning

This module is under development! Use at your own risk.

data~numpy.ndarray

two-dimensional array of the image data of the spectrogram.

time_axis~numpy.ndarray

one-dimensional array containing the offset from the start for each column of data.

freq_axis~numpy.ndarray

one-dimensional array containing information about the frequencies each row of the image corresponds to.

start~datetime.datetime

starting time of the measurement

end~datetime.datetime

end time of the measurement

t_initint

offset from the start of the day the measurement began. If None gets automatically set from start.

t_labelstr

label for the time axis

f_labelstr

label for the frequency axis

contentstr

header for the image

instrumentsstr array

instruments that recorded the data, may be more than one if it was constructed using combine_frequencies or join_many.

COPY_PROPERTIES = [('time_axis', 1), ('freq_axis', 1), ('instruments', 1), ('start', 0), ('end', 0), ('t_label', 0), ('f_label', 0), ('content', 0), ('t_init', 0)]

at_freq(freq)

auto_const_bg()

Automatically determine background.

auto_find_background(amount=0.05)

Automatically find the background. This is done by first subtracting the average value in each channel and then finding those times which have the lowest standard deviation.

Parameters

amount (float) – The percent amount (out of 1) of lowest standard deviation to consider.

clip_freq(vmin=None, vmax=None)

Return a new spectrogram only consisting of frequencies in the interval [vmin, vmax].

Parameters

• vmin (float) – All frequencies in the result are greater or equal to this.

• vmax (float) – All frequencies in the result are smaller or equal to this.

clip_values(vmin=None, vmax=None, out=None)

Clip intensities to be in the interval [vmin, vmax].

Any values greater than the maximum will be assigned the maximum, any values lower than the minimum will be assigned the minimum. If either is left out or None, do not clip at that side of the interval.

Parameters

• min (int or float) – New minimum value for intensities.

• max (int or float) – New maximum value for intensities.

constbacksub(overwrite=True)

Background subtraction method where the average and the standard deviation of each row will be calculated and subtracted from the image.

Parameters

overwrite (bool) – If function constbacksub has been called directly, there will be a possibility to overwrite it’s current spectrogram data.

property dtype

elimwrongchannels(overwrite=True)

Removing the RFI (radio frequency interference) from the spectrogram.

Parameters

overwrite (bool) – If function elimwrongchannels has been called directly, there will be a possibility to overwrite it’s current spectrogram data.

estimate_change_points(window_width=100, max_length_single_segment=20000, segment_width=10000)

Estimates the change points of the spectrogram and returns the indices. If the spectrogram is too big it will get segmented. These segments will overlap by 2*window_width to not miss change points where the spectrogram is segmented.

Parameters

• window_width (int) – width of the sliding window.

• max_length_single_segment (int) – max width of data array. If bigger it will get segmented because of memory reasons.

• segment_width (int) – width of the segments if the CallistoSpectrogram gets segmented.

static format_freq(freq)

Override to configure default plotting.

static format_time(time)

Override to configure default plotting.

freq_overlap(other)

Get frequency range present in both spectrograms. Returns (min, max) tuple.

Parameters

other (Spectrogram) – Other spectrogram with which to look for frequency overlap.

glid_back_sub(window_width=0, weighted=False, overwrite=True)

A gliding background subtraction method, where the sum weighted from the coefficients of the evenly spaces values of each row will be subtracted from the spectrogram.

Parameters

• window_width (int) – The width of the sliding window that is used to calculate the background.

• weighted (bool) – If true, the coefficients of each rows will be considered dependent on the image width.

• overwrite (bool) – If function glid_back_sub has been called directly, there will be a possibility to overwrite it’s current spectrogram data.

interpolate(frequency)

Linearly interpolate intensity at unknown frequency using linear interpolation of its two neighbours.

Parameters

frequency (float or int) – Unknown frequency for which to linearly interpolate the intensities. freq_axis[0] >= frequency >= self_freq_axis[-1]

interpolate2d(overwrite=True)

Interpolate the input data and it returns a new Spectrogram.

Parameters

• spec – The original Spectrogram.

• overwrite (bool) – if function interpolated_spec has been called directly, there will be a possibility to overwrite it’s current spectrogram data.

Returns

New Spectrogram with the interpolated data.

linearize_freqs(delta_freq=None)

Rebin frequencies so that the frequency axis is linear.

Parameters

delta_freq (float) – Difference between consecutive values on the new frequency axis. Defaults to half of smallest delta in current frequency axis. Compare Nyquist-Shannon sampling theorem.

peek(*args, **kwargs)

Plot spectrum onto current axes.

Parameters

• *args – dict.

• **kwargs – dict, any additional plot arguments that should be used when plotting.

Returns

A plot figure.

Return type

matplotlib.Figure

plot(figure=None, overlays=[], colorbar=True, vmin=None, vmax=None, linear=True, showz=True, yres=1080, max_dist=None, **matplotlib_args)

Plot spectrogram onto figure.

Parameters

• figure (matplotlib.Figure) – Figure to plot the spectrogram on. If None, new Figure is created.

• overlays (list) – List of overlays (functions that receive figure and axes and return new ones) to be applied after drawing.

• colorbar (bool) – Flag that determines whether or not to draw a colorbar. If existing figure is passed, it is attempted to overdraw old colorbar.

• vmin (float) – Clip intensities lower than vmin before drawing.

• vmax (float) – Clip intensities higher than vmax before drawing.

• linear (bool) – If set to True, “stretch” image to make frequency axis linear.

• showz (bool) – If set to True, the value of the pixel that is hovered with the mouse is shown in the bottom right corner.

• yres (int or None) – To be used in combination with linear=True. If None, sample the image with half the minimum frequency delta. Else, sample theimage to be at most yres pixels in vertical dimension. Defaultsto 1080 because that’s a common screen size.

• max_dist (float or None) – If not None, mask elements that are further than max_dist away from actual data points (ie, frequencies that actually have data from the receiver and are not just nearest-neighbour interpolated).

randomized_auto_const_bg(amount)

Automatically determine background. Only consider a randomly chosen subset of the image.

Parameters

amount (int) – Size of random sample that is considered for calculation of the background.

randomized_subtract_bg(amount)

Perform randomized constant background subtraction. Does not produce the same result every time it is run.

Parameters

amount (int) – Size of random sample that is considered for calculation of the background.

rescale(vmin=0, vmax=1, dtype=dtype('float32'))

Rescale intensities to [vmin, vmax]. Note that vmin ≠ vmax and spectrogram.min() ≠ spectrogram.max().

Parameters

• vmin (float or int) – New minimum value in the resulting spectrogram.

• vmax (float or int) – New maximum value in the resulting spectrogram.

• dtype (numpy.dtype) – Data-type of the resulting spectrogram.

property shape

subtract_bg(*args, **kwargs)

Perform background subtraction, with the opportunity to choose between different procedures and the ability to remove the radio frequency interference (RFI).

Parameters

• *args – List of desired methods that should be called.

• **kwargs – List of arguments that should be passed to a subfunction.

subtract_bg_sliding_window(amount: float = 0.05, window_width: int = 0, affected_width: int = 0, change_points: Union[bool, List[int]] = False)

Performs background subtraction with a sliding window. Change points where significant jumps in value are observed or expected can be specified or automatically estimated. If change points are present each one will split the spectrogram and each resulting part will have its background removed independently.

Parameters

• amount (float) – The percent amount (out of 1) of lowest standard deviation to consider.

• window_width (int) – The percent amount (out of 1) of lowest standard deviation to consider.

• affected_width (int) – The width of the section where the background calculated by the window_width gets subtracted. It is centered in the sliding window and is also the step size.

• change_points (list of int or bool) – If a list of ints is provided it will use these values as change points. If a bool isprovided it will estimate the change points if true or won’t include any change points if false.

time_formatter(x, pos)

This returns the label for the tick of value x at a specified pos on the time axis.

time_to_x(time)

Return x-coordinate in spectrogram that corresponds to the passed ~datetime.datetime value.

Parameters

time – sunpy.time.parse_time compatible str datetime.datetime to find the x coordinate for.

update_rfi_header(freq_axis, rfi_freq_axis, positions)