flint.peel.potato

Utilities the connect to Stefan Duchesne potatopeel module, which is responsible for peeling sources in racs. The repository is available at:

https://gitlab.com/Sunmish/potato/-/tree/main

Potato stands for “Peel Out That Annoying Terrible Object”.

Although this is a python module, for the moment it is expected to be in a singularity container. There are several reasons for this, but the principal one is that the numba module used by potatopeel may be difficult to get working correctly alongside dask and flint. Keeping it simple at this point is the main aim. There is also the problem of casatasks + python-casacore not jiving in newer python versions.

Classes

NormalisedSources	Temporary container to hold the normalised source properties that
PotatoConfigCommand	Container for potato configuration command results
PotatoConfigOptions	Container class to hold options that go into the potatopy
PotatoPeelArguments	The mandatory arguments for potato peel.
PotatoPeelCommand	Container to hold the items of the hot potato command
PotatoPeelOptions	Container class to hold options that go to the potato peel

Functions

_potato_config_command(→ PotatoConfigCommand)	Create the peel_configuration.py command that will be called
_potato_options_to_command(→ str)	Construct the CLI options that would be provided to
_potato_peel_command(→ PotatoPeelCommand)	Construct the CLI command for hot_potato, and appropriately
_prepare_potato_options(...)	Create the appropriate set of potato option class instances. This function
_print_ms_colnames(→ flint.options.MS)	A dummy function to print colnames in a MS table
cli()
create_run_potato_config(→ PotatoConfigCommand)	Construct and run a CLI command into the peel_configuration.py
create_run_potato_peel(→ PotatoPeelCommand)	Construct and run a hot_potato command to peel out sources from
find_sources_to_peel(→ astropy.table.Table | None)	Obtain a set of sources to peel from a reference candidate set. This will
get_parser(→ argparse.ArgumentParser)
get_source_props_from_table(→ NormalisedSources)	Given the astropy table of known sources to peel, normalise their
load_known_peel_sources(→ astropy.table.Table)	Locate and load the packaged set of known sources to peel. These sources
potato_peel(→ flint.options.MS)	Peel out sources from a measurement set using PotatoPeel. Candidate sources
prepare_ms_for_potato(→ flint.options.MS)	The potatopeel software requires the data column being operated against to be
source_within_image_fov(→ bool)	Evaluate whether a source will be within the field of view

Module Contents

class flint.peel.potato.NormalisedSources

Bases: NamedTuple

Temporary container to hold the normalised source properties that would be provided to potato

source_decs: tuple[float]

The Decs in degrees

source_fovs: tuple[float]

The size of each source to image in degrees

source_names: tuple[str]

The name of each source

source_ras: tuple[float]

The RAs in degrees

class flint.peel.potato.PotatoConfigCommand

Bases: NamedTuple

Container for potato configuration command results

command: str

The command string that should be executed

config_path: pathlib.Path

Path to the configuration file generated

class flint.peel.potato.PotatoConfigOptions

Bases: NamedTuple

Container class to hold options that go into the potatopy configuration creation software by Stefan Duchesne. See:

https://gitlab.com/Sunmish/potato

image_briggs: float = -1.5

Briggs robust parameter for the in-field image

image_channels: int = 4

Number of output channels for the in-field image

image_minuvl: float = 700

“Minimum (u,v)- distance in wavelengths for data to be selected

image_scale: float = 0.0006944

The pixel scale of the in-field image in degrees

image_size: int = 6148

Size of an in-field image

peel_channels: int = 16

Number of output channels for the peel images

peel_minuvl: float = 700

“Minimum (u,v)- distance in wavelengths for data to be selected for the peel image

peel_multiscale: bool = True

Whether multi-scale is to be used for the peel sources

peel_nmiter: int = 7

Number of major iterations allowed for the peel sources

peel_scale: float = 0.0006944

Pixel scale of the peel images in degrees

peel_size: int = 1000

Size of the peel image to make, in pixels

class flint.peel.potato.PotatoPeelArguments

Bases: NamedTuple

The mandatory arguments for potato peel.

decs: Collection[float]

The source Dec in degrees to peel

image_fov: float

The field-of-view in degrees of the main in-field image. If a sources is within this radius it is not peeled (because it would be imaged)

ms: pathlib.Path

The measurement set that will be examined for peeling

n: Collection[str]

Name of the source being peeled

peel_fovs: Collection[float]

The field-of-views that should be created for the peel source in degrees

ras: Collection[float]

The source RA in degrees to peel

class flint.peel.potato.PotatoPeelCommand

Bases: NamedTuple

Container to hold the items of the hot potato command

command: str

The hot potato command that will be executed

ms: flint.options.MS

The measurement set that potato has operated against

class flint.peel.potato.PotatoPeelOptions

Bases: NamedTuple

Container class to hold options that go to the potato peel software by Stefan Duchesne. FLINT uses the hot_potato version. ee:

https://gitlab.com/Sunmish/potato

with_options(**kwargs) → PotatoPeelOptions

