suncasa.dspec

SunCASA Dspec

isort:skip_file

Submodules

Classes

Dspec

A class to handle dynamic spectra from radio observations.

Package Contents

class suncasa.dspec.Dspec(fname=None, specfile=None, bl='', uvrange='', field='', scan='', datacolumn='data', domedian=False, timeran=None, spw=None, timebin='0s', regridfreq=False, fillnan=None, verbose=False, usetbtool=True, ds_normalised=False)[source]

A class to handle dynamic spectra from radio observations.

data

The dynamic spectrum data array.

Type:

numpy.ndarray

time_axis

Time axis of the dynamic spectrum.

Type:

astropy.time.Time

freq_axis

Frequency axis of the dynamic spectrum in Hz.

Type:

numpy.ndarray

telescope

Name of the telescope used for the observation.

Type:

str

observatory

Name of the observatory.

Type:

str

t_label

Label for the time axis.

Type:

str

f_label

Label for the frequency axis.

Type:

str

bl

Baseline information.

Type:

str

uvrange

UV range information.

Type:

str

pol

Polarization information.

Type:

str

spec_unit

Unit of the dynamic spectrum data (‘sfu’, ‘Jy’, or ‘K’).

Type:

str, default ‘sfu’

__init__(fname=None, specfile=None, \*\*kwargs):

Initializes the Dspec object by reading a FITS file or a saved numpy array.

read(fname, source=None, \*args, \*\*kwargs):

Reads dynamic spectrum data from a file.

tofits(fitsfile=None, specdata=None, \*\*kwargs):

Writes the dynamic spectrum data to a FITS file.

get_dspec(fname=None, \*\*kwargs):

Extracts dynamic spectrum data from a measurement set.

wrt_dspec(specfile=None, specdat=None):

Writes the dynamic spectrum data to a binary file.

rd_dspec(specdata, \*\*kwargs):

Reads dynamic spectrum data from a numpy file.

concat_dspec(specfiles, outfile=None, savespec=False):

Concatenates multiple dynamic spectrum files along the time axis.

peek(*args, \*\*kwargs):

Plots the dynamic spectrum on the current axes.

plot(pol='I', \*\*kwargs):

Plots the dynamic spectrum for a given polarization.

data = None
time_axis = None
freq_axis = None
telescope = None
observatory = None
t_label = None
f_label = None
bl = None
uvrange = None
pol = None
spec_unit = 'sfu'
spec_name = 'Intensity'
read(fname, source=None, *args, **kwargs)[source]

Reads dynamic spectrum data from a file.

Parameters:

  • fname (str or list of str) – The file name to read the dynamic spectrum data from.

  • source (str, optional) – Specifies the data source (‘fits’, ‘suncasa’, or ‘lwa’) to determine the appropriate reader.

  • source. (Additional parameters are passed to the specific reader function based on the)

tofits(fitsfile=None, specdata=None, spectype='amp', spec_unit='jy', telescope='EOVSA', observatory='Owens Valley Radio Observatory', observer='EOVSA Team')[source]

Writes the dynamic spectrum data to a FITS file.

This method exports the stored dynamic spectrum data into a new FITS file, including relevant metadata and optional input spectrum data.

Parameters:

  • fitsfile (str, optional) – Path and name of the output FITS file. If not specified, a default name will be generated.

  • specdata (dict, optional) – Input dictionary containing dynamic spectrum data and metadata. If not provided, the method uses the data stored in the Dspec object.

  • spectype (str, optional) – Specifies the type of the spectrum to be saved (‘amp’ for amplitude, ‘pha’ for phase). Default is ‘amp’.

  • spec_unit (str, optional) – Specifies the unit of the spectrum data (‘jy’ for Jansky, ‘sfu’ for Solar Flux Units, ‘k’ for Kelvin). Default is ‘jy’.

  • telescope (str, optional) – Name of the telescope with which the data was obtained. Default is ‘EOVSA’.

  • observatory (str, optional) – Name of the observatory. Default is ‘Owens Valley Radio Observatory’.

  • observer (str, optional) – Name of the observer or team that made the observation. Default is ‘EOVSA Team’.

Return type:

None

Raises:

  • FileNotFoundError – If the specified fitsfile path does not exist.

  • ValueError – If specdata is provided but does not contain the required keys.

Examples

>>> dspec = Dspec()
>>> dspec.tofits(fitsfile='output.fits', specdata=my_specdata, spec_unit='sfu', observer='Sun Observer')

Note

The method can directly utilize the dynamic spectrum data stored within the Dspec object if specdata is not provided. Ensure the Dspec object has been properly initialized with dynamic spectrum data before calling this method without specdata.

