flint.coadd.linmos

This is an interface into the yandasoft linmos task.

Attributes

EXPECTED_HOLOGRAPHY_ROTATION_CONSTANT_RADIANS

Classes

BoundingBox	Simple container to represent a bounding box
LinmosOptions	Container for options that direct linmos processing
LinmosParsetSummary	Container for key components around a linmos parset file
LinmosResult	A base class that Options style flint classes can inherit from.
TrimImageResult	The constructed path and the bounding box

Functions

_blank_zeros(→ int)	Blank linmos' 0.0 padding in place, returning how many pixels were blanked
_create_bound_box_plane(→ BoundingBox | None)	Create a bounding box around pixels in a 2D image. If all
_file_list_to_string(→ str)
_get_alpha_linmos_option(→ str)	Compute the appropriate alpha term for linmos that is used to
_get_holography_linmos_options(→ str)	Construct the appropriate set of linmos options that
_get_image_weight_plane(→ float)	Extract the inverse variance weight for an input plane of data
_linmos_cleanup(→ tuple[pathlib.Path, ...])	Clean up linmos files if requested.
_merge_bound_boxes(→ BoundingBox)	Construct the bounding box that encloses all input bounding boxes.
blank_zero_pixels(→ pathlib.Path)	Blank a linmos image's 0.0 padding, leaving its pixel grid alone.
cli(→ None)
compute_pb_rotation_alpha(→ float)	Compute the differential rotation, in radians, between a field's
create_bound_box(→ BoundingBox)	Construct a bounding box around finite pixels for a 2D image.
generate_linmos_parameter_set(→ LinmosParsetSummary)	Generate a parset file that will be used with the
generate_weights_list_and_files(→ tuple[pathlib.Path, ...])	Generate the expected linmos weight files, and construct an appropriate
get_image_weight(→ list[float])	Compute an image weight supplied to linmos, which is used for optimally
get_parser(→ argparse.ArgumentParser)
linmos_images() → LinmosResult)	Create a linmos parset file and execute it.
trim_fits_image(→ TrimImageResult)	Trim the FITS image produces by linmos to remove as many empty pixels around

Module Contents

class flint.coadd.linmos.BoundingBox(/, **data: Any)

Bases: capn_crunch.BaseOptions

Simple container to represent a bounding box

clip() → BoundingBox | None

Clip to original_shape, or None if the box falls entirely off it

Returns:

The clipped box, or None if nothing remains

Return type:

BoundingBox | None

original_shape: tuple[int, int]

The original shape of the image. If constructed against a cube this is the shape of a single plane.

xmax: int

Maximum x pixel, exclusive (i.e. slice ready)

xmin: int

Minimum x pixel

ymax: int

Maximum y pixel, exclusive (i.e. slice ready)

ymin: int

Minimum y pixel

class flint.coadd.linmos.LinmosOptions(/, **data: Any)

Bases: capn_crunch.BaseOptions

Container for options that direct linmos processing

base_output_name: pathlib.Path

Base name path of the output linmos produces, including parent path. This is provided to form LinmosNames. Defaults to ‘linmos_field’.

cleanup: bool = False

Remove files generated throughout linmos, including the text files with the channel weights. Defaults to False.

cutoff: float = 0.001

Pixels whose primary beam attenuation is below this cutoff value are blanked. Defaults to 0.001.

force_remove_leakage: bool | None = None

Overwrite the removeLeakage option to linmos. Defaults to None.

holofile: pathlib.Path | None = None

Path to a FITS cube produced by the holography processing pipeline. Used by linmos to appropriate primary-beam correct the images. Defaults to None.

overwrite: bool = False

Overwrite the linmos parset file generated if it exists. Defaults to False.

pol_axis: float | None = None

The physical oritentation of the ASKAP third-axis in radians. Defaults to None.

regrid_method: Literal['nearest', 'linear', 'cubic', 'lanczos'] = 'cubic'

Interpolation linmos regrids the inputs with. Its own default, ‘linear’, suppresses the peak of a source. Defaults to ‘cubic’.

