The Field class

The Field class is used to manage the overall state and parameters of observed field, including observations, images, calibration solutions, etc.

class rapthor.lib.field.Field(parset, minimal=False)

The Field object stores parameters needed for processing of the field

Parameters:

parsetdict

Parset with processing parameters

minimalbool

If True, only initialize the minimal set of required parameters

adjust_sector_boundaries()

Adjusts the imaging sector boundaries for overlaping sources

Note: this adjustment is only done when there are multiple sectors in a grid, since its purpose is to ensure that sources don’t get split between two neighboring sectors

check_selfcal_progress()

Checks whether selfcal has converged or diverged by comparing the current image noise to that of the previous cycle. A check is also done on the absolute value of the noise.

Convergence is determined by comparing the noise and dynamic range ratios to self.convergence_ratio, which is the minimum ratio of the current noise to the previous noise above which selfcal is considered to have converged (must be in the range 0.5 – 2). E.g., self.convergence_ratio = 0.95 means that the image noise must decrease by ~ 5% or more from the previous cycle for selfcal to be considered as not yet converged. The same is true for the dynamic range but reversed (the dynamic range must increase by ~ 5% or more from the previous cycle for selfcal to be considered as not yet converged).

Divergence is determined by comparing the noise ratio to self.divergence_ratio, which is the minimum ratio of the current noise to the previous noise above which selfcal is considered to have diverged (must be >= 1). E.g., divergence_ratio = 1.1 means that, if image noise worsens by ~ 10% or more from the previous cycle, selfcal is considered to have diverged.

Failure is determined by comparing the absolute value of the noise in the current cycle with the theoretical noise. If the ratio of the current median noise to the theoretical one is greater than failure_ratio, selfcal is considered to have failed.

Returns:

selfcal_statenamedtuple

The selfcal state, with the following elements:

selfcal_state.converged - True if selfcal has converged in all

sectors

selfcal_state.diverged - True if selfcal has diverged in one or

more sectors

selfcal_state.failed - True if selfcal has failed in one or

more sectors

chunk_observations(mintime, prefer_high_el_periods=True)

Break existing observations into smaller observations

Parameters:

mintimefloat

Minimum duration in sec for a chunk

prefer_high_el_periodsbool, optional

Prefer periods for which the elevation is in the highest 80% of values for a given observation. This option is useful for removing periods of lower signal-to-noise (e.g., due to being at lower elevations where ionospheric activity can increase and sensitivity decrease). If the requested mintime is larger than the total time of the high-elevation period for a given observation, then the full observation is used instead

define_bright_source_sectors(index)

Defines the bright source sectors

Note: these sectors are used only in prediction of the bright sources

Parameters:

indexint

Processing cycle index

define_full_field_sector(radius=None)

Defines the full-field imaging sector, used for generation of the initial sky model

Parameters:

radiusfloat, optional

Radius in degrees of region to image. If None, an area corresponding to 2*FWHM is used

define_imaging_sectors()

Defines the imaging sectors

define_normalize_sector()

Defines the flux-scale normalization imaging sector, used for normalization of the overall flux scale

define_outlier_sectors(index)

Defines the outlier sectors

Note: these sectors are used only in prediction of the outlier sources

Parameters:

indexint

Processing cycle index

define_predict_sectors(index)

Defines the predict sectors

Note: these sectors are used only in prediction of all sources for direction- independent solves

Parameters:

indexint

Processing cycle index

define_sector_bounds()

Compute bounding box for all imaging sectors and store as a a semi-colon-separated list of [maxRA; minDec; minRA; maxDec] (we use semi- colons as otherwise the workflow parset parser will split the list). Also store the midpoint as [midRA; midDec]. Note: this is just once, rather than each time the sector borders are adjusted, so that the image sizes do not change with cycle (so mask images from previous cycles may be used)

find_intersecting_sources()

Finds sources that intersect with the intial sector boundaries

Returns:

intersecting_source_polys: list of Polygons

List of source polygons that intersect one or more sector boundaries

get_calibration_radius()

Returns the radius in degrees that encloses all calibrators

get_matplotlib_patch(wcs=None)

Returns a matplotlib patch for the field primary-beam FOV polygon

Parameters:

wcsWCS object, optional

WCS object defining (RA, Dec) <-> (x, y) transformation. If not given, the field’s transformation is used

Returns:

patchmatplotlib patch object

The patch for the field polygon

get_obs_parameters(parameter)

Returns list of parameters for all observations

Parameters:

parameterstr

Name of parameter to return

Returns:

parameterslist

List of parameters of each observation

get_source_distances(source_dict: Dict[str, List[float]])

