astrohack

Submodules

Classes

`AstrohackPointFile`	Data class for point data.
`AstrohackLocitFile`	Data class for locit data.
`AstrohackHologFile`	Data class for holog data.
`AstrohackPanelFile`	Data class for panel data.
`AstrohackBeamcutFile`	Data class for beam cut data.
`AstrohackPositionFile`	Data class for position data.
`AstrohackImageFile`	Data class for image data.

Functions

`open_beamcut`(...)	Open beamcut file and return instance of the beamcut data object. Object includes summary function to list available nodes.
`open_pointing`(...)	Open pointing file and return instance of the pointing data object. Object includes summary function to list available dictionary keys.
`open_holog`(...)	Open holog file and return instance of the holog data object. Object includes summary function to list available dictionary keys.
`open_image`(...)	Open image file and return instance of the image data object. Object includes summary function to list available dictionary keys.
`open_locit`(...)	Open locit file and return instance of the locit data object. Object includes summary function to list available dictionary keys.
`open_panel`(...)	Open panel file and return instance of the panel data object. Object includes summary function to list available dictionary keys.
`open_position`(...)	Open position file and return instance of the position data object. Object includes summary function to list available dictionary keys.
`extract_holog`(...)	Extract holography and optionally pointing data, from measurement set. Creates holography output file.
`generate_holog_obs_dict`(...)	Generate holography observation dictionary, from measurement set..
`beamcut`(holog_name[, beamcut_name, ant, ddi, ...])	Process beamcut data from a .holog.zarr file to produce reports and plots.
`extract_pointing`(...)	Extract pointing data from measurement set. Creates holography output file.
`holog`(, to_stokes, overwrite, parallel, None])	Process holography data and derive aperture illumination pattern.
`panel`(image_name[, panel_name, clip_type, clip_level, ...])	Analyze holography images to derive panel adjustments
`combine`(...)	Combine DDIs in a Holography image to increase SNR
`locit`(locit_name[, position_name, elevation_limit, ...])	Extract Antenna position determination data from an MS and stores it in a locit output file.
`extract_locit`(cal_table[, locit_name, ant, ddi, overwrite])	Extract Antenna position determination data from an MS and stores it in a locit output file.
`cassegrain_ray_tracing_pipeline`(output_xds_filename, ...)	Execute the cassegrain ray tracing pipeline to determine phase effects caused by optical mis-alignments.
`create_ray_tracing_telescope_parameter_dict`([...])	Create a dictionary with a cassegrain telescope parameters
`plot_2d_maps_from_rt_xds`(rt_xds_filename, keys, rootname)	Plot 2D maps of keys in the ray tracing Xarray Dataset
`plot_radial_projection_from_rt_xds`(rt_xds_filename, ...)	Plot a radial projection of some of the rays simulated in the ray tracing Xarray Dataset.
`apply_holog_phase_fitting_to_rt_xds`(rt_xds_filename, ...)	Feed phase image from ray tracing Xarray dataset to Astrohak's default phase fitting tool for VLA data.
`compare_fits_images`(image, reference_image, ...[, ...])	Compares a set of images to a set of reference images.
`rms_table_from_zarr_datatree`(zarr_data_tree, table_file)	Goes through the data in a zarr DataTree created by compare_fits_images.
`get_proper_telescope`(name[, antenna_name])	Retrieve the proper telescope object based on the name

Package Contents

open_beamcut(file: str) → astrohack.io.beamcut_mds.AstrohackBeamcutFile | None[source]

Open beamcut file and return instance of the beamcut data object. Object includes summary function to list available nodes.

Parameters:: file (str) – Path to beamcut file.
Returns:: beamcut object; None if file not found.
Return type:: AstrohackBeamcutFile

AstrohackBeamcutFile Beamcu object allows the user to access beam cut data via a xarray data tree, in order of depth, ant -> ddi -> cut. The beamcut object also provides a summary() helper function to list available nodes for each file. An outline of the beam object structure is show below:

beamcut_mds =
    {
        ant_0:{
            ddi_0:{
                 cut_0: beamcut_ds,
                     ⋮
                 cut_n: beamcut_ds
            },
            ⋮
            ddi_n: …
        },
        ⋮
        ant_n: …
    }

open_pointing(file: str) → astrohack.io.point_mds.AstrohackPointFile | None[source]

Open pointing file and return instance of the pointing data object. Object includes summary function to list available dictionary keys.

Parameters:: file (str) – Path to pointing file.
Returns:: Holography pointing object; None if file does not exist.
Return type:: AstrohackPointFile

AstrohackPointFile Pointing object allows the user to access pointing data via dictionary key with value based on ant. The pointing object also provides a summary() helper function to list available keys for each file. An outline of the pointing object structure is show below:

point_mds =
    {
        ant_0: point_ds,
        ⋮
        ant_n: point_ds
    }

open_holog(file: str) → astrohack.io.holog_mds.AstrohackHologFile | None[source]

Open holog file and return instance of the holog data object. Object includes summary function to list available dictionary keys.

Parameters:: file (str) – Path to holog file.
Returns:: Holography holog object; None if file not found.
Return type:: AstrohackHologFile

AstrohackHologFile Holog object allows the user to access holog data via compound dictionary keys with values, in order of depth, ddi -> map -> ant. The holog object also provides a summary() helper function to list available keys for each file. An outline of the holog object structure is show below:

holog_mds =
    {
        ant_0:{
            ddi_0:{
                 map_0: holog_ds,
                     ⋮
                 map_n: holog_ds
            },
            ⋮
            ddi_p: …
        },
    ⋮
    ant_m: …
    }

open_image(file: str) → astrohack.io.image_mds.AstrohackImageFile | None[source]

Open image file and return instance of the image data object. Object includes summary function to list available dictionary keys.

Parameters:: file (str) – Path to image file.
Returns:: Holography image object; None if file not found.
Return type:: AstrohackImageFile

AstrohackImageFile Image object allows the user to access image data via compound dictionary keys with values, in order of depth, ant -> ddi. The image object also provides a summary() helper function to list available keys for each file. An outline of the image object structure is show below:

image_mds =
    {
        ant_0:{
            ddi_0: image_ds,
            ⋮
            ddi_m: image_ds
        },
        ⋮
        ant_n: …
    }

open_locit(file: str) → astrohack.io.locit_mds.AstrohackLocitFile | None[source]

Open locit file and return instance of the locit data object. Object includes summary function to list available dictionary keys.

Parameters:: file (str) – Path of locit file.
Returns:: locit object; None if file not found.
Return type:: AstrohackLocitFile

AstrohackLocitFile Locit object allows the user to access locit data via compound dictionary keys with values, in order of depth, ant -> ddi. The locit object also provides a summary() helper function to list available keys for each file. An outline of the locit object structure is show below:

locit_mds =
    {
        ant_0:{
            ddi_0: locit_ds,
            ⋮
            ddi_m: locit_ds
        },
        ⋮
        ant_n: …
    }

open_panel(file: str) → astrohack.io.panel_mds.AstrohackPanelFile | None[source]

Open panel file and return instance of the panel data object. Object includes summary function to list available dictionary keys.

Parameters:: file (str) – Path ot panel file.
Returns:: Holography panel object; None if file not found.
Return type:: AstrohackPanelFile

AstrohackPanelFile Panel object allows the user to access panel data via compound dictionary keys with values, in order of depth, ant -> ddi. The panel object also provides a summary() helper function to list available keys for each file. An outline of the panel object structure is show below:

panel_mds =
    {
        ant_0:{
            ddi_0: panel_ds,
            ⋮
            ddi_m: panel_ds
        },
        ⋮
        ant_n: …
    }

open_position(file: str) → astrohack.io.position_mds.AstrohackPositionFile | None[source]

Open position file and return instance of the position data object. Object includes summary function to list available dictionary keys.

Parameters:: file (str) – Path of position file.
Returns:: position object; None if file does not exist.
Return type:: AstrohackPositionFile

AstrohackPositionFile position object allows the user to access position data via compound dictionary keys with values, in order of depth, ant -> ddi. The position object also provides a summary() helper function to list available keys for each file. An outline of the position object structure is show below:

position_mds =
    {
        ant_0:{
            ddi_0: position_ds,
            ⋮
            ddi_m: position_ds
        },
        ⋮
        ant_n: …
    }

class AstrohackPointFile(file: str)[source]

Bases: astrohack.io.base_mds.AstrohackBaseFile

Data class for point data.

Data within an object of this class can be selected for further inspection, plotted or produce a report

Plot Pointing for antennas in time.

Parameters:

destination (str) – Name of the destination folder to contain plot(s)
ant (str, list, optional) – Antenna(s) to plot, default is “all”
pointing_key (str, optional) – Which xds pointing data key to plot, defaults to “DIRECTIONAL_COSINES”
plot_antennas_separately (bool, optional) – Create an individual plot file for each antenna?
azel_unit (str, optional) – Unit for Azimuth and Elevation in the plot(s), valid values are trigonometric units, default is deg
time_unit (str, optional) – Unit for time in the plot(s), valid values are time units, default is hour
az_scale (Union[Tuple, List[float], np.array], optional) – Azimuth plot limits, defaults to all Azimuths present when None.
el_scale (Union[Tuple, List[float], np.array], optional) – Elevation plot limits, defaults to all Elevations present when None.
time_scale (Union[Tuple, List[float], np.array], optional) – Time plot limits, defaults to all times present when None
display (bool, optional) – Display plot(s) inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300

Plot antenna pointing info in time together in one plot, or individually for each antenna.

Plot antenna positions.

Parameters:

destination (str) – Name of the destination folder to contain plot
stations (bool, optional) – Add station names to the plot, defaults to True
zoff (bool, optional) – Add Elevation offsets to the plots, defaults to False
unit (str, optional) – Unit for the plot, valid values are length units, default is km
box_size (int, float, optional) – Size of the box for plotting the inner part of the array in unit, when none the box size is 20% of the total size of the array, default is None
display (bool, optional) – Display plots inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300

Plot the array configuration from the antenna positions.

set_antennas_as_reference(reference_antennas: str | list[str] | tuple[str], write_changes: bool = True) → None[source]

Modify point_mds data to make specific antennas reference antennas, useful for older datasets that contain wrong pointing data for reference antennas.

Parameters:

reference_antennas (Union[str, list[str], tuple[str]]) – Antennas to transform into reference antennas
write_changes (bool, optional) – Write the modified mds to disk?

class AstrohackLocitFile(file: str)[source]

Bases: astrohack.io.base_mds.AstrohackBaseFile

Data class for locit data.

Data within an object of this class can be selected for further inspection, plotted or produce a report