remove_original_images: bool = False

Delete the images that were coaddede together. Defaults to False.

stokesi_images: list[pathlib.Path] | None = None

Collection of Stokes-I images used to correct widefield leakage when input images are Stokes Q or U. If None linmos will attempt to find them. Defaults to None.

trim_linmos_fits: bool = True

Attempt to trim the output linmos files of as much empty space as possible. Defaults to True.

class flint.coadd.linmos.LinmosParsetSummary

Bases: NamedTuple

Container for key components around a linmos parset file

image_paths: tuple[pathlib.Path, ...]

The set of paths to the fits images that were coadded together

parset_path: pathlib.Path

Path to the parset text file created

weight_text_paths: tuple[pathlib.Path, ...] | None = None

The set of Paths to the text files with per channel weights used by linmos

class flint.coadd.linmos.LinmosResult(/, **data: Any)

Bases: capn_crunch.BaseOptions

A base class that Options style flint classes can inherit from.

This is derived from pydantic.BaseModel, and can be used for validation of supplied values.

Class derived from BaseOptions are immutable by default, and have the docstrings of attributes extracted.

cmd: str

The yandasoft linmos task that will be executed

image_fits: pathlib.Path

Path to the output linmos image created (or will be).

parset: pathlib.Path

The output location that the generated linmos parset has been written to

weight_fits: pathlib.Path

Path to the output weight image formed through the linmos process

class flint.coadd.linmos.TrimImageResult

Bases: NamedTuple

The constructed path and the bounding box

bounding_box: BoundingBox

The bounding box that was applied to the image

path: pathlib.Path

The path to the trimmed image

flint.coadd.linmos._blank_zeros(data: numpy.ndarray) → int

Blank linmos’ 0.0 padding in place, returning how many pixels were blanked

flint.coadd.linmos._create_bound_box_plane(image_data: numpy.ndarray, is_masked: bool = False) → BoundingBox | None

Create a bounding box around pixels in a 2D image. If all pixels are not valid, then None is returned.

Parameters:

• image_data (np.ndarray) – The 2D image to construct a bounding box around

• is_masked (bool, optional) – Whether to treat the image as booleans or values. Defaults to False.

Returns:

None if no valid pixels, a bounding box with the (xmin,xmax,ymin,ymax) of valid pixels

Return type:

Optional[BoundingBox]

flint.coadd.linmos._file_list_to_string(file_list: collections.abc.Collection[pathlib.Path]) → str

flint.coadd.linmos._get_alpha_linmos_option(pol_axis: float | None = None) → str

Compute the appropriate alpha term for linmos that is used to describe the differential rotation of the ASKAP third-axis and the footprint layout. See compute_pb_rotation_alpha.

Parameters:

pol_axis (Optional[float], optional) – The prescribed polarisation axis value described in a MS. Defaults to None.

Returns:

Yandasoft linmos option to rotation the holography cubes

Return type:

str

flint.coadd.linmos._get_holography_linmos_options(holofile: pathlib.Path | None = None, pol_axis: float | None = None, remove_leakage: bool = False, stokesi_images: collections.abc.Collection[pathlib.Path] | None = None) → str

Construct the appropriate set of linmos options that describe the use of the holography cube file to primary beam correct the input images. This includes appropriately rotating the holography (see _get_alpha_linmos_options).

Parameters:

• holofile (Optional[Path], optional) – Path to the holography cube file to primary beam correct with. Defaults to None.

• pol_axis (Optional[float], optional) – The rotation of the third axis as described in an ASAKP MS. Defaults to None.

• remove_leakage (bool, optional) – Add the directive to remove leakage. Defaults to False.

Returns:

Set of linmos options to add to a parset file

Return type:

str

flint.coadd.linmos._get_image_weight_plane(image_data: numpy.ndarray, mode: Literal['std', 'mad'] = 'mad', stride: int = 4) → float

Extract the inverse variance weight for an input plane of data

Modes are ‘std’ or ‘mad’.

Parameters:

• image_data (np.ndarray) – Data to consider