Returns source distances in degrees from the phase center

Parameters:

source_dictdict

Dict of source patch names and coordinates in degrees (e.g., {‘name’: [RA, Dec]})

Returns:

namesnumpy array

Array of source names

distancesnumpy array

Array of distances from the phase center in degrees

makeWCS()

Makes simple WCS object

make_outlier_skymodel(threshold_ratio=0.001, threshold_jy=0.1)

Make a sky model of any outlier calibration sources, not included in any imaging sector

Thresholds can be used to avoid unnecessary processing in cases where the total flux density of the outlier sky model is negligable (either relative to that in the imaged regions or in absolute terms). Note that outlier sources will be considered for processing when either threshold is met.

Parameters:

threshold_ratiofloat, optional

The threshold of the ratio of the total flux in outlier sources relative to the total flux in imaged sources, above which outlier sources will be considered

threshold_jyfloat, optional

The threshold (in Jy) of the total flux density of all outlier sources, above which outlier sources will be considered

Returns:

outlier_skymodel: LSMTool sky model object

Sky model of the outlier sources

make_skymodels(skymodel_true_sky, skymodel_apparent_sky=None, regroup=True, find_sources=False, target_flux=None, target_number=None, calibrator_max_dist_deg=None, index=0)

Groups a sky model into source and calibration patches

Grouping is done on the apparent-flux sky model if available. Note that the source names in the true- and apparent-flux models must be the same (i.e., the only differences between the two are the fluxes and spectral indices)

Parameters:

skymodel_true_skystr or LSMTool skymodel object

Filename of input makesourcedb true-flux sky model file

skymodel_apparent_skystr or LSMTool skymodel object, optional

Filename of input makesourcedb apparent-flux sky model file

regroupbool, optional

If False, the calibration sky model is not regrouped to the target flux. Instead, the existing calibration groups are used

find_sourcesbool, optional

If True, group the sky model by thresholding to find sources. This is not needed if the input sky model was filtered by PyBDSF in the imaging operation

target_fluxfloat, optional

Target flux in Jy for grouping

target_numberint, optional

Target number of patches for grouping

calibrator_max_dist_degfloat, optional

Maximum distance in degrees from phase center for grouping

indexindex

Processing cycle index

plot_overview(output_filename, show_initial_coverage=False, show_calibration_patches=False, moc=None, check_skymodel_bounds=False)

Plots an overview of the field, with optional intial sky-model coverage and calibration facets shown

Parameters:

output_filenamestr

Base filename of ouput file, to be output to ‘dir_working/plots/’

show_initial_coveragebool, optional

If True, plot the intial sky-model coverage. The plot will be centered on the center of the field. If False, the plot will be centered on the center of the imaging region(s)

show_calibration_patchesbool, optional

If True, plot the calibration patches

mocstr or None, optional

If not None, the multi-order coverage map to plot alongside the usual quantiies. Only shown if show_initial_coverage = True

check_skymodel_boundsbool, optional

If True (and show_calibration_patches is True), the bounds from the calibration sky model are checked when calculating the faceting bounds

remove_skymodels()

Remove sky models to minimize memory usage

scan_h5parms()

Scans the calibration h5parms

The basic structure is checked for correctness and for the presence of amplitude solutions (which may require different processing steps).

scan_observations()

Checks input MS files and initializes the associated Observation objects

set_obs_parameters()

Sets parameters for all observations from current parset and sky model

update(step_dict, index, final=False)

Updates parameters, sky models, etc. for current cycle

Parameters:

step_dictdict

Dict of parameter values for given processing cycle

indexint

Index of processing cycle (counting starts from 1)

finalbool, optional

If True, process as the final pass (needed for correct processing of the sky models)

update_observations(new_observations)

Update the observations used for processing

This method should be run when any changes to the observations has been done, such as chunking or reseting the observations to the original, full ones.

Parameters:

observationslist of Observation objects

The list of observations to use for processing

update_skymodels(index, regroup, target_flux=None, target_number=None, calibrator_max_dist_deg=None, combine_current_and_intial=False)

Updates the source and calibration sky models from the output sector sky model(s)

Parameters:

indexint

Processing cycle index (counts starting from 1)

regroupbool

Regroup sky model. In almost all cases, regrouping should be done. The exception is when using small imaging sectors when the sources in each sector should be grouped into a single patch together.

target_fluxfloat, optional

Target flux in Jy for grouping

target_numberint, optional

Target number of patches for grouping

calibrator_max_dist_degfloat, optional

Maximum distance in degrees from phase center for grouping

combine_current_and_intialbool, optional

If True, combine the initial and current sky models (needed for the final calibration in order to include potential outlier sources)