get_dspec(fname=None, specfile=None, bl='', uvrange='', field='', scan='', datacolumn='data', domedian=False, timeran=None, spw=None, timebin='0s', regridfreq=False, hanning=False, applyflag=True, fillnan=None, verbose=False, usetbtool=True, ds_normalised=False)[source]
wrt_dspec(specfile=None, specdat=None)[source]
rd_dspec(specdata, spectype='amp', spec_unit='jy')[source]
concat_dspec(specfiles, outfile=None, savespec=False)[source]

concatenate a list of specfiles in time axis :param specfiles: a list of specfile to concatenate :return: concatenated specdata

peek(*args, **kwargs)[source]

Plot dynamaic spectrum onto current axes.

Parameters:

  • *args (dict)

  • **kwargs (dict) – Any additional plot arguments that should be used when plotting.

Returns:

fig – A plot figure.

Return type:

~matplotlib.Figure

plot(pol='I', vmin=None, vmax=None, norm='log', cmap='viridis', cmap2='viridis', vmin2=None, vmax2=None, figsize=None, timerange=None, freqrange=None, bkgtim=None, interp_method='linear', ignore_gaps=True, freq_unit='GHz', spec_unit=None, plot_fast=False, percentile=[1, 99], minmaxpercentile=False, axes=None, spec_name=None, **kwargs)[source]

Plots the dynamic spectrum for a given polarization.

This method generates a plot of the dynamic spectrum, allowing for customization of the visualization through various parameters such as color maps, normalization, and value ranges.

Parameters:

  • pol (str, optional) – Polarization for plotting. Default is ‘I’.

  • vmin (float, optional) – Minimum intensity value for the color scale. Default is None, which auto-scales.

  • vmax (float, optional) – Maximum intensity value for the color scale. Default is None, which auto-scales.

  • norm (str or matplotlib.colors.Normalize, optional) – Normalization of the color scale. Can be ‘linear’, ‘log’, or a custom normalization. Default is ‘log’.

  • cmap (str, optional) – Matplotlib colormap name or instance for the plot. Default is ‘viridis’.

  • cmap2 (str, optional) – Matplotlib colormap name or instance for the second polarization plot. Default is ‘viridis’.

  • vmin2 (float, optional) – Minimum intensity value for the color scale of the second polarization. Default is None.

  • vmax2 (float, optional) – Maximum intensity value for the color scale of the second polarization. Default is None.

  • timerange (list of str, optional) – Time range to plot, formatted as [‘start_time’, ‘end_time’]. Times should be in ISO format. Defaults to None, which plots the entire range.

  • freqrange (list of float, optional) – Frequency range to plot, in units specified by freq_unit. Defaults to None, which plots the entire range.

  • bkgtim (list or list of lists) –

    Background time interval(s). It can be a single time interval (list of two strings) or multiple time intervals (list of lists of two strings each). Example: [‘2024-06-11T19:41:00’, ‘2024-06-11T20:40:58’]

    [[‘2024-06-11T19:41:00’, ‘2024-06-11T20:40:58’], [‘2024-06-11T21:41:00’, ‘2024-06-11T22:40:58’]]

  • interp_method (str, optional) – The method of interpolation to use. Default is ‘linear’. Can be any method supported by scipy.interpolate.interp1d.

  • ignore_gaps (bool, optional) – If True, ignores gaps in the frequency axis. Default is True.

  • freq_unit (str, optional) – Unit for the frequency axis (‘kHz’, ‘MHz’, ‘GHz’). Default is ‘GHz’.

  • spec_unit (str, optional) – Unit for the spectrum data (‘sfu’, ‘Jy’, or ‘K’). If not specified, uses the unit from the Dspec object.

  • plot_fast (bool, optional) – If True, uses a faster plotting method which may reduce detail. Default is False.

  • percentile (list of float, optional) – Percentile values to use for auto-scaling the color range. Default is [1, 99].

  • minmaxpercentile (bool, optional) – If True, uses percentile for vmin and vmax. Default is False.

  • spec_name (str, optional) – Label to display for the spectrum quantity (e.g., for colorbars). Defaults to the object’s spec_name if set.

  • kwargs (dict) – Any additional plot arguments that should be used when plotting.

Returns:

The matplotlib figure object containing the plot.

Return type:

matplotlib.figure.Figure

Example:

>>> dspec = Dspec()
>>> fig = dspec.plot(pol='I', vmin=0.1, vmax=5, cmap='hot', freqrange=[1, 2], timerange=['2021-01-01T00:00:00', '2021-01-01T01:00:00'])
>>> plt.show()
Notes:

For dual-polarization plots (e.g., ‘RRLL’), cmap2 along with vmin2 and vmax2 can be specified to customize the appearance of the second polarization.