• mode (str, optional) – Statistic computation mode. Defaults to “mad”.

• stride (int, optional) – Include every n’th pixel when computing the weight. ‘1’ includes all pixels. Defaults to 4.

Raises:

ValueError – Raised when mode is unknown

Returns:

The inverse variance weight computed

Return type:

float

flint.coadd.linmos._linmos_cleanup(linmos_parset_summary: LinmosParsetSummary) → tuple[pathlib.Path, ...]

Clean up linmos files if requested.

Parameters:

linmos_parset_summary (LinmosParsetSummary) – Parset summary from which the text file weights are gathered for deletion from

Returns:

Set of files removed

Return type:

Tuple[Path, …]

flint.coadd.linmos._merge_bound_boxes(bounding_boxes: collections.abc.Collection[BoundingBox]) → BoundingBox

Construct the bounding box that encloses all input bounding boxes.

Parameters:

bounding_boxes (Collection[BoundingBox]) – The boxes to merge together

Returns:

The smallest box containing all inputs

Return type:

BoundingBox

flint.coadd.linmos.blank_zero_pixels(image_path: pathlib.Path) → pathlib.Path

Blank a linmos image’s 0.0 padding, leaving its pixel grid alone.

linmos writes 0.0 where the primary beam falls below its cutoff, which is a blank rather than a measurement. Left as 0.0 it convolves into the data as though it were one, smearing the mosaic edge into small non-zero values that nothing downstream can separate from real faint pixels; blanked, the convolution carries the mask and the edge stays sharp.

trim_fits_image blanks as well, but the cube path turns trimming off to keep every channel on one pixel grid, so the blanking cannot ride with it.

Parameters:

image_path (Path) – The FITS image to blank, modified in place

Returns:

The blanked image

Return type:

Path

flint.coadd.linmos.cli() → None

flint.coadd.linmos.compute_pb_rotation_alpha(pol_axis: float) → float

Compute the differential rotation, in radians, between a field’s third-axis orientation and the frame the holography cube was measured in. The typical holography rotation is -45 degs. Internally the alpha term is computed as:

>>> pol_axis - EXPECTED_HOLOGRAPHY_ROTATION_CONSTANT_RADIANS

Used both to build linmos’s ASKAP_PB.alpha option (_get_alpha_linmos_option) and to directly sample a holography cube’s response for a rotated field (flint.misc.holo.sample_beam_response).

Parameters:

pol_axis (float) – The prescribed polarisation axis value described in a MS, in radians.

Returns:

The differential rotation, in radians

Return type:

float

flint.coadd.linmos.create_bound_box(image_data: numpy.ndarray, is_masked: bool = False) → BoundingBox

Construct a bounding box around finite pixels for a 2D image.

If a cube ids provided, the bounding box is constructed from pixels as broadcast across all of the non-spatial dimensions. That is to say the single bounding box can be projected across all channel/stokes channels