c: pathlib.Path | None = None

Path to the potatopeel configuration file

calmode: str = 'P'

Self-calibration mode to use (see casatasks gaincal)

direct_subtract: bool = True

Whether a direct model subtraction (without self-cal) should be used ift he source is faint

intermediate_peels: bool = True

Creates an image after each calibration and subtraction loop to show iterative improvements of the subject peel source

minpeelflux: float = 0.5

Minimum flux, in Jy, for the peeling procedure (image->selfcal->image)

minuvimage: float | None = None

The minimum uv distance in wavelengths to use for imaging

minuvpeel: float | None = None

The minimum uv distance in wavelengths to use when attempting to self-calibrate

refant: int = 1

Reference antenna to use when solving for self-cal solutions

solint: float = 30

Solution interval to use when applying gaincal

tmp: str | pathlib.Path | None = None

Where the temporary wsclean files will be written to

flint.peel.potato._potato_config_command(config_path: pathlib.Path, potato_config_options: PotatoConfigOptions) → PotatoConfigCommand

Create the peel_configuration.py command that will be called in the potato singularity image. This is the CLI version of the code (not calling the python function).

Parameters:

• config_path (Path) – Output location of the configuration file

• potato_config_options (PotatoConfigOptions) – Instance of all the options to use

Returns:

The CLI command that will be executed to create a potato configuration file

Return type:

PotatoconfigCommand

flint.peel.potato._potato_options_to_command(potato_options: PotatoPeelArguments | PotatoConfigOptions | PotatoPeelOptions, skip_keys: Collection[str] | None = None, check_double_keys: bool = False) → str

Construct the CLI options that would be provided to a potato peel CLI program

Parameters:

• potato_options (Union[PotatoPeelArguments,PotatoConfigOptions, PotatoPeelOptions]) – An instance of one of the option classes to draw from

• skip_keys (Optional[Collection[str]], optional) – A collections of keys to ignore when build the CLI. If None all keys in the provided options instance are used. Defaults to None.

• check_double_leys (bool, optional) – Some long form names in hot_potato are single dash while others are double dash. This is not the case in the config creation tool. This will check to see if the double should be used. Defaults to False.

Raises:

TypeError – When an unrecognised data type is found in the provided options class

Returns:

A string of the CLI options and keys

Return type:

str

flint.peel.potato._potato_peel_command(ms: flint.options.MS, potato_peel_arguments: PotatoPeelArguments, potato_peel_options: PotatoPeelOptions) → PotatoPeelCommand

Construct the CLI command for hot_potato, and appropriately handle the mandatory and optional arguments.

Parameters:

• ms (MS) – The measurement set that will be peeled

• potato_peel_arguments (PotatoPeelArguments) – The mandatory arguments for hot_potato

• potato_peel_options (PotatoPeelOptions) – The hot_potato options to supply

Returns:

The hot_potato command that was constructed from the input PotatoPeelOptions

Return type:

PotatoPeelCommand

flint.peel.potato._prepare_potato_options(ms: flint.options.MS, potato_container: pathlib.Path, update_potato_config_options: dict[str, Any] | None = None, update_potato_peel_options: dict[str, Any] | None = None) → tuple[PotatoConfigOptions | None, PotatoPeelOptions]

Create the appropriate set of potato option class instances. This function will assess if a configuration file has been specified, and if not it will generate one from the potato configuration generator program. This is a call out to singularity.

Parameters:

• ms (MS) – The measurement set to be peeled

• potato_container (Path) – Path to the container that holds potato

• update_potato_config_options (dict[str, Any]) – Options to override defaults of the PotatoConfigOptions. Defaults to None.

• update_potato_peel_options (dict[str, Any]) – Options to override defaults of the PotatoPeelOptions. Defaults to None.

Returns:

The populated set of classes. If a user provide configuration was provided there None is returned in place of PotatoConfigOptions

Return type:

tuple[PotatoConfigOptions | None, PotatoPeelOptions]

flint.peel.potato._print_ms_colnames(ms: flint.options.MS) → flint.options.MS

A dummy function to print colnames in a MS table

flint.peel.potato.cli()

flint.peel.potato.create_run_potato_config(potato_container: pathlib.Path, ms_path: pathlib.Path | flint.options.MS, potato_config_options: PotatoConfigOptions) → PotatoConfigCommand

Construct and run a CLI command into the peel_configuration.py script of the potatopeel package.

Parameters:

• potato_container (Path) – Container with the potatopeel package installed

• ms_path (Union[Path, MS]) – Path to the measurement set that will be peeled

• potato_config_options (PotatoConfigOptions) – Options to tweak the values in the peel configuration

Returns:

Container of the path to the peel configuration file and the corresponding command that generated it

Return type:

PotatoConfigCommand

flint.peel.potato.create_run_potato_peel(potato_container: pathlib.Path, ms: flint.options.MS, potato_peel_arguments: PotatoPeelArguments, potato_peel_options: PotatoPeelOptions) → PotatoPeelCommand

