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
`TrimImageResult`	The constructed path and the bounding box

Functions¶

`_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, Ellipsis])	Clean up linmos files if requested.
`cli`(→ None)
`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[source]¶

Bases: NamedTuple

Simple container to represent a bounding box

original_shape: tuple[int, int][source]¶: The original shape of the image. If constructed against a cube this is the shape of a single plane.

xmax: int[source]¶: Maximum x pixel

xmin: int[source]¶: Minimum x pixel

ymax: int[source]¶: Maximum y pixel

ymin: int[source]¶: Minimum y pixel

class flint.coadd.linmos.LinmosOptions(/, **data: Any)[source]¶

Bases: flint.options.BaseOptions

Container for options that direct linmos processing

base_output_name: pathlib.Path[source]¶: Base name path of the output linmos produces, including parent path. This is provided to form LinmosNames. Defaults to ‘linmos_field’.

cleanup: bool = False[source]¶: Remove files generated throughout linmos, including the text files with the channel weights. Defaults to False.

cutoff: float = 0.001[source]¶: Pixels whose primary beam attenuation is below this cutoff value are blanked. Defaults to 0.001.

force_remove_leakage: bool | None = None[source]¶: Overwrite the removeLeakage option to linmos. Defaults to None.

holofile: pathlib.Path | None = None[source]¶: 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[source]¶: Overwrite the linmos parset file generated if it exists. Defaults to False.

pol_axis: float | None = None[source]¶: The physical oritentation of the ASKAP third-axis in radians. Defaults to None.

remove_original_images: bool = False[source]¶: Delete the images that were coaddede together. Defaults to False.

stokesi_images: list[pathlib.Path] | None = None[source]¶: 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[source]¶: Attempt to trim the output linmos files of as much empty space as possible. Defaults to True.

class flint.coadd.linmos.LinmosParsetSummary[source]¶

Bases: NamedTuple

Container for key components around a linmos parset file

image_paths: tuple[pathlib.Path, Ellipsis][source]¶: The set of paths to the fits images that were coadded together

parset_path: pathlib.Path[source]¶: Path to the parset text file created

weight_text_paths: tuple[pathlib.Path, Ellipsis] | None = None[source]¶: The set of Paths to the text files with per channel weights used by linmos

class flint.coadd.linmos.LinmosResult(/, **data: Any)[source]¶

Bases: flint.options.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[source]¶: The yandasoft linmos task that will be executed

image_fits: pathlib.Path[source]¶: Path to the output linmos image created (or will be).

parset: pathlib.Path[source]¶: The output location that the generated linmos parset has been written to

weight_fits: pathlib.Path[source]¶: Path to the output weight image formed through the linmos process

class flint.coadd.linmos.TrimImageResult[source]¶

Bases: NamedTuple

The constructed path and the bounding box

bounding_box: BoundingBox[source]¶: The bounding box that was applied to the image

path: pathlib.Path[source]¶: The path to the trimmed image

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

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: Collection[pathlib.Path]) → str[source]¶

flint.coadd.linmos._get_alpha_linmos_option(pol_axis: float | None = None) → str[source]¶

Compute the appropriate alpha term for linmos that is used to describe the differential rotation of the ASKAP third-axis and the footprint layout. The typical holography rotation is -45 degs. Internally the alpha term is computed as:

>>> pol_axis - EXPECTED_HOLOGRAPHY_ROTATION_CONSTANT_RADIANS

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: Collection[pathlib.Path] | None = None) → str[source]¶

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[source]¶

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 1.

Raises:

ValueError – Raised when modes unknown

Returns:

The inverse variance weight computerd

Return type:

float

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

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.cli() → None[source]¶

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

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: Collection[pathlib.Path], linmos_names: flint.naming.LinmosNames, linmos_options: LinmosOptions, weight_list: str | None = None) → LinmosParsetSummary[source]¶

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: Collection[pathlib.Path], mode: str = 'mad', stride: int = 1) → tuple[pathlib.Path, Ellipsis][source]¶

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][source]¶

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.

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[source]¶

flint.coadd.linmos.linmos_images(images: 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[source]¶

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[source]¶

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[source]¶