If is_mask` is ``False, the image_data will be masked internally using numpy.isfinite.

Parameters:

• image_data (np.ndarray) – The image data that will have a bounding box constructed for.

• is_masked (bool, optional) – if this is True the image_data are treated as a boolean mask array. Defaults to False.

Returns:

The tight bounding box around pixels.

Return type:

BoundingBox

flint.coadd.linmos.generate_linmos_parameter_set(images: collections.abc.Collection[pathlib.Path], linmos_names: flint.naming.LinmosNames, linmos_options: LinmosOptions, weight_list: str | None = None) → LinmosParsetSummary

Generate a parset file that will be used with the yandasoft linmos task.

Parameters:

• images (Collection[Path]) – The images that will be coadded into a single field image.

• linmos_names (LinmosNames) – Names of the output image and weights that linmos will produces. The weight image will have a similar name. Defaults to “linmos_field”.

• linmos_options (LinmosOptions) – Options that are passed through to the yandasoft linmos application.

• weight_list (str, optional) – If not None, this string will be embedded into the yandasoft linmos parset as-is. It should represent the formatted string pointing to weight files, and should be equal length of the input images. If None it is internally generated. Defaults to None.

Returns:

Important components around the generated parset file.

Return type:

LinmosParsetSummary

flint.coadd.linmos.generate_weights_list_and_files(image_paths: collections.abc.Collection[pathlib.Path], mode: str = 'mad', stride: int = 1) → tuple[pathlib.Path, ...]

Generate the expected linmos weight files, and construct an appropriate string that can be embedded into a linmos partset. These weights files will appear as:

>>> #Channel Weight
>>> 0 1234.5
>>> 1 6789.0

The weights should be correct relative to the entire set of input images. They do not necessarily have to correspond to an accurate measure of the RMS.

This function will create a corresponding text file for each input image. At the moment it is only intended to work on MFS images. It is not currently intended to be used on image cubes.

The stride parameter will only include every N’th pixel when computing the weights. A smaller set of pixels will reduce the time required to calculate the weights, but may come at the cost of accuracy with large values.

Parameters:

• image_paths (Collection[Path]) – Images to iterate over to create a corresponding weights.txt file.

• mode (str, optional) – The mode to use when calling get_image_weight

Returns:

A list of paths pointing to the weights for each input image

Return type:

Tuple[Path, …]

flint.coadd.linmos.get_image_weight(image_path: pathlib.Path, mode: str = 'mad', stride: int = 1, image_slice: int = 0) → list[float]

Compute an image weight supplied to linmos, which is used for optimally weighting overlapping images. Supported modes are ‘mad’ and ‘mtd’, which simply resolve to their numpy equivalents.

This weight is really a relative weight to used between all images in a set of images being co-added together. So long as these are all calculated in the same way, it does not necessarily have to correspond to an optimatelly calculated RMS.

The stride parameter will only include every N’th pixel when computing the weights. A smaller set of pixels will reduce the time required to calculate the weights, but may come at the cost of accuracy with large values.

Parameters:

• image (Path) – The path to the image fits file to inspect.

• mode (str, optional) – Which mode should be used when calculating the weight. Defaults to ‘mad’.

• stride (int, optional) – Include every n’th pixel when computing the weight. ‘1’ includes all pixels. Defaults to 1.

• image_slice (int, optional) – The image slice in the HDU list of the image fits file to inspect. Defaults to 0.

Raises:

ValueError – Raised when a mode is requested but does not exist

Returns:

The weight per channel to supply to linmos

Return type:

List[float]

flint.coadd.linmos.get_parser() → argparse.ArgumentParser

flint.coadd.linmos.linmos_images(images: collections.abc.Collection[pathlib.Path], linmos_options: LinmosOptions, parset_output_path: pathlib.Path | None = None, weight_list: str | None = None, container: pathlib.Path = Path('yandasoft.sif')) → LinmosResult

Create a linmos parset file and execute it.

Parameters:

• images (Collection[Path]) – The images that will be coadded into a single field image.

• linmos_options (LinmosOptions) – Options to control the yandasott linmos program and related features.

• parset_output_path (Path | None, optional) – Path of the output linmos parset file. If None it is derived from common input fields. Defaults to None.

• weight_list (str, optional) – If not None, this string will be embedded into the yandasoft linmos parset as-is. It should represent the formatted string pointing to weight files, and should be equal length of the input images. If None it is internally generated. Defaults to None.

Returns:

The linmos command executed and the associated parset file

Return type:

LinmosResult

flint.coadd.linmos.trim_fits_image(image_path: pathlib.Path, bounding_box: BoundingBox | None = None) → TrimImageResult

Trim the FITS image produces by linmos to remove as many empty pixels around the border of the image as possible. This is an inplace operation. Pixels that have a value of 0.0 are first filled with nan values before trimming.

Parameters:

• image_path (Path) – The FITS image that will have its border trimmed

• bounding_box (Optional[BoundingBox], optional) – The bounding box that will be applied to the image. If None it is computed. Defaults to None.

Returns:

Path of the FITS image that had its border trimmed

Return type:

Path

flint.coadd.linmos.EXPECTED_HOLOGRAPHY_ROTATION_CONSTANT_RADIANS