print_source_table() → None[source]: Prints a table with the sources observed for antenna location determination

print_array_configuration(relative: bool = True) → None[source]

Prints a table containing the array configuration

Parameters:: relative (bool, optional) – Print antenna coordinates relative to array center or in geocentric coordinates, default is True

Print arrayx configuration in the dataset. Also marks the reference antenna and the antennas that are absent from the dataset. Coordinates of antenna stations can be relative to the array center or Geocentric (longitude, latitude and radius)

plot_source_positions(destination: str, labels: bool = True, precessed: bool = False, display: bool = False, figure_size: Tuple | List[float | int] | numpy.ndarray | None = None, dpi: int = 300) → None[source]

Plot source positions in either FK5 or precessed right ascension and declination.

Parameters:

destination (str) – Name of the destination folder to contain plot
labels (bool, optional) – Add source labels to the plot, defaults to False
precessed (bool, optional) – Plot in precessed coordinates? defaults to False (FK5)
display (bool, optional) – Display plots inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300

Plot the sources on the source list to a full 24 hours 180 degrees flat 2D representation of the full sky. If precessed is set to True the coordinates precessd to the midpoint of the observations is plotted, otherwise the FK5 coordinates are plotted. The source names can be plotted next to their positions if label is True, however plots may become too crowded if that is the case.

Plot antenna positions.

Parameters:

destination (str) – Name of the destination folder to contain plot
stations (bool, optional) – Add station names to the plot, defaults to True
zoff (bool, optional) – Add Elevation offsets to the plots, defaults to False
unit (str, optional) – Unit for the plot, valid values are length units, default is km
box_size (int, float, optional) – Size of the box for plotting the inner part of the array in unit, when none the box size is 20% of the total size of the array, default is None
display (bool, optional) – Display plots inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300

Plot the array configuration from the antenna positions.

class AstrohackHologFile(file: str)[source]

Bases: astrohack.io.base_mds.AstrohackBaseFile

Data class for holog data.

Data within an object of this class can be selected for further inspection, plotted or produce a report

Plot diagnostic calibration plots from the holography data file.

Parameters:

destination (str) – Name of the destination folder to contain diagnostic plots
delta (float, optional) – Defines a fraction of cell_size around which to look for peaks., defaults to 0.01
ant (list or str, optional) – antenna ID to use in subselection, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – data description ID to use in subselection, defaults to “all” when None, ex. 0
map_id (list or int, optional) – map ID to use in subselection. This relates to which antenna are in the mapping vs. scanning configuration, defaults to “all” when None, ex. 0
complex_split (str, optional) – How to split complex data, cartesian (real + imaginary) or polar (amplitude + phase), default is polar
display (bool, optional) – Display plots inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300
parallel (bool, optional) – Run in parallel, defaults to False

Additional Information The visibilities extracted by extract_holog are complex due to the nature of interferometric measurements. To ease the visualization of the complex data it can be split into real and imaginary parts (cartesian) or in amplitude and phase (polar).

Available complex splitting possibilities:

cartesian: Split is done to a real part and an imaginary part in the plots
polar: Split is done to an amplitude and a phase in the plots

Plot directional cosine coverage.

Parameters:

destination (str) – Name of the destination folder to contain plots
ant (list or str, optional) – antenna ID to use in subselection, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – data description ID to use in subselection, defaults to “all” when None, ex. 0
map_id (list or int, optional) – map ID to use in subselection. This relates to which antenna are in the mapping vs. scanning configuration, defaults to “all” when None, ex. 0
angle_unit (str, optional) – Unit for L and M axes in plots, default is ‘deg’.
time_unit (str, optional) – Unit for time axis in plots, default is ‘hour’.
plot_correlation (str, list, optional) – Which correlation to plot against L and M, default is None (no correlation plots).
complex_split (str, optional) – How to split complex data, cartesian (real + imaginary) or polar (amplitude + phase), default is polar
phase_unit (str) – Unit for phase in ‘polar’ plots, default is ‘deg’.
display (bool, optional) – Display plots inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300
parallel (bool, optional) – Run in parallel, defaults to False

Additional Information The visibilities extracted by extract_holog are complex due to the nature of interferometric measurements. To ease the visualization of the complex data it can be split into real and imaginary parts (cartesian) or in amplitude and phase (polar).

Available complex splitting possibilities:

cartesian: Split is done to a real part and an imaginary part in the plots
polar: Split is done to an amplitude and a phase in the plots

Plotting correlations:

RR, RL, LR, LL: Are available for circular systems
XX, XY, YX, YY: Are available for linear systems
all: Plot all correlations in dataset

Export data compatible to AIPS’s HOLOG task

Parameters:

destination (str) – Name of the destination folder to contain ASCII files
ant (list or str, optional) – antenna ID to use in subselection, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – data description ID to use in subselection, defaults to “all” when None, ex. 0
map_id (list or int, optional) – map ID to use in subselection. This relates to which antenna are in the mapping vs. scanning configuration, defaults to “all” when None, ex. 0
parallel (bool, optional) – Run in parallel, defaults to False

Additional Information

This method converts the data for an Antenna mapping to the ASCII format used by AIPS’s HOLOG task. Currently only stokes I is supported.