Construct and run a hot_potato command to peel out sources from a measurement set.

Parameters:

• potato_container (Path) – Container with the potato peel software and appropriate tools (including wsclean)

• ms (MS) – The measurement set that contains sources to peel

• potato_peel_arguments (PotatoPeelArguments) – The mandatory arguments that go into hot_potato.

• potato_peel_options (PotatoPeelOptions) – Options that are supplied to hot_potato.

Returns:

The executed hot_potato command

Return type:

PotatoPeelCommand

flint.peel.potato.find_sources_to_peel(ms: flint.options.MS, image_options: flint.imager.wsclean.WSCleanOptions, field_idx: int = 0, maximum_offset: float = 30, minimum_apparent_brightness: float = 0.5, override_beam_position_with: astropy.coordinates.SkyCoord | None = None) → astropy.table.Table | None

Obtain a set of sources to peel from a reference candidate set. This will evaluate whether a source should be peels based on two criteria:

• if it is below a nominal primary beam cut off level (10 percent, assuming a gaussian primary beam)

• if the sources is within some separation of the imaging center

Parameters:

• ms (MS) – The measurement set that is being considered

• image_options (WSCleanOptions) – The imaging parameters that will be used to compute a placeholder WCS

• field_idx (int, optional) – Which field in the MS to draw the position from. Defaults to 0.

• maximum_offset (float, optional) – The largest separation, in degrees, before a source is ignored. Defaults to 30.0.

• minimum_apparent_brightness (float, optional) – The minimum apparent brightnessm, in Jy, a source should be before attempting to peel. Defaults to 0.5.

• override_beam_position_with (Optional[SkyCoord], optional) – Ignore the beam position of the input MS, instead use this. Do not rely on this option as it may be taken away. Defaults to None.

Returns:

Collection of sources to peel from the reference table. Column names are Name, RA, Dec, Aperture. This is the package table. If no sources need to be peeled None is returned.

Return type:

Union[Table,None]

flint.peel.potato.get_parser() → argparse.ArgumentParser

flint.peel.potato.get_source_props_from_table(table: astropy.table.Table) → NormalisedSources

Given the astropy table of known sources to peel, normalise their inputs for the potato peel CLI

Parameters:

table (Table) – Table of sources to peel

Returns:

Collection of normalised sources properties that will be provided to hot_potato

Return type:

NormalisedSources

flint.peel.potato.load_known_peel_sources() → astropy.table.Table

Locate and load the packaged set of known sources to peel. These sources are drawn from Duchesne et. al. (2023), Table 3.

Returns:

The astropy Table of candidate sources to remove.

Return type:

Table

flint.peel.potato.potato_peel(ms: flint.options.MS, potato_container: pathlib.Path, update_potato_config_options: dict[str, Any] | None = None, update_potato_peel_options: dict[str, Any] | None = None, image_options: flint.imager.wsclean.WSCleanOptions | None = None) → flint.options.MS

Peel out sources from a measurement set using PotatoPeel. Candidate sources from a known list of sources (see Table 3 or RACS-Mid paper) are considered.

Parameters:

• ms (MS) – The measurement set to peel out known sources

• potato_container (Path) – Location of container with potatopeel software installed

• update_potato_config_options (Optional[Dict[str, Any]], optional) – A dictionary with values to use to update the default options within the PotatoConfigOptions. If None use the defaults. Defaults to None.

• update_potato_peel_options (Optional[Dict[str, Any]], optional) – A dictionary with values to use to update the default options within the PotatoPeelOptions. If None use the defaults. Defaults to None.

• image_options (Optional[WSCleanOptions], optional) – Any imaging options that should be used to determine if sources require peeling (e.g. image size, pixel size)

Returns:

Updated measurement set

Return type:

MS

flint.peel.potato.prepare_ms_for_potato(ms: flint.options.MS) → flint.options.MS

The potatopeel software requires the data column being operated against to be called DATA. This is a requirement of CASA and its gaincal / applysolution task.

If there is already a DATA column and this is not the nominated data column described by the MS then it is removed, and the nominated data column is renamed.

If the DATA column already exists and it is the nominated column described by MS then this is returned. If there is a CORRECTED_DATA column in this situation it is removed.

Parameters:

ms (MS) – The measurement set that will be edited

Raises:

ValueError – Raised when a column name is expected but can not be found.

Returns:

measurement set with the data column moved into the correct location

Return type:

MS

flint.peel.potato.source_within_image_fov(source_coord: astropy.coordinates.SkyCoord, beam_coord: astropy.coordinates.SkyCoord, image_size: int, pixel_scale: astropy.units.Quantity | str) → bool

Evaluate whether a source will be within the field of view of an image.

Parameters:

• source_coord (SkyCoord) – The source position to consider

• beam_coord (SkyCoord) – The center beam position to consider

• image_size (int) – The image size. This assumes a square image.

• pixel_scale (Union[u.Quantity, str]) – The pixel size, assuming square pixels.

Returns:

Whether the source is expected to be in the field of view

Return type:

bool