astrohack.utils.algorithms
==========================

.. py:module:: astrohack.utils.algorithms


Functions
---------

.. autoapisummary::

   astrohack.utils.algorithms.tokenize_version_number
   astrohack.utils.algorithms.data_from_version_needs_patch
   astrohack.utils.algorithms.calc_coords
   astrohack.utils.algorithms.find_nearest
   astrohack.utils.algorithms.chunked_average
   astrohack.utils.algorithms.find_peak_beam_value
   astrohack.utils.algorithms.gauss_elimination
   astrohack.utils.algorithms.least_squares
   astrohack.utils.algorithms.least_squares_jit
   astrohack.utils.algorithms.calculate_optimal_grid_parameters
   astrohack.utils.algorithms.compute_average_stokes_visibilities
   astrohack.utils.algorithms.compute_stokes
   astrohack.utils.algorithms.compute_antenna_relative_off
   astrohack.utils.algorithms.rotate_to_gmt
   astrohack.utils.algorithms.data_statistics
   astrohack.utils.algorithms.phase_wrapping
   astrohack.utils.algorithms.create_coordinate_images
   astrohack.utils.algorithms.arm_shadow_masking
   astrohack.utils.algorithms.are_axes_equal
   astrohack.utils.algorithms.create_2d_array_reconstruction_array
   astrohack.utils.algorithms.regrid_data_onto_2d_grid
   astrohack.utils.algorithms.compute_antenna_baseline_distance_matrix_dict


Module Contents
---------------

.. py:function:: tokenize_version_number(version_number)

   Tokenize a version number into an array of integers
   :param version_number: The astrohack number version to be tokenized

   :returns: Tokenized version number in 3 element numpy array of integers


.. py:function:: data_from_version_needs_patch(version_to_check, patched_version)

   Check if data from a version needs to be patched according to a reference patch version
   :param version_to_check: The version that is being tested
   :param patched_version: Reference version at which the patch is no longer needed

   :returns: True if the checked version is from before the patch False elsewise


.. py:function:: calc_coords(image_size, cell_size)

   Calculate the center pixel of the image given a cell and image size

   :param image_size: image size
   :type image_size: np.ndarray
   :param cell_size: cell size
   :type cell_size: np.ndarray

   :returns: center pixel location in coordinates x, y
   :rtype: float, float


.. py:function:: find_nearest(array, value)

   Find the nearest entry in array to that of value.

   :param array: _description_
   :type array: numpy.array
   :param value: _description_
   :type value: float

   :returns: index, array value
   :rtype: int, float


.. py:function:: chunked_average(data, weight, avg_map, avg_freq)

   Average visibilities in chunks with close enough frequencies
   :param data: Visibility data
   :param weight: Visibility weights
   :param avg_map: mapping of channels to average
   :param avg_freq: new frequency ranges

   Returns:
   Chunked average of visibilities and weights


.. py:function:: find_peak_beam_value(data, height=0.5, scaling=0.5)

   Search algorithm to determine the maximal signal peak in the beam pattern.

   :param data: beam data grid
   :type data: numpy.ndarray
   :param height: Peak threshold. Looks for the maximum peak in data and uses a percentage of this
                  peak to determine a threshold for other peaks. Defaults to 0.5.
   :type height: float, optional
   :param scaling: scaling factor for beam data cropping. Defaults to 0.5.
   :type scaling: float, optional

   :returns: peak maximum value
   :rtype: float


.. py:function:: gauss_elimination(system, vector)

   Gauss elimination solving of a system using numpy
   :param system: System matrix to be solved
   :param vector: Vector that represents the right hand side of the system

   Returns:
   The solved system


.. py:function:: least_squares(system, vector, return_sigma=False)

   Least squares fitting of a system of linear equations
   The variances are simplified as the diagonal of the covariances
   :param system: System matrix to be solved
   :param vector: Vector that represents the right hand side of the system
   :param return_sigma: Return sigma value

   Returns:
   The solved system, the variances of the system solution and the sum of the residuals


.. py:function:: least_squares_jit(system, vector)

   Least squares fitting of a system of linear equations
   The variances are simplified as the diagonal of the covariances
   :param system: System matrix to be solved
   :param vector: Vector that represents the right hand side of the system

   Returns:
   The solved system, the variances of the system solution and the sum of the residuals


.. py:function:: calculate_optimal_grid_parameters(pnt_map_dict, antenna_name, telescope_diameter, chan_freq, ddi)

.. py:function:: compute_average_stokes_visibilities(vis, stokes)

.. py:function:: compute_stokes(data, weight, pol_axis)

.. py:function:: compute_antenna_relative_off(antenna, tel_lon, tel_lat, tel_rad, scaling=1.0)

   Computes an antenna offset to the array center
   :param antenna: Antenna information dictionary
   :param tel_lon: array center longitude
   :param tel_lat: array center latitude
   :param tel_rad: array center's distance to the center of the earth
   :param scaling: scale factor

   Returns:
   Offset to the east, Offset to the North, elevation offset and distance to array center


.. py:function:: rotate_to_gmt(positions, errors, longitude)

   Rotate geometrical delays from antenna reference frame to GMT reference frame
   :param positions: geometrical delays
   :param errors: geometrical delay errors
   :param longitude: Antenna longitude

   Returns:
   Rotated geometrical delays and associated errors


.. py:function:: data_statistics(data_array)

.. py:function:: phase_wrapping(phase)

   Wraps phase to the -pi to pi interval
   :param phase: phase to be wrapped

   Returns:
   Phase wrapped to the -pi to pi interval


.. py:function:: create_coordinate_images(x_axis, y_axis, create_polar_coordinates=False)

   Takes two axes and creates 2D representation of the image coordinates
   :param x_axis: X axis
   :param y_axis: Y axis
   :param create_polar_coordinates: Also create polar coordinates images?

   :returns: x_mesh and y_mesh, plus radius_mesh and polar_angle_mesh if create_polar_coordinates


.. py:function:: arm_shadow_masking(inmask, x_mesh, y_mesh, radius_mesh, minradius, maxradius, width, angle)

.. py:function:: are_axes_equal(axis_a, axis_b)

.. py:function:: create_2d_array_reconstruction_array(x_axis, y_axis, mask)

.. py:function:: regrid_data_onto_2d_grid(x_axis, y_axis, linear_array, grid_idx)

   Use index information to get 1D data back onto a 2D grid.
   :param x_axis: X axis of the data on the 2 D grid
   :param y_axis: Y axis of the data on the 2 D grid
   :param linear_array: Linearized masked array
   :param grid_idx: Linearized 2 D indexes onto the original grid

   Returns:
   Data regridded onto a 2D array


.. py:function:: compute_antenna_baseline_distance_matrix_dict(ant_pos, ant_names)

   Compute a matrix of antenna position distances from antenna positions
   :param ant_pos: antenna position array
   :param ant_names: antenna names array
   :return: dict with antenna distance matrix