observation_summary(summary_file: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', map_id: int | List[int] | str = 'all', az_el_key: str = 'center', phase_center_unit: str = 'radec', az_el_unit: str = 'deg', time_format: str = '%d %h %Y, %H:%M:%S', tab_size: int = 3, print_summary: bool = True, parallel: bool = False) → None[source]

Create a Summary of observation information

Parameters:

summary_file (str) – Text file to put the observation summary
ant (list or str, optional) – antenna ID to use in subselection, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – data description ID to use in subselection, defaults to “all” when None, ex. 0
map_id (list or int, optional) – map ID to use in subselection. This relates to which antenna are in the mapping vs. scanning configuration, defaults to “all” when None, ex. 0
az_el_key (str, optional) – What type of Azimuth & Elevation information to print, ‘mean’, ‘median’ or ‘center’, default is ‘center’
phase_center_unit (str, optional) – What unit to display phase center coordinates, ‘radec’ and angle units supported, default is ‘radec’
az_el_unit (str, optional) – Angle unit used to display Azimuth & Elevation information, default is ‘deg’
time_format (str, optional) – datetime time format for the start and end dates of observation, default is “%d %h %Y, %H:%M:%S”
tab_size (int, optional) – Number of spaces in the tab levels, default is 3
print_summary (bool, optional) – Print the summary at the end of execution, default is True
parallel (bool, optional) – Run in parallel, defaults to False

Additional Information

This method produces a summary of the data in the AstrohackHologFile displaying general information, spectral information and suggested beam image characteristics.

class AstrohackPanelFile(file: str)[source]

Bases: astrohack.io.base_mds.AstrohackBaseFile

Data class for panel data.

Data within an object of this class can be selected for further inspection, plotted or produce a report

get_antenna(ant: str, ddi: int) → astrohack.antenna.antenna_surface.AntennaSurface[source]

Retrieve an AntennaSurface object for interaction

Parameters:

ant (str) – Antenna to be retrieved, ex. ea25.
ddi (int) – DDI to be retrieved for ant_id, ex. 0

Returns:

AntennaSurface object describing for further interaction

Return type:

AntennaSurface

Export screw adjustments to text files and optionally plots.

Parameters:

destination (str) – Name of the destination folder to contain exported screw adjustments
ant (list or str, optional) – List of antennas/antenna to be exported, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be exported, defaults to “all” when None, ex. 0
unit (str, optional) – Unit for screws adjustments, most length units supported, defaults to “mm”
threshold (float, optional) – Threshold below which data is considered negligible, value is assumed to be in the same unit as the plot, if not given defaults to 10% of the maximal deviation
panel_labels (bool, optional) – Add panel labels to antenna surface plots, default is True
display (bool, optional) – Display plots inline or suppress, defaults to True
colormap (str, optional) – Colormap for screw adjustment map, default is RdBu_r
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the screw adjustment map size in inches
dpi (int, optional) – Screw adjustment map resolution in pixels per inch, default is 300
parallel (bool, optional) – Produce screw maps and screw adjustments in parallel

Produce the screw adjustments from astrohack.panel results to be used at the antenna site to improve the antenna surface

Create diagnostic plots of antenna surfaces from panel data file.

Parameters:

destination (str) – Name of the destination folder to contain plots
ant (list or str, optional) – List of antennas/antenna to be plotted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be plotted, defaults to “all” when None, ex. 0
plot_type (str, optional) – type of plot to be produced, deviation, phase, ancillary or all, default is deviation
plot_screws (bool, optional) – Add screw positions to plot
amplitude_limits (numpy.ndarray, list, tuple, optional) – Lower than Upper limit for amplitude in volts default is None (Guess from data)
phase_unit (str, optional) – Unit for phase plots, defaults is ‘deg’
phase_limits (numpy.ndarray, list, tuple, optional) – Lower than Upper limit for phase, value in phase_unit, default is None (Guess from data)
deviation_unit (str, optional) – Unit for deviation plots, defaults is ‘mm’
deviation_limits (numpy.ndarray, list, tuple, optional) – Lower than Upper limit for deviation, value in deviation_unit, default is None (Guess from data)
panel_labels (bool, optional) – Add panel labels to antenna surface plots, default is False
display (bool, optional) – Display plots inline or suppress, defaults to True
colormap (str, optional) – Colormap for plots, default is viridis
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300
parallel (bool, optional) – If True will use an existing astrohack client to produce plots in parallel, default is False

Produce plots from astrohack.panel results to be analyzed to judge the quality of the results

Additional Information .. rubric:: Available plot types: - deviation: Surface deviation estimated from phase and wavelength, three plots are produced for each antenna and ddi combination, surface before correction, the corrections applied and the corrected surface, most length units available - phase: Phase deviations over the surface, three plots are produced for each antenna and ddi combination, phase before correction, the corrections applied and the corrected phase, deg and rad available as units - ancillary: Two ancillary plots with useful information: The mask used to select data to be fitted, the amplitude data used to derive the mask, units are irrelevant for these plots - all: All the plots listed above. In this case the unit parameter is taken to mean the deviation unit, the phase unit is set to degrees

export_to_fits(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', parallel: bool = False) → None[source]

Export contents of an Astrohack MDS file to several FITS files in the destination folder

Parameters:

destination (str) – Name of the destination folder to contain plots
ant (list or str, optional) – List of antennas/antenna to be plotted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be plotted, defaults to “all” when None, ex. 0
parallel (bool, optional) – If True will use an existing astrohack client to export FITS in parallel, default is False

Export the products from the panel mds onto FITS files to be read by other software packages

Additional Information

The FITS fils produced by this method have been tested and are known to work with CARTA and DS9

Compute estimated antenna gains in dB and saves them to ASCII files.

Parameters:

destination (str) – Name of the destination folder to contain ASCII files
ant (list or str, optional) – List of antennas/antenna to be exported, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be exported, defaults to “all” when None, ex. 0
wavelengths (list or float, optional) – List of wavelengths at which to compute the gains.
wavelength_unit (str, optional) – Unit for the wavelengths being used, default is cm.
frequencies (list or float, optional) – List of frequencies at which to compute the gains.
frequency_unit (str, optional) – Unit for the frequencies being used, default is GHz.
rms_unit (str, optional) – Unit for the Antenna surface RMS, default is mm.
parallel (bool, optional) – If True will use an existing astrohack client to produce ASCII files in parallel, default is False

Export antenna gains in dB from astrohack.panel for analysis.

Additional Information

Selecting frequencies and wavelengths:

If neither a frequency list nor a wavelength list is provided, export_gains_table will try to use a predefined list set for the telescope associated with the dataset. If both are provided, export_gains_table will combine both lists.

observation_summary(summary_file: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', az_el_key: str = 'center', phase_center_unit: str = 'radec', az_el_unit: str = 'deg', time_format: str = '%d %h %Y, %H:%M:%S', tab_size: int = 3, print_summary: bool = True, parallel: bool = False) → None[source]

Create a Summary of observation information

Parameters:

summary_file (str) – Text file to put the observation summary
ant (list or str, optional) – antenna ID to use in subselection, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – data description ID to use in subselection, defaults to “all” when None, ex. 0
az_el_key (str, optional) – What type of Azimuth & Elevation information to print, ‘mean’, ‘median’ or ‘center’, default is ‘center’
phase_center_unit (str, optional) – What unit to display phase center coordinates, ‘radec’ and angle units supported, default is ‘radec’
az_el_unit (str, optional) – Angle unit used to display Azimuth & Elevation information, default is ‘deg’
time_format (str, optional) – datetime time format for the start and end dates of observation, default is “%d %h %Y, %H:%M:%S”
tab_size (int, optional) – Number of spaces in the tab levels, default is 3
print_summary (bool, optional) – Print the summary at the end of execution, default is True
parallel (bool, optional) – Run in parallel, defaults to False

Additional Information

This method produces a summary of the data in the AstrohackPanelFile displaying general information, spectral information, beam image characteristics and aperture image characteristics.

class AstrohackBeamcutFile(file: str)[source]

Bases: astrohack.io.base_mds.AstrohackBaseFile

Data class for beam cut data.

Data within an object of this class can be selected for further inspection, plotted or produce a report

observation_summary(summary_file: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', az_el_key: str = 'center', phase_center_unit: str = 'radec', az_el_unit: str = 'deg', time_format: str = '%d %h %Y, %H:%M:%S', tab_size: int = 3, print_summary: bool = True, parallel: bool = False) → None[source]

Create a Summary of observation information

Parameters:

summary_file (str) – Text file to put the observation summary
ant (list or str, optional) – antenna ID to use in subselection, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – data description ID to use in subselection, defaults to “all” when None, ex. 0
az_el_key (str, optional) – What type of Azimuth & Elevation information to print, ‘mean’, ‘median’ or ‘center’, default is ‘center’
phase_center_unit (str, optional) – What unit to display phase center coordinates, ‘radec’ and angle units supported, default is ‘radec’
az_el_unit (str, optional) – Angle unit used to display Azimuth & Elevation information, default is ‘deg’
time_format (str, optional) – datetime time format for the start and end dates of observation, default is “%d %h %Y, %H:%M:%S”
tab_size (int, optional) – Number of spaces in the tab levels, default is 3
print_summary (bool, optional) – Print the summary at the end of execution, default is True
parallel (bool, optional) – Run in parallel, defaults to False

Returns:

None

Return type:

NoneType

Additional Information

This method produces a summary of the data in the AstrohackBeamcutFile displaying general information, spectral information, beam image characteristics and aperture image characteristics.

plot_beamcut_in_amplitude(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', lm_unit: str = 'amin', azel_unit: str = 'deg', y_scale: list[float | int] | None = None, display: bool = False, dpi: int = 300, parallel: bool = False) → None[source]

Plot beamcuts contained in the beamcut_mds in amplitude

Parameters:

destination (str) – Directory into which to save plots.
ant (list or str, optional) – Antenna ID to use in subselection, e.g. ea25, defaults to “all”.
ddi (list or int, optional) – Data description ID to use in subselection, e.g. 0, defaults to “all”.
lm_unit (str, optional) – Unit for L/M offsets, default is “amin”.
azel_unit (str, optional) – Unit for Az/El information, default is “deg”.
y_scale (str, optional) – Set the y scale for the plots.
display (bool, optional) – Display plots during execution, default is False.
dpi (int, optional) – Pixel resolution for plots, default is 300.
parallel (bool, optional) – Run in parallel, defaults to False.

Returns:

None

Return type:

NoneType

Plot beamcuts contained in the beamcut_mds in attenuation

Parameters:

destination (str) – Directory into which to save plots.
ant (list or str, optional) – Antenna ID to use in subselection, e.g. ea25, defaults to “all”.
ddi (list or int, optional) – Data description ID to use in subselection, e.g. 0, defaults to “all”.
lm_unit (str, optional) – Unit for L/M offsets, default is “amin”.
azel_unit (str, optional) – Unit for Az/El information, default is “deg”.
y_scale (str, optional) – Set the y scale for the plots.
display (bool, optional) – Display plots during execution, default is False.
dpi (int, optional) – Pixel resolution for plots, default is 300.
parallel (bool, optional) – Run in parallel, defaults to False.

Returns:

None

Return type:

NoneType

plot_beamcut_lm_offsets(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', lm_unit: str = 'amin', azel_unit: str = 'deg', display: bool = False, dpi: int = 300, parallel: bool = False) → None[source]

Plot beamcuts contained in the beamcut_mds over the sky

Parameters:

destination (str) – Directory into which to save plots.
ant (list or str, optional) – Antenna ID to use in subselection, e.g. ea25, defaults to “all”.
ddi (list or int, optional) – Data description ID to use in subselection, e.g. 0, defaults to “all”.
lm_unit (str, optional) – Unit for L/M offsets, default is “amin”.
azel_unit (str, optional) – Unit for Az/El information, default is “deg”.
display (bool, optional) – Display plots during execution, default is False.
dpi (int, optional) – Pixel resolution for plots, default is 300.
parallel (bool, optional) – Run in parallel, defaults to False.

Returns:

None

Return type:

NoneType

plot_beamcut_in_phase(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', lm_unit: str = 'amin', azel_unit: str = 'deg', phase_unit: str = 'deg', phase_scale: List[float] | Tuple[float] | numpy.ndarray | None = None, display: bool = False, dpi: int = 300, parallel: bool = False) → None[source]

Plot beamcuts contained in the beamcut_mds in phase

Parameters:

destination (str) – Directory into which to save plots.
ant (list or str, optional) – Antenna ID to use in subselection, e.g. ea25, defaults to “all”.
ddi (list or int, optional) – Data description ID to use in subselection, e.g. 0, defaults to “all”.
lm_unit (str, optional) – Unit for L/M offsets, default is “amin”.
azel_unit (str, optional) – Unit for Az/El information, default is “deg”.
phase_unit (str, optional) – Unit for the phase plots, default is “deg”.
phase_scale (Union[List[float], Tuple[float], np.array], optional) – Scale for the phase plots, in phase_unit, default is None, meaning 1 full cycle.
display (bool, optional) – Display plots during execution, default is False.
dpi (int, optional) – Pixel resolution for plots, default is 300.
parallel (bool, optional) – Run in parallel, defaults to False.

Returns:

None

Return type:

NoneType

export_beamcut_report(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', lm_unit: str = 'amin', azel_unit: str = 'deg', parallel: bool = False) → None[source]

Create reports on the parameters of the gaussians fitted to the beamcut.

Parameters:

destination (str) – Directory into which to save the reports.
ant (list or str, optional) – Antenna ID to use in subselection, e.g. ea25, defaults to “all”.
ddi (list or int, optional) – Data description ID to use in subselection, e.g. 0, defaults to “all”.
lm_unit (str, optional) – Unit for L/M offsets, default is “amin”.
azel_unit (str, optional) – Unit for Az/El information, default is “deg”.
parallel (bool, optional) – run in parallel, defaults to False.

Returns:

None

Return type:

NoneType

class AstrohackPositionFile(file: str)[source]

Bases: astrohack.io.base_mds.AstrohackBaseFile

Data class for position data.

Data within an object of this class can be selected for further inspection, plotted or produce a report

export_locit_fit_results(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', position_unit: str = 'm', time_unit: str = 'hour', delay_unit: str = 'nsec', phase_unit: str = 'deg') → None[source]

Export antenna position fit results to a text file.

Parameters:

destination (str) – Name of the destination folder to contain exported fit results
ant (list or str, optional) – List of antennas/antenna to be exported, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be exported, defaults to “all” when None, ex. 0
position_unit (str, optional) – Unit to list position fit results, defaults to ‘m’
time_unit (str, optional) – Unit for time in position fit results, defaults to ‘hour’
delay_unit (str, optional) – Unit for delays, defaults to ‘nsec’
phase_unit (str, optional) – Unit for phasess, defaults to ‘deg’

Produce a text file with the fit results from astrohack.locit for better determination of antenna locations.

export_results_to_parminator(filename: str, ant: str | List[str] = 'all', ddi: int | None = None, correction_threshold: float | int = 0.01) → None[source]

Export antenna position fit results to a VLA parminator file.

Parameters:

filename (str) – Name of the parminator file to be created
ant (list or str, optional) – List of antennas/antenna to be exported, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be exported, defaults to “all” when None, ex. 0
correction_threshold (float, optional) – Correction threshold in meters to include an antenna position correction in output.

Produce a VLA parminator compatible text file with the fit results from astrohack.locit.

Plot the sky coverage of the data used for antenna position fitting

Parameters:

destination (str) – Name of the destination folder to contain the plots
ant (list or str, optional) – List of antennas/antenna to be plotted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be plotted, defaults to “all” when None, ex. 0
angle_unit (str, optional) – Unit for angle in plots, defaults to ‘deg’
time_unit (str, optional) – Unit for time in plots, defaults to ‘hour’
display (bool, optional) – Display plots inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot size in inches
dpi (int, optional) – plot resolution in pixels per inch, default is 300
parallel (bool, optional) – If True will use an existing astrohack client to produce plots in parallel, default is False

This method produces 4 plots for each selected antenna and DDI. These plots are: 1) Time vs Elevation 2) Time vs Hour Angle 3) Time vs Declination 4) Hour Angle vs Declination

These plots are intended to display the coverage of the sky of the fitted data

plot_delays(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', time_unit: str = 'hour', angle_unit: str = 'deg', delay_unit: str = 'nsec', plot_model: bool = True, display: bool = False, figure_size: Tuple | List[float | int] | numpy.ndarray | None = None, dpi: int = 300, parallel: bool = False) → None[source]

Plot the delays used for antenna position fitting and optionally the resulting fit.

Parameters:

destination (str) – Name of the destination folder to contain the plots
ant (list or str, optional) – List of antennas/antenna to be plotted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be plotted, defaults to “all” when None, ex. 0
angle_unit (str, optional) – Unit for angle in plots, defaults to ‘deg’
time_unit (str, optional) – Unit for time in plots, defaults to ‘hour’
delay_unit (str, optional) – Unit for delay in plots, defaults to ‘nsec’
plot_model (bool, optional) – Plot the fitted model results alongside the data.
display (bool, optional) – Display plots inline or suppress, defaults to True
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot size in inches
dpi (int, optional) – plot resolution in pixels per inch, default is 300
parallel (bool, optional) – If True will use an existing astrohack client to produce plots in parallel, default is False

This method produces 4 plots for each selected antenna and DDI. These plots are: 1) Time vs Delays 2) Elevation vs Delays 3) Hour Angle vs Delays 4) Declination vs Delays

These plots are intended to display the gain variation with the 4 relevant parameters for the fitting and also asses the quality of the position fit.

Plot Antenna position corrections on an array configuration plot

Parameters:

destination (str) – Name of the destination folder to contain plot
ant (list or str, optional) – Select which antennas are to be plotted, defaults to all when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be plotted, defaults to “all” when None, ex. 0
unit (str, optional) – Unit for the plot, valid values are length units, default is km
box_size (int, float, optional) – Size of the box for plotting the inner part of the array in unit, default is 5 km
scaling (int, float, optional) – scaling factor to plotting the corrections, default is 250
display (bool, optional) – Display plots inline or suppress, defaults to False
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300

Plot the position corrections computed by locit on top of an array configuration plot. The corrections are too small to be visualized on the array plot since they are of the order of mm and the array is usually spread over km, or at least hundreds of meters. The scaling factor is used to bring the corrections to a scale discernible on the plot, this plot should not be used to estimate correction values, for that purpose use export_locit_fit_results instead.

class AstrohackImageFile(file: str)[source]

Bases: astrohack.io.base_mds.AstrohackBaseFile

Data class for image data.

Data within an object of this class can be selected for further inspection, plotted or produce a report

export_to_fits(destination: str, complex_split: str = 'cartesian', ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', parallel: bool = False) → None[source]

Export contents of an AstrohackImageFile object to several FITS files in the destination folder

Parameters:

destination (str) – Name of the destination folder to contain plots
complex_split (str, optional) – How to split complex data, cartesian (real + imag, default) or polar (amplitude + phase)
ant (list or str, optional) – List of antennas/antenna to be plotted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddi to be plotted, defaults to “all” when None, ex. 0
parallel (bool, optional) – If True will use an existing astrohack client to export FITS in parallel, default is False

Export the products from the holog mds onto FITS files to be read by other software packages

Additional Information The image products of holog are complex images due to the nature of interferometric measurements and Fourier transforms, currently complex128 FITS files are not supported by astropy, hence the need to split complex images onto two real image products, we present the user with two options to carry out this split.

Available complex splitting possibilities:

cartesian: Split is done to a real part and an imaginary part FITS files
polar: Split is done to an amplitude and a phase FITS files

The FITS files produced by this function have been tested and are known to work with CARTA and DS9

Aperture amplitude and phase plots from the data in an AstrohackImageFIle object.

Parameters:

destination (str) – Name of the destination folder to contain plots
ant (list or str, optional) – List of antennas/antenna to be plotted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be plotted, defaults to “all” when None, ex. 0
polarization_state (list or str, optional) – List of polarization states/ polarization state to be plotted, defaults to “I”
plot_screws (bool, optional) – Add screw positions to plot, default is False
amplitude_limits (numpy.ndarray, list, tuple, optional) – Lower than Upper limit for amplitude in volts default is None (Guess from data)
phase_unit (str, optional) – Unit for phase plots, defaults is ‘deg’
phase_limits (numpy.ndarray, list, tuple, optional) – Lower than Upper limit for phase, value in phase_unit, default is None (Guess from data)
deviation_unit (str, optional) – Unit for deviation plots, defaults is ‘mm’
deviation_limits (numpy.ndarray, list, tuple, optional) – Lower than Upper limit for deviation, value in deviation_unit, default is None (Guess from data)
panel_labels (bool, optional) – Add panel labels to antenna surface plots, default is False
display (bool, optional) – Display plots inline or suppress, defaults to True
colormap (str, optional) – Colormap for plots, default is viridis
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300
parallel (bool, optional) – If True will use an existing astrohack client to produce plots in parallel, default is False

Produce plots from astrohack.holog results for analysis

plot_beams(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', complex_split: str = 'polar', angle_unit: str = 'deg', phase_unit: str = 'deg', display: bool = False, colormap: str = 'viridis', figure_size: Tuple | List[float] | numpy.ndarray = (8, 4.5), dpi: int = 300, parallel: bool = False) → None[source]

Beam plots from the data in an AstrohackImageFIle object.

Parameters:

destination (str) – Name of the destination folder to contain plots
ant (list or str, optional) – List of antennas/antenna to be plotted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be plotted, defaults to “all” when None, ex. 0
angle_unit (str, optional) – Unit for L and M axes in plots, default is ‘deg’.
complex_split (str, optional) – How to split complex beam data, cartesian (real + imag) or polar (amplitude + phase, default)
phase_unit (str) – Unit for phase in ‘polar’ plots, default is ‘deg’.
display (bool, optional) – Display plots inline or suppress, defaults to True
colormap (str, optional) – Colormap for plots, default is viridis
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300
parallel (bool, optional) – If True will use an existing astrohack client to produce plots in parallel, default is False

Produce plots from astrohack.holog results for analysis

export_phase_fit_results(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', angle_unit: str = 'deg', length_unit: str = 'mm', parallel: bool = False) → None[source]

Export perturbations phase fit results from the data in an AstrohackImageFIle object to ASCII files.

Parameters:

destination (str) – Name of the destination folder to contain ASCII files
ant (list or str, optional) – List of antennas/antenna to be exported, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be exported, defaults to “all” when None, ex. 0
angle_unit (str, optional) – Unit for results that are angles.
length_unit (str, optional) – Unit for results that are displacements.
parallel (bool, optional) – If True will use an existing astrohack client to produce ASCII files in parallel, default is False

Export the results of the phase fitting process in astrohack.holog for analysis

export_zernike_fit_results(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', parallel: bool = False) → None[source]

Export Zernike coefficients from the data in an AstrohackImageFIle object to ASCII files.

Parameters:

destination (str) – Name of the destination folder to contain ASCII files
ant (list or str, optional) – List of antennas/antenna to be exported, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be exported, defaults to “all” when None, ex. 0
parallel (bool, optional) – If True will use an existing astrohack client to produce ASCII files in parallel, default is False

Export Zernike coefficients from the AstrohackImageFile object obtained during processing in astrohack.holog for analysis.

plot_zernike_model(destination: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', display: bool = False, colormap: str = 'viridis', figure_size: Tuple | List[float] | numpy.ndarray = (16, 9), dpi: int = 300, parallel: bool = False) → None[source]

Plot Zernike models from the data in an AstrohackImageFile object.

Parameters:

destination (str) – Name of the destination folder to contain the model plots
ant (list or str, optional) – List of antennas/antenna to be exported, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be exported, defaults to “all” when None, ex. 0
display (bool, optional) – Display plots inline or suppress, defaults to True
colormap (str, optional) – Colormap for plots, default is viridis
figure_size (numpy.ndarray, list, tuple, optional) – 2 element array/list/tuple with the plot sizes in inches
dpi (int, optional) – dots per inch to be used in plots, default is 300
parallel (bool, optional) – If True will use an existing astrohack client to produce plots in parallel, default is False

Export Zernike coefficients from the AstrohackImageFile object obtained during processing in astrohack.holog for analysis.

observation_summary(summary_file: str, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', az_el_key: str = 'center', phase_center_unit: str = 'radec', az_el_unit: str = 'deg', time_format: str = '%d %h %Y, %H:%M:%S', tab_size: int = 3, print_summary: bool = True, parallel: bool = False) → None[source]

Create a Summary of observation information

Parameters:

summary_file (str) – Text file to put the observation summary
ant (list or str, optional) – antenna ID to use in subselection, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – data description ID to use in subselection, defaults to “all” when None, ex. 0
az_el_key (str, optional) – What type of Azimuth & Elevation information to print, ‘mean’, ‘median’ or ‘center’, default is ‘center’
phase_center_unit (str, optional) – What unit to display phase center coordinates, ‘radec’ and angle units supported, default is ‘radec’
az_el_unit (str, optional) – Angle unit used to display Azimuth & Elevation information, default is ‘deg’
time_format (str, optional) – datetime time format for the start and end dates of observation, default is “%d %h %Y, %H:%M:%S”
tab_size (int, optional) – Number of spaces in the tab levels, default is 3
print_summary (bool, optional) – Print the summary at the end of execution, default is True
parallel (bool, optional) – Run in parallel, defaults to False

Additional Information

This method produces a summary of the data in the AstrohackImageFile displaying general information, spectral information, beam image characteristics and aperture image characteristics.

extract_holog(ms_name: str, point_name: str, holog_name: str | None = None, holog_obs_dict: astrohack.core.holog_obs_dict.HologObsDict | None = None, ant: str | List[str] = 'all', ddi: int | List[int] | str = 'all', baseline_average_distance: float | int | str = 'all', baseline_average_nearest: int | str = 1, exclude_antennas: list[str] | str | None = None, data_column: str = 'CORRECTED_DATA', time_smoothing_interval: float | int | None = None, pointing_interpolation_method: str = 'linear', parallel: bool = False, overwrite: bool = False, append: bool = False) → astrohack.io.holog_mds.AstrohackHologFile | None[source]

Extract holography and optionally pointing data, from measurement set. Creates holography output file.

Parameters:

ms_name (str) – Name of input measurement file name.
point_name – Name of <point_name>.point.zarr file to use. This is must be provided.
holog_name (str, optional) – Name of <holog_name>.holog.zarr file to create. Defaults to measurement set name with holog.zarr extension.
holog_obs_dict (dict, optional) – The holog_obs_dict describes which scan and antenna data to extract from the measurement set. As detailed below, this compound dictionary also includes important metadata needed for preprocessing and extraction of the holography data from the measurement set. If not specified holog_obs_dict will be generated. For auto generation of the holog_obs_dict the assumption is made that the same antenna beam is not mapped twice in a row (alternating sets of antennas is fine). If the holog_obs_dict is specified, the ddi input is ignored. The user can self generate this dictionary using generate_holog_obs_dict.
ant (str | list[str], optional) – Antennas that should be extracted from the measurement set. Defaults to all mapping antennas in the ms.
ddi (int numpy.ndarray | int list, optional) – DDI(s) that should be extracted from the measurement set. Defaults to all DDI’s in the ms.
baseline_average_distance (float, optional) – To increase the signal-to-noise for a mapping antenna multiple reference antennas can be used. The baseline_average_distance is the acceptable distance (in meters) between a mapping antenna and a reference antenna. The baseline_average_distance is only used if the holog_obs_dict is not specified. If no distance is specified all reference antennas will be used. baseline_average_distance and baseline_average_nearest can not be used together.
baseline_average_nearest (int, optional) – To increase the signal-to-noise for a mapping antenna multiple reference antennas can be used. The baseline_average_nearest is the number of nearest reference antennas to use. The baseline_average_nearest is only used if the holog_obs_dict is not specified. baseline_average_distance and baseline_average_nearest can not be used together.
exclude_antennas (str | list, optional) – If an antenna is given for exclusion it will not be processed as a reference or a mapping antenna. This can be used to exclude antennas that have bad data for whatever reason. Default is None, meaning no antenna is excluded.
data_column (str, optional, ex. DATA, CORRECTED_DATA) – Determines the data column to pull from the measurement set. Defaults to “CORRECTED_DATA”.
time_smoothing_interval (float, optional) – Determines the time smoothing interval, set to the integration time when None.
pointing_interpolation_method (str, optional) – Determines which algorithm to use to interpolate pointing in time, two options are available: ‘linear’ (Faster but brittle) and ‘gaussian’ (slower but robust), default is ‘linear’.
parallel (bool, optional) – Boolean for whether to process in parallel, defaults to False.
overwrite (bool, optional) – Boolean for whether to overwrite current holog.zarr and point.zarr files, defaults to False.
append (bool, optional) – Should data be appended to an existing holog file on disk, append and overwrite cannot be both true defaults to False.

Returns:

Holography holog object.

Return type:

AstrohackHologFile

AstrohackHologFile

Holog object allows the user to access holog data via compound dictionary keys with values, in order of depth, ddi -> map -> ant. The holog object also provides a summary() helper function to list available keys for each file. An outline of the holog object structure is show below:

holog_mds =
{
    ddi_0:{
        map_0:{
         ant_0: holog_ds,
                  ⋮
         ant_n: holog_ds
        },
        ⋮
        map_p: …
    },
    ⋮
    ddi_m: …
}

Example Usage In this case the pointing file has already been created. In addition, the appropriate data_column value nees to be set for the type of measurement set data you are extracting.

from astrohack.extract_holog import extract_holog

holog_mds = extract_holog(
    ms_name="astrohack_observation.ms",
    point_name="astrohack_observation.point.ms",
    holog_name="astrohack_observation.holog.ms",
    data_column='CORRECTED_DATA',
    parallel=True,
    overwrite=True
)

Additional Information

This function extracts the holography related information from the given measurement file. The data is restructured into an astrohack file format and saved into a file in the form of <holog_name>.holog.zarr. The extension .holog.zarr is used for all holography files. In addition, the pointing information is recorded into a holography file of format <pointing_name>.point.zarr. The extension .point.zarr is used for all holography pointing files.

holog_obs_dict[holog_mapping_id] (dict): holog_mapping_id is a unique, arbitrary, user-defined integer assigned to the data that describes a single complete mapping of the beam.

This is needed for two reasons:

A complete mapping of the beam can be done over more than one scan (for example the VLA data).

A measurement set can contain more than one mapping of the beam (for example the ALMA data).

holog_obs_dict[holog_mapping_id][scans] (int | numpy.ndarray | list): All the scans in the measurement set the holog_mapping_id.

holog_obs_dict[holog_mapping_id][ant] (dict): The dictionary keys are the mapping antenna names and the values a list of the reference antennas. See example below.

The below example shows how the holog_obs_description dictionary should be laid out. For each holog_mapping_id the relevant scans and antennas must be provided. For the ant key, an entry is required for each mapping antenna and the accompanying reference antenna(s).
holog_obs_description = {
    'map_0' :{
        'scans':[2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22],
        'ant':{
            'DA44':[
                'DV02', 'DV03', 'DV04',
                'DV11', 'DV12', 'DV13',
                'DV14', 'DV15', 'DV16',
                'DV17', 'DV18', 'DV19',
                'DV20', 'DV21', 'DV22',
                'DV23', 'DV24', 'DV25'
            ]
        }
    }
}

generate_holog_obs_dict(point_name: str, baseline_average_distance: str = 'all', baseline_average_nearest: str = 'all', exclude_antennas: list[str] | str | None = None, parallel: bool = False) → astrohack.core.holog_obs_dict.HologObsDict[source]

Generate holography observation dictionary, from measurement set..

Parameters:

point_name (str, optional) – Name of <point_name>.point.zarr file to use.
baseline_average_distance – To increase the signal-to-noise for a mapping antenna multiple reference

antennas can be used. The baseline_average_distance is the acceptable distance between a mapping antenna and a reference antenna. The baseline_average_distance is only used if the holog_obs_dict is not specified. If no distance is specified all reference antennas will be used. baseline_average_distance and baseline_average_nearest can not be used together. :type baseline_average_distance: float, optional

Parameters:: baseline_average_nearest – To increase the signal-to-noise for a mapping antenna multiple reference antennas

can be used. The baseline_average_nearest is the number of nearest reference antennas to use. The baseline_average_nearest is only used if the holog_obs_dict is not specified. baseline_average_distance and baseline_average_nearest can not be used together. :type baseline_average_nearest: int, optional

Parameters:

exclude_antennas (str | list, optional) – If an antenna is given for exclusion it will not be processed as a reference or a mapping antenna. This can be used to exclude antennas that have bad data for whatever reason. Default is None, meaning no antenna is excluded.
parallel (bool, optional) – Boolean for whether to process in parallel. Defaults to False

Returns:

holog observation dictionary

Return type:

HologObsDict

AstrohackHologFile

Holog object allows the user to access holog data via compound dictionary keys with values, in order of depth, ddi -> map -> ant. The holog object also provides a summary() helper function to list available keys for each file. An outline of the holog object structure is show below:

holog_mds =
{
    ddi_0:{
        map_0:{
         ant_0: holog_ds,
                  ⋮
         ant_n: holog_ds
        },
        ⋮
        map_p: …
    },
    ⋮
    ddi_m: …
}

Example Usage In this case the pointing file has already been created.

from astrohack.extract_holog import generate_holog_obs_dict

holog_obs_obj = generate_holog_obs_dict(
    ms_name="astrohack_observation.ms",
    point_name="astrohack_observation.point.zarr"
)

Additional Information

holog_obs_dict[holog_mapping_id] (dict): holog_mapping_id is a unique, arbitrary, user-defined integer assigned to the data that describes a single complete mapping of the beam.

This is needed for two reasons:

A complete mapping of the beam can be done over more than one scan (for example the VLA data).

A measurement set can contain more than one mapping of the beam (for example the ALMA data).

holog_obs_dict[holog_mapping_id][scans] (int | numpy.ndarray | list): All the scans in the measurement set the holog_mapping_id.

holog_obs_dict[holog_mapping_id][ant] (dict): The dictionary keys are the mapping antenna names and the values a list of the reference antennas. See example below.

The below example shows how the holog_obs_description dictionary should be laid out. For each holog_mapping_id the relevant scans and antennas must be provided. For the ant key, an entry is required for each mapping antenna and the accompanying reference antenna(s).
holog_obs_description = {
    'map_0' :{
        'scans':[2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22],
        'ant':{
            'DA44':[
                'DV02', 'DV03', 'DV04',
                'DV11', 'DV12', 'DV13',
                'DV14', 'DV15', 'DV16',
                'DV17', 'DV18', 'DV19',
                'DV20', 'DV21', 'DV22',
                'DV23', 'DV24', 'DV25'
            ]
        }
    }
}

Process beamcut data from a .holog.zarr file to produce reports and plots.

Parameters:

holog_name (str) – Name of the .holog.zarr file to use as input.
beamcut_name (str) – Name for the output .beamcut.zarr file to save data.
ant (list or str, optional) – List of antennas/antenna to be processed, defaults to “all” when None, ex. ea25.
ddi (list or int, optional) – List of ddi to be processed, defaults to “all” when None, ex. 0.
destination (str, optional) – Destination directory for plots and reports if not None, defaults to None.
lm_unit (str, optional) – Unit for L/M offsets in plots and report, default is “amin”.
azel_unit (str, optional) – Unit for Az/El information in plots and report, default is “deg”.
phase_unit (str, optional) – Unit for phase plots, default is “deg”.
phase_scale (Union[List[float], Tuple[float], np.array], optional) – Scale for the phase plots, in phase_unit, default is None, meaning 1 full cycle.
dpi (int, optional) – Resolution in pixels, defaults to 300.
display (bool, optional) – Display plots during execution, defaults to False.
y_scale (str, optional) – Define amplitude plot Y scale, defaults to None.
parallel (bool, optional) – Process beamcuts in parallel, defaults to False.
overwrite (bool, optional) – Overwrite previously existing beamcut file of same name, defaults to False.

Returns:

Beamcut mds object

Return type:

AstrohackBeamcutFile

AstrohackBeamcutFile

The beamcut mds object allows the user to access the underlying xarray datatree using compound keys, which are in order of depth, ant -> ddi. This object also provides a summary() method to list available data and available data visualization methods.

An outline of the beamcut mds data tree is show below:

image_mds =
    {
    ant_0:{
        ddi_0: {
            cut_0: beamcut_ds
            ⋮
            cut_p: beamcut_ds
        },
        ddi_m: …
    },
    ⋮
    ant_n: …
}

Example Usage

from astrohack import beamcut

beamcut(
    holog_name="astrohack_observation.holog.zarr",
    beamcut_name="astrohack_observation.beamcut.zarr",
    destination="beamcut_exports",
    display=False,
    ant='ea25',
    overwrite=True,
    parallel=True
)

extract_pointing(ms_name: str, point_name: str | None = None, parallel: bool = False, overwrite: bool = False) → astrohack.io.point_mds.AstrohackPointFile | None[source]

Extract pointing data from measurement set. Creates holography output file.

Parameters:

ms_name (str) – Name of input measurement file name.
point_name (str, optional) – Name of <point_name>.point.zarr file to create. Defaults to measurement set name with point.zarr extension.
parallel (bool, optional) – Boolean for whether to process in parallel. Defaults to False
overwrite (bool, optional) – Overwrite pointing file on disk, defaults to False

Returns:

Holography point object.

Return type:

AstrohackPointFile

Example Usage In this case, the pointing_name is the file name to be created after extraction.

from astrohack.extract_pointing import extract_pointing

extract_pointing(
    ms_name="astrohack_observation.ms",
    point_name="astrohack_observation.point.zarr"
)

AstrohackPointFile

Point object allows the user to access point data via dictionary keys with values ant. The point object also provides a summary() helper function to list available keys for each file.

holog(holog_name: str, image_name: str | None = None, grid_size: int | numpy.ndarray | List[int] | None = None, cell_size: float | int | numpy.ndarray | List[int] | None = None, padding_factor: int = 10, grid_interpolation_mode: str = 'gaussian', chan_average: bool = True, chan_tolerance_factor: float = 0.005, scan_average: bool = True, alma_osf_pad: str | None = None, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', zernike_n_order: int = 4, phase_fit_engine: str = 'perturbations', phase_fit_control: List[bool] | Tuple[bool] = (True, True, True, True, True), to_stokes: bool = True, overwrite: bool = False, parallel: bool = False) → astrohack.io.image_mds.AstrohackImageFile | None[source]

Process holography data and derive aperture illumination pattern.

Parameters:

holog_name (str) – Name of holography .holog.zarr file to process.
image_name (str, optional) – Defines the name of the output image name. If value is None, the name will be set to <base_name>.image.zarr, defaults to None
grid_size (numpy.ndarray, dtype int, list optional) – Numpy array specifying the dimensions of the grid used in data gridding. If not specified grid_size is calculated using POINTING_OFFSET in pointing table.
cell_size (numpy.ndarray, dtype float, list optional) – Size 2 array defining the cell size of each beam grid bin in radians. If not specified, the used cell_size is the one given in the observation_summary of the input holog file.
padding_factor (int, optional) – Padding factor applied to beam grid before computing the fast-fourier transform. The default has been set for operation on most systems. The user should be aware of memory constraints before increasing this parameter significantly., defaults to 10
parallel (bool, optional) – Run in parallel with Dask or in serial., defaults to False
grid_interpolation_mode (str, optional. Available options: {"gaussian", "linear", "nearest", "cubic"}) – Method of interpolation used when gridding data. For modes ‘linear’, ‘nearest’ and ‘cubic’ this is done using the scipy.interpolate.griddata method. For more information see scipy.interpolate. The remaining mode ‘gaussian’ convolves the visibilities with a gaussian kernel with a FWHM equal HPBW for the primary beam main lobe at the given frequency, this is slower than scipy.interpolate.griddata but better at preserving the small scales variations in the beam. Defaults to “gaussian”.
chan_average (bool, optional) – Boolean dictating whether the channel average is computed and written to the output holog file., defaults to True
chan_tolerance_factor (float, optional) – Tolerance used in channel averaging to determine the number of primary beam channels., defaults to 0.005
scan_average (bool, optional) – Boolean dictating whether averaging is done over scan., defaults to True
alma_osf_pad (str, optional) – Pad on which the antenna was poitioned at the ALMA OSF (only relevant for ALMA near field holographies).
ant (list or str, optional) – List of antennas/antenna to be processed, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddi to be processed, defaults to “all” when None, ex. 0
zernike_n_order (int, optional) – Maximal N order for the Zernike Polynomials to be fitted to the aperture data.
phase_fit_engine (str, optional.) – Choose between the two available phase fitting engines, “perturbations” which assumes cassegrain optics and “zernike” which makes no assumption about the optical system but may overfit the aperture phase, default is “perturbations”.
phase_fit_control (bool array, optional) –
Controls which type of optical perturbations are to be fitted when phase_fit_engine is set to “perturbations”.

Available phase fit controls:
- [0]: pointing offset;
- [1]: focus xy offsets;
- [2]: focus z offset;
- [3]: subreflector tilt (off by default except for VLA and VLBA)
- [4]: cassegrain offset
to_stokes (bool, optional) – Dictates whether polarization is computed according to stokes values., defaults to True
overwrite (bool, optional) – Overwrite existing files on disk, defaults to False

Returns:

Holography image object.

Return type:

AstrohackImageFile

AstrohackImageFile

Image object allows the user to access image data via compound dictionary keys with values, in order of depth, ant -> ddi. The image object also provides a summary() helper function to list available keys for each file. An outline of the image object structure is show below:

image_mds =
    {
    ant_0:{
        ddi_0: image_ds,
         ⋮
        ddi_m: image_ds
    },
    ⋮
    ant_n: …
}

Example Usage

from astrohack.holog import holog

holog(
    holog_name="astrohack_observation.holog.zarr",
    padding_factor=50,
    grid_interpolation_mode='linear',
    chan_average = True,
    scan_average = True,
    ant='ea25',
    overwrite=True,
    parallel=True
)

panel(image_name: str, panel_name: str | None = None, clip_type: str = 'sigma', clip_level: float | int | dict[dict[float | int]] = 3.0, use_detailed_mask: bool = True, panel_model: str = 'rigid', panel_margins: float = 0.05, polarization_state: str = 'I', ant: str | List[str] = 'all', ddi: str | int | List[str] = 'all', parallel: bool = False, overwrite: bool = False)[source]

Analyze holography images to derive panel adjustments

Parameters:

image_name (str) – Input holography data file name. Accepted data formats are the output from astrohack.holog.holog and AIPS holography data prepackaged using astrohack.panel.aips_holog_to_astrohack.
panel_name (str, optional) – Name of output file; File name will be appended with suffix .panel.zarr. Defaults to basename of input file plus holography panel file suffix.
clip_type (str, optional) – Choose the amplitude clipping algorithm: none, absolute, relative, sigma or noise_threshold, default is sigma
clip_level (float, dict, optional) – Choose level of clipping, can also be specified for specific antenna and DDI combinations by passing a dictionary, default is 3 (appropriate for sigma clipping)
use_detailed_mask (bool, optional) – Use a detailed aperture mask, i.e. include arm shadows for the VLA or include regions outside central circular aperture for the ngvla, default is True.
panel_model (str, optional) – Model of surface fitting function used to fit panel surfaces, None will default to “rigid”. Possible models are listed below.
panel_margins (float, optional) – Relative margin from the edge of the panel used to decide which points are margin points or internal points of each panel. Defaults to 0.05.
polarization_state (str, optional) – Select the polarization state over which to run panel, only parallel hands or stokes I should be used, default is I.
ant (list or str, optional) – List of antennas/antenna to be processed, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddi to be processed, defaults to “all” when None, ex. 0
parallel (bool, optional) – Run in parallel. Defaults to False.
overwrite (bool, optional) – Overwrite files on disk. Defaults to False.

Returns:

Holography panel object.

Return type:

AstrohackPanelFile

Each Stokes I aperture image in the input image file is processed in the following steps:

Code Outline

Phase image is converted to a physical surface deviation image.

A mask of valid signals is created by using the relative cutoff on the amplitude image.

From telescope panel and layout information, an image describing the panel assignment of each pixel is created

Using panel image and mask, a list of pixels in each panel is created.

Pixels in each panel are divided into two groups: margin pixels and internal pixels.

For each panel:

Internal pixels are fitted to a surface model.

The fitted surface model is used to derive corrections for all pixels in the panel, internal and margins.

The fitted surface model is used to derive corrections for the positions of the screws.

A corrected deviation image is produced.

RMS is computed for both the corrected and uncorrected deviation images.

All images produced are stored in the output .panel.zarr file.

Available panel surface models:

AIPS fitting models:

mean: The panel is corrected by the mean of its samples.

rigid: The panel samples are fitted to a rigid surface (DEFAULT model).

Corotated Paraboloids: (the two bending axes of the paraboloid are parallel and perpendicular to a radius of the antenna crossing the middle point of the panel):

corotated_scipy: Paraboloid is fitted using scipy.optimize, robust but slow.

corotated_lst_sq: Paraboloid is fitted using the linear algebra least squares method, fast but unreliable.

corotated_robust: Tries corotated_lst_sq, if it diverges falls back to corotated_scipy, fast and robust.

Experimental fitting models:

xy_paraboloid: fitted using scipy.optimize, bending axes are parallel to the x and y axes.

rotated_paraboloid: fitted using scipy.optimize, bending axes can be rotated by any arbitrary angle.

full_paraboloid_lst_sq: Full 9 parameter paraboloid fitted using least_squares method, tends to heavily overfit surface irregularities.

Amplitude clipping:

In order to produce results of good quality parts of the aperture with low signal (e.g. the shadow of the secondary mirror support) a mask is defined based on the amplitude of the aperture. There are 5 methods (clip_type parameter) available to define at which level (clip_level) the amplitude is clipped:

none: In this method no amplitude clip is performed, i.e. the clipping value is set to -infinity.

absolute: In this method the clipping value is taken directly from the clip_level parameter, e.g.: if the user calls panel(…, clip_type=’absolute’, clip_level=3.5) everything below 3.5 in amplitude will be clipped

relative: In this method the clipping value is derived from the amplitude maximum, e.g.: if the user calls `panel(…, clip_type=’relative’, clip_level=0.2) everything below 20% of the maximum amplitude will be clipped

sigma: In this method the clipping value is computed from the RMS noise in the amplitude outside the physical dish, e.g.: if the user calls panel(clip_type=’sigma’, clip_level=3) everything below 3 times the RMS noise in amplitude will be clipped.

noise_threshold: In this model the cut is first set to the maximum amplitude outside the disk, a proxy for the noise maximum in amplitude, if this preserves a fraction of the aperture disk that is larger than the clip_level this is the chosen amplitude cutoff, if not, the cutoff is iteratively lowered by 10% until it preservers a fraction of the disk that is larger thatn clip_level. This heuristic was created with help from VLA operations.

The default clipping is set to 3 sigma.

Passing a dictionary for amplitude clipping:

The dictionary used for specifying amplitude clippings specific for each antenna and DDI combination must follow the following scheme:
amp_clip_dict = {
    ant1_name: {
        0: 0.3
        1: 0.5
    }
    ant2_name: {
        0: 0.45
        1: 0.21
    }
}
Where the antenna name is the usual antenna designation e.g. ea24 for the VLA or DV42 for ALMA, and the DDI number must be given as an integer.

AstrohackPanelFile Panel object allows the user to access panel data via compound dictionary keys with values, in order of depth, ant -> ddi. The panel object also provides a summary() helper function to list available keys for each file. An outline of the panel object structure is show below:

panel_mds =
{
    ant_0:{
        ddi_0: panel_ds,
         ⋮
        ddi_m: panel_ds
    },
    ⋮
    ant_n: …
}

Example Usage

from astrohack.panel import panel

# Fit the panels in the aperture image by using a rigid panel model and
# excluding the border 5% of each panel from the fitting.
panel_mds = panel(
    "myholo.image.zarr",
    panel_model='rigid',
    panel_margin=0.05
)

# fit the panels in the aperture image by using a rigid panel model and
# excluding points in the aperture image which have an amplitude that is less than 20% of the peak amplitude.
panel_mds = panel(
    "myholo.image.zarr",
    clip_type='relative',
    clip_level=0.2
)

combine(image_name: str, combine_name: str | None = None, ant: str | List[str] = 'all', ddi: int | List[int] | str = 'all', weighted: bool = False, parallel: bool = False, overwrite: bool = False) → astrohack.io.image_mds.AstrohackImageFile | None[source]

Combine DDIs in a Holography image to increase SNR

Parameters:

image_name (str) – Input holography data file name. Accepted data format is the output from astrohack.holog.holog
combine_name (str, optional) – Name of output file; File name will be appended with suffix .combine.zarr. Defaults to basename of input file plus holography panel file suffix.
ant (list or str, optional) – List of antennas to be processed. None will use all antennas. Defaults to None, ex. ea25.
ddi (list of int, optional) – List of DDIs to be combined. None will use all DDIs. Defaults to None, ex. [0, …, 8].
weighted (bool, optional) – Weight phases by the corresponding amplitudes.
parallel (bool, optional) – Run in parallel. Defaults to False.
overwrite (bool, optional) – Overwrite files on disk. Defaults to False.

Returns:

Holography image object.

Return type:

AstrohackImageFile

combine

Combine combines the amplitude and corrected_phase members of the selected DDIs in the input image file. Currently, combine only supports the combination of these two quantities to avoid long regridding times. Hence, the output image file (.combine.zarr file name) contains the combined amplitude and corrected_phase images, but the aperture and beam images present in this file will be those present in the DDI with the lowest frequency.

AstrohackImageFile

Image object allows the user to access image data via compound dictionary keys with values, in order of depth, ant -> ddi. The image object produced by combine is special because it will always contain a single DDI. The image object also provides a summary() helper function to list available keys for each file. An outline of the image object structure when produced by combine is show below:

image_mds =
    {
    ant_0:{
        ddi_n: image_ds,
    },
    ⋮
    ant_n: …
}

Example Usage

from astrohack.combine import combine

combine(
    "astrohack_obs.image.zarr",
    ant = "ea25"
    weight = False
)

locit(locit_name: str, position_name: str | None = None, elevation_limit: float | int = 10.0, polarization: str = 'both', fit_engine: str = 'scipy', fit_kterm: bool = False, fit_delay_rate: bool = True, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', combine_ddis: str = 'simple', parallel: bool = False, overwrite: bool = False)[source]

Extract Antenna position determination data from an MS and stores it in a locit output file.

Parameters:

locit_name (str) – Name of input *.locit.zarr file.
position_name (str, optional) – Name of <position_name>.position.zarr file to create. Defaults to measurement set name with position.zarr extension.
elevation_limit (float, optional) – Lower elevation limit for excluding sources in degrees
polarization (str, optional) – Which polarization to use R, L or both for circular systems, X, Y, or both for linear systems.
fit_kterm (bool, optional) – Fit antenna elevation axis offset term, defaults to False
fit_delay_rate (bool, optional) – Fit delay rate with time, defaults to True
fit_engine (str, optional) – What engine to use on fitting, default is linear algebra
ant (list or str, optional) – List of antennas/antenna to be processed, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddis/ddi to be processed, defaults to “all” when None, ex. 0
combine_ddis (str, optional) – Type of DDI combination, if desired, defaults to simple
parallel (bool, optional) – Run in parallel. Defaults to False.
overwrite (bool, optional) – Boolean for whether to overwrite current position.zarr file, defaults to False.

Returns:

Antenna position object.

Return type:

AstrohackPositionFile

AstrohackPositionFile Position object allows the user to access position data via compound dictionary keys with values, in order of depth, ant -> ddi. The position object also provides a summary() helper function to list available keys for each file. An outline of the position object structure is show below:

combine_ddis = no:

position_mds =
{
    ant_0:{
        ddi_0: position_ds,
         ⋮
        ddi_m: position_ds
    },
    ⋮
    ant_n: …
}

combine_ddis = [“simple”, “difference”]:

position_mds =
{
    ant_0: position_ds
    ant_n: position_ds
}

Additional Information

Available fitting engines:

For locit two fitting engines have been implemented, one the classic method used in AIPS is called here ‘linear algebra’ and a newer more pythonic engine using scipy curve fitting capabilities, which we call scipy, more details below.

linear algebra: This fitting engine is based on the least square methods for solving linear systems, this engine is fast, about one order of magnitude faster than scipy, but may fail to converge, also its uncertainties may be underestimated.
scipy: This fitting engine uses the well established scipy.optimize.curve_fit routine. This engine is slower than the linear algebra engine, but it is more robust with better estimated uncertainties.

Choosing a polarization

The position fit may be done on either polarization (R or L for the VLA, X or Y for ALMA) or for both polarizations at once. When choosing both polarizations we increase the robustness of the solution by doubling the amount of data fitted.

Combining DDIs

By default, (combine_ddis=’simple’) locit combines different DDIs so that there is a single position solution per antenna. The other options are, a solution for each of the DDIs for each antenna (combine_ddis=’no’) or combining two DDIs by computing the delays from the difference in phases between the two DDIs of different frequencies (combine_ddis=’difference’).

combine_ddis=’simple’ : Generates higher antenna position correction solutions of higher SNR as more data is used in each delay fit. combine_ddis=’no’ : Useful for detecting systematic differences between different DDIs. combine_ddis=’difference’ : This method is useful for cases where phase wrapping may have occurred due to large delays.

Examples

position_mds = locit(“myphase.locit.zarr”, polarization=’R’, combine_ddis=’simple’) -> Fit the phase delays in “myphase.locit.zarr” for all antennas by combining the delays from all DDIs but using only the ‘R’ polarization.
position_mds = locit(“myphase.locit.zarr”, combine_ddis=’difference’, elevation_limit=30.0) -> Fit the phase difference delays in “myphase.locit.zarr” for all antennas but only using sources above 30 degrees elevation.

extract_locit(cal_table: str, locit_name: str | None = None, ant: str | List[str] = 'all', ddi: str | int | List[int] = 'all', overwrite: bool = False)[source]

Extract Antenna position determination data from an MS and stores it in a locit output file.

Parameters:

cal_table (str) – Name of input measurement file name.
locit_name (str, optional) – Name of <locit_name>.locit.zarr file to create. Defaults to measurement set name with locit.zarr extension.
ant (list or str, optional) – List of antennas/antenna to be extracted, defaults to “all” when None, ex. ea25
ddi (list or int, optional) – List of ddi to be extracted, defaults to “all” when None, ex. 0
overwrite (bool, optional) – Boolean for whether to overwrite current locit.zarr file, defaults to False.

Returns:

Antenna position locit object.

Return type:

AstrohackLocitFile

extract_locit is a tool to extract the phase gains from a calibration table in an order that is suited for parallelized processing by locit. Along with the calibration data antenna position and source position information is extracted from the calibration table for use in the fitting process in locit.

AstrohackLocitFile The locit object allows the user to access calibration data via compound dictionary keys with values, in order of depth, ant -> ddi. The locit object also provides a summary() helper function to list available keys for each file. An outline of the locit object structure is show below:

locit_mds =
{
    ant_0:{
        ddi_0: locit_ds,
         ⋮
        ddi_m: locit_ds
    },
    ⋮
    ant_n: …
}

Examples

locit_mds = extract_locit(“myphase.cal”, locit_name=”myphase.locit.zarr”) -> Extract phase calibration data for all antennas and all DDIs in “myphase.cal” into a locit file called “myphase.locit.zarr”
locit_mds = extract_locit(“myphase.cal”, ant=[“ea06”, “ea03”, “ea25”], DDI=0, overwrite=True) -> Extract phase calibration data for DDI 0 of antennas ea06, ea03 and ea25 in “myphase.cal” into a locit file called “myphase.locit.zarr” that will be overwritten if already present.

cassegrain_ray_tracing_pipeline(output_xds_filename: str, telescope_parameters: dict, grid_size: float | int = 28, grid_resolution: float | int = 0.1, grid_unit: str = 'm', x_pointing_offset: float | int = 0, y_pointing_offset: float | int = 0, pointing_offset_unit: str = 'asec', x_focus_offset: float | int = 0, y_focus_offset: float | int = 0, z_focus_offset: float | int = 0, focus_offset_unit: str = 'mm', phase_offset: float | int = 0, phase_unit: str = 'deg', observing_wavelength: float | int = 1, wavelength_unit: str = 'cm', overwrite: bool = False)[source]

Execute the cassegrain ray tracing pipeline to determine phase effects caused by optical mis-alignments.

Parameters:

output_xds_filename (str) – Filename for the output Xarray dataset on disk using a Zarr container.
telescope_parameters (dict) – Dictionary containing the parameters of the cassegrain telescope in use.
grid_size (float, int, optional) – Size of the grid onto which to compute phase effects in grid_unit.
grid_resolution (float, int, optional) – Resolution of the grid onto which to compute phase effects in grid_unit.
grid_unit (str, optional) – Length unit for grid_size and grid_resolution, default is “m”.
x_pointing_offset (float, int, optional) – X Pointing offset in pointing_offset_unit.
y_pointing_offset (float, int, optional) – Y Pointing offset in pointing_offset_unit.
pointing_offset_unit (str, optional) – Angle unit for pointing offsets, default is “asec”.
x_focus_offset (float, int, optional) – X offset of the secondary in focus_offset_unit.
y_focus_offset (float, int, optional) – Y offset of the secondary in focus_offset_unit.
z_focus_offset (float, int, optional) – Z offset of the secondary in focus_offset_unit, what is usually refered to as simply focus.
focus_offset_unit (str, optional) – Length unit for focus offsets, default is “mm”.
phase_offset (float, int, optional) – A phase offset to be applied to the phase image.
phase_unit (str, optional) – Angle unit for the phase offset, default is “deg”.
observing_wavelength (float, int, optional) – Wavelength of the rays to be simulated in wavelength unit.
wavelength_unit (str, optional) – Length unit for the observing wavelength, default is “cm”.
overwrite (bool, optional) – Overwrite rt_xds file on disk, default is False.

Returns:

X array dataset object with the results from the ray tracing.

Return type:

xr.Dataset

Code Outline

A Gridded representation of the primary dish and the normal to its surface are created and stored in an XDS.

The reflection between the incident light and the primary mirror is computed for each of the gridded points.

The reflected rays from the primary are progated and the intercept between them and the secondary is calculated.

Compute the reflection at the secondary for each ray reflected at the primary that touches it.

Check which rays from the secondary intercept the mouth of the horn.

Compute the total path from the rim of the primary up to horn for detected rays.

Compute the phase for each ray based on the total path.

Limitations

This ray tracing code only aims at estimating aperture phases, not its amplitude.

Detection from sidelobes is not estimated.

Beam shape estimations cannot be computed from the results as amplitudes are not modeled.

This model is axi-symmetric, i.e. it cannot be used to estimate the full range of phase effects present in VLA apertures.

If large pointing or focus offsets are chosen the rays may stop intercepting the horn and hence produce partially or fully blank phase images.

Create a dictionary with a cassegrain telescope parameters

Parameters:

primary_diameter (float, int, optional) – Diameter of the primary mirror.
secondary_diameter (float, int, optional) – Diameter of the secondary mirror.
focal_length (float, int, optional) – Focal length of the primary mirror.
z_intercept (float, int, optional) – Distance between the Z intercept of the secondary and the mid-point between the primary and secondary focus, usually refered to as ‘a’.
foci_half_distance (float, int, optional) – Half-distance between the primary and secondary foci, usually refered to as ‘c’.
inner_radius (float, int, optional) – Inner valid surface radius of the primary reflector, usually refered to as Blockage.
horn_diameter (float, int, optional) – Diameter of the horn detecting the signals, used to determine if rays are detected or lost.
length_unit (str, optional) – Unit for the telescope dimensions, default is “m”.

Returns:

A dictionary filled with the user inputs and also the horn position and orientation.

Return type:

dict

Create a basic description of a Cassegrain radio telescope from user inputs. This function assumes that the horn is positioned at the secondary focus and is pointed directly upwards, i.e. an axi-symmetric design. Default values reflect the values for the VLA available in EVLA memo 211.

plot_2d_maps_from_rt_xds(rt_xds_filename: str, keys: str | list, rootname: str, phase_unit: str = 'deg', length_unit: str = 'm', colormap: str = 'viridis', display: bool = True, dpi: int = 300)[source]

Plot 2D maps of keys in the ray tracing Xarray Dataset

Parameters:

rt_xds_filename (str) – Name on disk of the Xarray dataset containing the results of the Ray tracing pipeline
keys (str, list) – Key or keys in rt_xds to be plotted.
rootname (str) – Root name for the plots to be created.
phase_unit (str, optional) – Unit for the phase plot, default is “deg”.
length_unit (str, optional) – Unit for the plots of keys other than phase, default is “m”.
colormap (str, optional) – Colormap to be used for plots, default is “viridis”.
display (bool, optional) – Display plots inline or suppress, defaults to True
dpi (int, optional) – dots per inch to be used in plots, default is 300

Produce plots from the Xarray dataset containing ray tracing results for analysis. All Xarray dataset data variables except for the x and y axes can be plotted.

plot_radial_projection_from_rt_xds(rt_xds_filename: str, plot_filename: str, nrays: int = 20, display: bool = True, dpi: int = 300)[source]

Plot a radial projection of some of the rays simulated in the ray tracing Xarray Dataset.

Parameters:

rt_xds_filename (xr.Dataset) – Name on disk of the Xarray dataset containing the results of the Ray tracing pipeline
plot_filename (str) – Name of the file to contain the plot.
nrays (int, optional) – Number of random rays to be plotted, default is 20.
display (bool, optional) – Display plot inline or suppress, default is True
dpi (int, optional) – dots per inch to be used in plots, default is 300

Produce a plot of a random selection of nrays that are present on the input Xarray dataset.

apply_holog_phase_fitting_to_rt_xds(rt_xds_filename: str, phase_plot_filename: str, fit_pointing_offset: bool = True, fit_xy_secondary_offset: bool = True, fit_focus_offset: bool = True, phase_unit: str = 'deg', colormap: str = 'viridis', display: bool = True, dpi: int = 300)[source]

Feed phase image from ray tracing Xarray dataset to Astrohak’s default phase fitting tool for VLA data.

Parameters:

rt_xds_filename (xr.Dataset) – Name on disk of the Xarray dataset containing the results of the Ray tracing pipeline
phase_plot_filename (str) – filename for the plot containing the RT phase image the fitted phase effects and the residuals
fit_pointing_offset (bool, optional) – Toggle to determine if pointing offsets are to be fitted, default is True.
fit_xy_secondary_offset – Toggle to determine if lateral displacements of the secondary are to be fitted,

default is True. :type fit_xy_secondary_offset: bool, optional

Parameters:

fit_focus_offset (bool, optional) – Toggle to determine if vertical displacements of the secondary are to be fitted, default is True.
phase_unit (str, optional) – Unit for the phase plot, default is “deg”.
colormap (str, optional) – Colormap to be used for plots, default is “viridis”.
display (bool, optional) – Display plots inline or suppress, defaults to True
dpi (int, optional) – dots per inch to be used in plots, default is 300

Apply the phase fitting engine used in astrohack.holog.holog to the phase image computed by the ray tracing pipeline. At the end of the fitting produces a table so that fitting results can be compared to the inputs given for the ray tracing pipeline. Along with the table a plot is produced containing the ray tracing modelled phases, the correction derived from the phase fitting tool and the residuals of the fitting. For easier comparison simple statistics of each image are provided.

compare_fits_images(image: str | List[str], reference_image: str | List[str], telescope_name: str, destination: str, comparison: str = 'direct', zarr_container_name: str | None = None, plot_resampled: bool = False, plot_percentuals: bool = False, plot_reference: bool = False, plot_original: bool = False, plot_divided_image: bool = False, plot_scatter: bool = True, z_scale_limits: List[float] | Tuple | numpy.ndarray | None = None, colormap: str = 'viridis', dpi: int = 300, display: bool = False, export_to_fits: bool = False, parallel: bool = False)[source]

Compares a set of images to a set of reference images.

Parameters:

image (list or str) – FITS image or list of FITS images to be compared.
reference_image (list or str) – FITS image or list of FITS images that serve as references.
telescope_name (str) – Name of the telescope used. Used for masking.
destination (str) – Name of directory onto which save plots
comparison (str, optional) – Type of comparison to be made between images, “direct” or “scaled”, default is “direct”.
zarr_container_name (str, optional) – Name of the Zarr container to contain the created datatree, default is None, i.e. DataTree is not saved to disk.
plot_resampled (bool, optional) – Plot the resampled data array used in the comparison, default is False.
plot_reference (bool, optional) – Plot the reference image used in the comparison, default is False.
plot_original (bool, optional) – Plot the unresampled image used as input, default is False.
plot_percentuals (bool, optional) – Plot the residuals in percent of reference image as well, default is False.
plot_divided_image (bool, optional) – Plot the divided image between Image and its reference, default is False.
plot_scatter (bool, optional) – Make a scatter plot of the Image against its reference image, default is True.
z_scale_limits (list, np.array, tuple, optional) – Z scale for original, resampled, reference and residual images in the image units, default is None (get z scale limits from data)
colormap (str, optional) – Colormap to be used on image plots, default is “viridis”.
dpi (int, optional) – dots per inch to be used in plots, default is 300.
display (bool, optional) – Display plots inline or suppress, defaults to True
export_to_fits (bool, optional) – Export created images to FITS files inside destination, default is False.
parallel (bool, optional) – If True will use an existing astrohack client to do comparison in parallel, default is False

Returns:

DataTree object containing all the comparisons executed

Return type:

xr.DataTree

Compares pairs of FITS images pixel by pixel using a mask based on telescope parameters to exclude problematic regions such as shadows caused by the secondary mirror or the arms supporting it. By default, 2 products are produced, a plot of the residuals image, i.e. (Reference - Image) and a scatter plot of the Reference against the Image. If necessary a resample of Image is conducted to allow for pixel by pixel comparison.

Comparison:

Two types of comparison between the images are available:

direct: Where the residuals are simply computed as Reference - Image.
scaled: Where the residuals are Reference - Factor * Image, with Factor = median(Reference/Image).

Plots:

A plot of the residuals of the comparison is always produced. However, a few extra plots can be produced and their production is controlled by the plot_ parameters, these are:

plot_resampled: Activates plotting of the resampled data used in the comparison, default is False as this is just the data on the FITS file resampled to the reference sampling.

plot_percentuals: Activates the plotting of the residuals as a perdentage of the Reference Image, default is False as this is just another view on the residuals.

plot_reference: Activates the plotting of the reference image used in the comparison, default is False as this is just the data on the reference FITS file.

plot_original: Activates the plotting of the unresampled data, default is False as this is just the data on the FITS file

plot_divided_image: Activates the plotting of Reference/Image, default is False. This plot is only available when using “scaled” comparison.

plot_scatter: Activates the creation of a scatter plot of Reference vs Image, with a linear regression, default is True.

Storage on disk:

By default, this function only produces plots, but this can be changed using two parameters:

zarr_container_name: If this parameter is not None a Zarr container will be created on disk with the contents of the produced DataTree.
export_to_fits: If set to True will produce FITS files of the produced images and store them at destination.

Return type:

This funtion returns a Xarray DataTree containing the Xarray DataSets that represent Image and Reference. The nodes in this DataTree are labelled according to the filenames given as input for easier navigation.

rms_table_from_zarr_datatree(zarr_data_tree: str, table_file: str, rms_unit: str = 'mm', print_table: bool = False)[source]

Goes through the data in a zarr DataTree created by compare_fits_images.

Parameters:

zarr_data_tree (str) – Name on disk of the Zarr container holding a compare_fits_image DataTree.
table_file (str) – Name of the ASCII file to be created on disk to contain the RMS table
rms_unit (str, optional) – Unit for the RMSes in the table, default is ‘mm’.
print_table (bool, optional) – Print table on terminal, default is False.

Returns:

None

Return type:

NoneType

get_proper_telescope(name: str, antenna_name: str = None)[source]

Retrieve the proper telescope object based on the name :param name: Name of the telescope :param antenna_name: Name of the antenna, significant for heterogenius arrays.

Returns:: A telescope object of one of the proper subclasses