suncasa.utils.qlookplot
Attributes
Functions
|
Validates the format of the restoringbeam string. If the format is incorrect, |
|
Returns a normalization object based on the given scaling type. |
|
|
|
|
|
Reads GOES data from https://umbra.nascom.nasa.gov/ repository, for date |
|
|
|
|
|
|
|
|
|
|
|
Parses the time range input and returns start and end times. |
|
Downloads AIA data for specified time range and wavelengths. |
|
Download AIA data in JP2 format using hvpy. |
|
Download a single JP2 file for the given timestamp and wavelength. |
|
Download AIA data using the JSOC API. |
|
Build JSOC query string for data export. |
|
Download AIA data using SunPy Fido. |
|
Retrieve or download AIA FITS files for the specified time range and wavelength. |
|
rdata, meta: (required) data and header of a fits file readed using ndfits.read |
|
|
|
Function to calculate contour levels for plotting from a timeseries of the input radio images. |
|
|
|
|
|
Generate quick-look images of solar radio data with optional AIA overlays. |
|
|
|
Generate quick-look plots and dynamic spectra for solar radio observations. |
Module Contents
- suncasa.utils.qlookplot.validate_and_reset_restoringbeam(restoringbm)[source]
Validates the format of the restoringbeam string. If the format is incorrect, it prints an error message and resets the value to an empty string.
Parameters: - restoringbeam (str): The restoring beam size to validate.
Returns: - str: The original restoringbeam if valid, or an empty string if invalid.
- suncasa.utils.qlookplot.get_normalization(vmin, vmax, scale)[source]
Returns a normalization object based on the given scaling type.
- Parameters:
vmin (float) – Minimum value for normalization
vmax (float) – Maximum value for normalization
scale (str) – Type of scaling, either ‘linear’ or ‘log’
- Returns:
The normalization object based on the given scaling
- Return type:
colors.Normalize or colors.LogNorm
- Raises:
ValueError – If scale is not ‘linear’ or ‘log’
- suncasa.utils.qlookplot.get_goes_data(t=None, sat_num=None)[source]
Reads GOES data from https://umbra.nascom.nasa.gov/ repository, for date and satellite number provided. If sat_num is None, data for all available satellites are downloaded, with some sanity check used to decide the best. If the Time() object t is None, data for the day before the current date are read (since there is a delay of 1 day in availability of the data). :returns: goes_t GOES time array in plot_date format
goes_data GOES 1-8 A lightcurve
- suncasa.utils.qlookplot.parse_trange(trange)[source]
Parses the time range input and returns start and end times.
- Parameters:
trange (list or astropy.time.Time) – Time range for the query.
- Raises:
ValueError – If trange is empty or the start time is later than the end time.
- Returns:
Start and end times as astropy Time objects.
- Return type:
tuple of astropy.time.Time
- suncasa.utils.qlookplot.download_aia_data(trange, wavelengths=[171], cadence=None, outdir='./')[source]
Downloads AIA data for specified time range and wavelengths.
- Parameters:
trange (list or astropy.time.Time) – Time range for the query.
wavelengths (list, optional) – List of wavelengths to download, defaults to [171].
cadence (Quantity, optional) – Desired data cadence, defaults to None.
outdir (str, optional) – Output directory for the downloaded data, defaults to ‘./’.
- Returns:
List of downloaded files.
- Return type:
list
- suncasa.utils.qlookplot.download_jp2(tstart, tend, wavelengths, outdir, cadence=None)[source]
Download AIA data in JP2 format using hvpy.
- Parameters:
tstart (astropy.time.Time) – Start time for the data.
tend (astropy.time.Time) – End time for the data.
wavelengths (list) – List of wavelengths to download.
outdir (str) – Output directory for the downloaded data.
cadence (Quantity, optional) – Desired data cadence, defaults to None.
- Returns:
List of downloaded files.
- Return type:
list
- suncasa.utils.qlookplot.download_single_jp2(timestamp, wave, outdir, data_sources)[source]
Download a single JP2 file for the given timestamp and wavelength.
- Parameters:
timestamp (datetime) – Timestamp for the data.
wave (int) – Wavelength of the data.
outdir (str) – Output directory for the downloaded data.
data_sources (dict) – Dictionary of data sources for different wavelengths.
- Returns:
Path to the downloaded JP2 file.
- Return type:
str
- suncasa.utils.qlookplot.download_using_jsoc(tst, ted, wavelengths, cadence, outdir)[source]
Download AIA data using the JSOC API.
- Parameters:
tst (astropy.time.Time) – Start time for the data.
ted (astropy.time.Time) – End time for the data.
wavelengths (list) – List of wavelengths to download.
cadence (Quantity, optional) – Desired data cadence, defaults to None.
outdir (pathlib.Path) – Output directory for the downloaded data.
- Raises:
drms.ExportError – If JSOC export fails.
- Returns:
List of downloaded files.
- Return type:
list
- suncasa.utils.qlookplot.build_jsoc_query(wave, tst, ted, cadence)[source]
Build JSOC query string for data export.
- Parameters:
wave (int) – Wavelength of the data.
tst (astropy.time.Time) – Start time for the data.
ted (astropy.time.Time) – End time for the data.
cadence (Quantity, optional) – Desired data cadence, defaults to None.
- Returns:
JSOC query string.
- Return type:
str
- suncasa.utils.qlookplot.download_using_fido(tst, ted, wavelengths, cadence, outdir)[source]
Download AIA data using SunPy Fido.
- Parameters:
tst (astropy.time.Time) – Start time for the data.
ted (astropy.time.Time) – End time for the data.
wavelengths (list) – List of wavelengths to download.
cadence (Quantity, optional) – Desired data cadence, defaults to None.
outdir (pathlib.Path) – Output directory for the downloaded data.
- Returns:
List of downloaded files.
- Return type:
list
- suncasa.utils.qlookplot.trange2aiafits(trange, aiawave, aiadir)[source]
Retrieve or download AIA FITS files for the specified time range and wavelength.
- Parameters:
trange (list or astropy.time.Time) – Time range for the query.
aiawave (int) – Wavelength of the AIA data.
aiadir (str) – Directory to search for the data.
- Returns:
Path to the AIA FITS files.
- Return type:
str or None
- suncasa.utils.qlookplot.parse_rdata(rdata, meta, icmap=None, stokes='I,V', sp=None, show_warnings=False)[source]
rdata, meta: (required) data and header of a fits file readed using ndfits.read icmap: (optional) colormap for plotting radio images stokes: (optional) polarizations to visualizing sp: (optional) the spectral window to plot, if there are multiple spectral windows in the fits file :returns: * cmaps (A dictionary contains colormaps for the selected polarizations)
datas (A dictionary contains image data for the selected polarizations)
- suncasa.utils.qlookplot.mk_qlook_image(vis, ncpu=1, timerange='', twidth=12, stokes='I,V', antenna='', imagedir=None, spws=[], toTb=True, sclfactor=1.0, overwrite=True, doslfcal=False, datacolumn='data', phasecenter='', robust=0.0, niter=500, gain=0.1, imsize=[512], cell=['5.0arcsec'], pbcor=True, reftime='', restoringbeam=[''], refbmsize=70.0, reffreq=1.0, minbmsize=4.0, mask='', docompress=False, wrapfits=True, uvrange='', subregion='', c_external=True, show_warnings=False)[source]
- suncasa.utils.qlookplot.radio_image_clevels(imres, clevels=[0.2, 0.4, 0.6, 0.8], snr=2.0, timerange_bkg=None, overbright=1000000000000.0)[source]
Function to calculate contour levels for plotting from a timeseries of the input radio images. The contour levels are fixed to those relative to the flare peak. :param imres: a dictionary contains the information of the FITS files (produced by qlookplot) :param clevels: relative contour levels with regard to the flare peak :snr: minimum enhancement during the peak time against the background level. Default 3 :timerange_bkg: timerange of the background. Example: [‘2024-01-03T17:46’, ‘2024-01-03T17:47’].
Default to None. If None, use the median of all FITS files
- Overbright:
Brightness temperature threshold in K, above which the peak values are deemed corrupted and not considered Default to 1e12 K.
- suncasa.utils.qlookplot.plt_qlook_image(imres, timerange='', spwplt=None, figdir='./qlookimgs/', specdata=None, verbose=False, stokes='I,V', fov=None, imax=None, imin=None, icmap='RdYlBu', inorm='linear', amax=None, amin=None, acmap='gray_r', anorm='log', dmax=None, dmin=None, dcmap='viridis', dnorm='linear', sclfactor=1.0, nclevels=3, clevels=None, clevelsfix=None, aiafits='', aiadir=None, aiawave=171, plotaia=True, freqbounds=None, moviename='', alpha_cont=1.0, custom_mapcubes=[], opencontour=False, movieformat='html', ds_normalised=False, minsnr=5, timtol=10.0 / 60.0 / 24.0, overwrite=True)[source]
Generate quick-look images of solar radio data with optional AIA overlays.
This function plots dynamic spectra, AIA overlays, and radio images for a specified time range and field of view. It can handle different plotting configurations, including stokes parameters and plotting custom contour levels.
- Parameters:
imres (dict or str) – Input image results dictionary from suncasa.utils.qlookplot.
timerange (str or astropy.time.Time, optional) – Time range for plotting, defaults to ‘’. If ‘’, use the entire timerange of the input imres. Can be a string or astropy.time.Time object, e.g., ‘2024-01-03T17:46~2024-01-03T17:47’.
spwplt (list, optional) – List of spectral windows to plot, defaults to None.
figdir (str, optional) – Directory to save the generated plots, defaults to ‘./qlookimgs/’.
specdata (object, optional) – Spectral data for plotting dynamic spectra.
verbose (bool, optional) – If True, print verbose output, defaults to True.
stokes (str, optional) – Comma-separated stokes parameters to plot, defaults to ‘I,V’.
fov (list, optional) – Field of view for the plot, defaults to None.
imax (float, optional) – Maximum value for radio image plot, defaults to None.
imin (float, optional) – Minimum value for radio image plot, defaults to None.
icmap (str, optional) – Colormap for radio image, defaults to ‘RdYlBu’.
inorm (str, optional) – Normalization for radio images. Must be ‘linear’ or ‘log’.
amin (float, optional) – Max and min values for AIA data normalization.
acmap (str, optional) – Colormap for AIA images, defaults to None.
anorm (str, optional) – Normalization for AIA data. Must be ‘linear’ or ‘log’.
dmin (float, optional) – Max and min values for dynamic spectra normalization.
dcmap (str, optional) – Colormap for dynamic spectra, defaults to ‘viridis’.
dnorm (str, optional) – Normalization for dynamic spectra. Must be ‘linear’ or ‘log’.
sclfactor (float, optional) – Scaling factor for spectral data, defaults to 1.0.
nclevels (int, optional) – Number of contour levels for radio images, calculated between imin and imax. Used if clevels and clevelsfix are not provided.
clevels (list, optional) – Contour levels for radio images, defined as percentages of the maximum value in the image. Overrides nclevels if provided. For example, [0.3, 0.5, 0.8] plots contours at 30%, 50%, and 80% of the maximum value for each spectral window.
clevelsfix (list, optional) – Fixed contour levels for each spectral window, calculated using radio_image_clevels. These levels are relative to the flare peak and defined as percentages of the peak value. Overrides both nclevels and clevels if provided.
aiafits (str, optional) – Path to AIA FITS files, defaults to ‘’.
aiadir (str, optional) – Directory to search for AIA FITS files, defaults to None.
aiawave (int, optional) – AIA wavelength to use, defaults to 171.
plotaia (bool, optional) – If True, plot AIA data, defaults to True.
freqbounds (dict, optional) – Frequency bounds for plotting, defaults to None.
moviename (str, optional) – Name for the output movie, defaults to ‘’.
alpha_cont (float, optional) – Alpha value for contours, defaults to 1.0.
custom_mapcubes (list, optional) – List of custom mapcubes to plot, defaults to [].
opencontour (bool, optional) – If True, use open contours, defaults to False.
movieformat (str, optional) – Format for the output movie, defaults to ‘html’.
ds_normalised (bool, optional) – If True, normalize the dynamic spectra, defaults to False.
minsnr (int, optional) – Minimum signal-to-noise ratio for plotting, defaults to 5.
timtol (float, optional) – Time tolerance for matching AIA data, defaults to 10./60./24. (in days).
overwrite (bool, optional) – If True, overwrite existing plots, defaults to True.
- Raises:
ValueError – If the input parameters are not valid.
- Returns:
Path to the generated movie file.
- Return type:
str
Example usage:
```python from suncasa.utils import qlookplot as ql from astropy.time import Time import numpy as np import matplotlib.pyplot as plt
# Load imres from the npz file from a prior qlookplot run imres = np.load(‘./qlookfits/IDB20240514_1645-1738.XXYY.cal.1s.ms.slfcaled.imres.npz’, allow_pickle=True)[‘imres’].item()
# Load dynamic spectrum from suncasa.dspec import dspec d = dspec.Dspec() d.read(‘eovsa.spec.flare_id_20240514164700.fits’, source=’eovsa’)
# Calculate contour levels # Define the background time to determine bands with sufficient flare enhancement timerange_bkg = Time([‘2024-05-14T16:39’, ‘2024-05-14T16:42’]) clevelsfix = ql.radio_image_clevels(imres, timerange_bkg=timerange_bkg, snr=2)
# Define timerange, fov, dmin, dmax (for spectrogram), and AIA normalization for plotting images fov = [[760., 1060.], [-430., -130.]] fov = None ql.plt_qlook_image(imres, stokes=’I’, figdir=’./qlookimgs/’,
specdata=d, icmap=plt.get_cmap(‘RdYlBu’), aiadir=’./’, fov=fov, opencontour=True, dcmap=’viridis’, dnorm=’log’, clevelsfix=clevelsfix, movieformat=’mp4’)
- suncasa.utils.qlookplot.dspec_external(vis, workdir='./', specfile=None, ds_normalised=False)[source]
- suncasa.utils.qlookplot.qlookplot(vis, timerange=None, spw='', spwplt=None, workdir='./', specfile=None, xycen=None, fov=[500.0, 500.0], xyrange=None, restoringbeam=[''], refbmsize=70.0, reffreq=1.0, minbmsize=4.0, antenna='', uvrange='', stokes='RR,LL', robust=0.0, weighting='briggs', niter=500, imsize=[512], cell=['5.0arcsec'], mask='', gain=0.1, pbcor=True, interactive=False, datacolumn='data', reftime='', toTb=True, sclfactor=1.0, subregion='', usemsphacenter=True, imagefile=None, outfits='', docompress=True, wrapfits=True, nclevels=3, clevels=None, clevelsfix=None, calpha=0.5, opencontour=False, imax=None, imin=None, icmap=None, inorm='linear', dmin=None, dmax=None, dcmap=None, dnorm='linear', plotaia=True, aiawave=171, aiafits=None, aiadir=None, amax=None, amin=None, acmap=None, anorm='log', goestime=None, mkmovie=False, ncpu=1, twidth=1, movieformat='html', cleartmpfits=True, overwrite=True, clearmshistory=False, show_warnings=False, verbose=False, quiet=False, ds_normalised=False)[source]
Generate quick-look plots and dynamic spectra for solar radio observations. Required inputs:
- param vis:
Path to the calibrated CASA measurement set.
- Important optional inputs:
timerange: Timerange for analysis in standard CASA format. Defaults to entire range, which can be slow. spw: spectral window (SPW) selection following the CASA syntax.
spwplt: Subset of SPW to display, defaults to all specified in spw. workdir: Working directory for temporary files, defaults to current directory. specfile: Path to a saved dynamic spectrum file (from suncasa.dspec.dspec.Dspec())
6or generate a median dynamic spectrum on the fly if not provided.
- Optional inputs:
goestime: goes plot time, example [‘2016/02/18 18:00:00’,’2016/02/18 23:00:00’] xycen: center of the image in helioprojective coordinates (HPLN/HPLT), in arcseconds. Example: [900, -150.] fov: field of view in arcsecs. Example: [500., 500.] xyrange: field of view in solar XY coordinates. Format: [[x1,x2],[y1,y2]]. Example: [[900., 1200.],[0,300]]
*NOTE: THIS PARAMETER OVERWRITES XYCEN AND FOV*
- Restoring Beam Parameters:
- restoringbeam: A list specifying the sizes of the restoring beam explicitly in arc seconds (e.g., [‘100arcsec’, ‘80arcsec’, ‘50arcsec’, …]).
Must match the number of SPWs if not [‘’]. If specified, these values override automatic beam size calculations for each SPW.
- refbmsize: The reference beam size in arc seconds. This parameter is used in conjunction with reffreq to calculate the beam size for all SPWs,
assuming the beam size is inversely proportional to the frequency. The parameters refbmsize,`reffreq` and minbmsize are only used if restoringbeam is set to [‘’].
reffreq: The reference frequency in GHz, used together with refbmsize to calculate the beam sizes for SPWs.
minbmsize: Minimum beam size in arcseconds, overrides smaller calculated sizes.
- CASA tclean parameters: refer to CASA tclean documentation for more details.
antenna: baseline to generate dynamic spectrum uvrange: uvrange to select baselines for generating dynamic spectrum stokes: polarization of the clean image, can be ‘RR,LL’ or ‘I,V’ robust: weighting: niter: imsize: cell: mask: only accept CASA region format (https://casaguides.nrao.edu/index.php/CASA_Region_Format) gain: pbcor: interactive: datacolumn:
- image registration parameters:
reftime: Reference time for image alignment. toTb: Bool. Convert the default Jy/beam to brightness temperature? sclfactor: scale the image values by its value (e.g., sclfactor = 100 to compensate VLA 20 dB attenuator) subregion: only write the data within the sub-region selection. See ‘help par.region’ for details. usephacenter: Bool – if True, correct for the RA and DEC in the ms file based on solar empheris.
Otherwise assume the phasecenter is correctly pointed to the solar disk center (EOVSA case)
imagefile: Use specified CASA radio image file for registration; otherwise, generate anew. outfits: Use specified FITS file of a radio image for output; otherwise, generate anew. docompress: if compress the outfits wrapfits: if wrap the fits files of multiple spectral windows at one given time interval into a combined fits file. overwrite: if overwrite the existed outfits file (default: True).
- radio image plotting parameters:
nclevels: Number of contour levels for radio image plots. clevels: Specific contour levels for radio image plots. opencontour: Boolean. Plots open contours if True; filled contours otherwise. icmap: Color map (string or Colormap object) for radio images/contours. imax, imin: Color scale range, defining normalization before color mapping. inorm: Normalization method (string or Normalize object), overriding imax and imin.
- radio dynamic spectrum plotting parameters:
dcmap: Color map (string or Colormap object) for the dynamic spectrum. dmin, dmax: Color scale range for dynamic spectrum normalization before color mapping. dnorm: Normalization method (string or Normalize object), overriding dmax and dmin.
- SDO/AIA image plotting parameters:
plotaia: Boolean. Downloads and plots AIA image at specified aiawave if True. aiawave: AIA image passband to download and display. aiafits: Directly plots AIA image from provided FITS file, skipping download. (note: users can provide any solar image FITS file for plotting). aiadir: Searches this directory for AIA image files to skip download. acmap: Color map (string or Colormap object) for AIA images. amin, amax: Color scale range for AIA image normalization before color mapping. anorm: Normalization method (string or Normalize object), overriding amax and amin.
- movie parameters:
mkmovie: Boolean. Generates a movie from radio images over multiple time intervals if True. ncpu: Number of CPUs for parallel clean operations with ptclean. twidth: Time pixel averaging width (default: 1). movieformat: Output movie format, either ‘html’ or ‘mp4’.