Source code for africanus.averaging.bda_avg

# -*- coding: utf-8 -*-

from collections import namedtuple

import numpy as np

from africanus.averaging.bda_mapping import bda_mapper, RowMapOutput
from africanus.averaging.shared import chan_corrs, merge_flags, vis_output_arrays
from africanus.util.docs import DocstringTemplate
from africanus.util.numba import (
    njit,
    overload,
    JIT_OPTIONS,
    intrinsic,
    is_numba_type_none,
)


_row_output_fields = [
    "antenna1",
    "antenna2",
    "time_centroid",
    "exposure",
    "uvw",
    "weight",
    "sigma",
]
RowAverageOutput = namedtuple("RowAverageOutput", _row_output_fields)


@njit(**JIT_OPTIONS)
def row_average(
    meta,
    ant1,
    ant2,
    flag_row=None,
    time_centroid=None,
    exposure=None,
    uvw=None,
    weight=None,
    sigma=None,
):
    return row_average_impl(
        meta,
        ant1,
        ant2,
        flag_row=flag_row,
        time_centroid=time_centroid,
        exposure=exposure,
        uvw=uvw,
        weight=weight,
        sigma=sigma,
    )


def row_average_impl(
    meta,
    ant1,
    ant2,
    flag_row=None,
    time_centroid=None,
    exposure=None,
    uvw=None,
    weight=None,
    sigma=None,
):
    return NotImplementedError


@overload(row_average_impl, jit_options=JIT_OPTIONS)
def nb_row_average_impl(
    meta,
    ant1,
    ant2,
    flag_row=None,
    time_centroid=None,
    exposure=None,
    uvw=None,
    weight=None,
    sigma=None,
):
    have_flag_row = not is_numba_type_none(flag_row)
    have_time_centroid = not is_numba_type_none(time_centroid)
    have_exposure = not is_numba_type_none(exposure)
    have_uvw = not is_numba_type_none(uvw)
    have_weight = not is_numba_type_none(weight)
    have_sigma = not is_numba_type_none(sigma)

    def impl(
        meta,
        ant1,
        ant2,
        flag_row=None,
        time_centroid=None,
        exposure=None,
        uvw=None,
        weight=None,
        sigma=None,
    ):
        out_rows = meta.time.shape[0]
        counts = np.zeros(out_rows, dtype=np.uint32)

        # These outputs are always present
        ant1_avg = np.empty(out_rows, ant1.dtype)
        ant2_avg = np.empty(out_rows, ant2.dtype)

        # Possibly present outputs for possibly present inputs
        uvw_avg = (
            None
            if not have_uvw
            else np.zeros((out_rows,) + uvw.shape[1:], dtype=uvw.dtype)
        )

        time_centroid_avg = (
            None
            if not have_time_centroid
            else np.zeros(
                (out_rows,) + time_centroid.shape[1:], dtype=time_centroid.dtype
            )
        )

        exposure_avg = (
            None
            if not have_exposure
            else np.zeros((out_rows,) + exposure.shape[1:], dtype=exposure.dtype)
        )

        weight_avg = (
            None
            if not have_weight
            else np.zeros((out_rows,) + weight.shape[1:], dtype=weight.dtype)
        )

        sigma_avg = (
            None
            if not have_sigma
            else np.zeros((out_rows,) + sigma.shape[1:], dtype=sigma.dtype)
        )

        sigma_weight_sum = (
            None
            if not have_sigma
            else np.zeros((out_rows,) + sigma.shape[1:], dtype=sigma.dtype)
        )

        # Average each array, if present
        # The output is a flattened row-channel array
        # where the values for each row are repeated along the channel
        # Individual runs in this output are described by meta.offset
        # Thus, we only compute the sum in the first position
        for ri in range(meta.map.shape[0]):
            ro = meta.map[ri, 0]

            # Here we can simply assign because input_row baselines
            # should always match output row baselines
            ant1_avg[ro] = ant1[ri]
            ant2_avg[ro] = ant2[ri]

            # Input and output flags must match in order for the
            # current row to contribute to these columns
            if have_flag_row and flag_row[ri] != meta.flag_row[ro]:
                continue

            counts[ro] += 1

            if have_uvw:
                uvw_avg[ro, 0] += uvw[ri, 0]
                uvw_avg[ro, 1] += uvw[ri, 1]
                uvw_avg[ro, 2] += uvw[ri, 2]

            if have_time_centroid:
                time_centroid_avg[ro] += time_centroid[ri]

            if have_exposure:
                exposure_avg[ro] += exposure[ri]

            if have_weight:
                for co in range(weight.shape[1]):
                    weight_avg[ro, co] += weight[ri, co]

            if have_sigma:
                for co in range(sigma.shape[1]):
                    # Use weights if present else natural weights
                    wt = weight[ri, co] if have_weight else 1.0

                    # Aggregate
                    sigma_avg[ro, co] += sigma[ri, co] ** 2 * wt**2
                    sigma_weight_sum[ro, co] += wt

        # Normalise and copy
        for o in range(len(meta.offsets) - 1):
            bro = meta.offsets[o]
            nchan = meta.offsets[o + 1] - bro
            count = counts[bro]

            for c in range(1, nchan):
                ant1_avg[bro + c] = ant1_avg[bro]
                ant2_avg[bro + c] = ant2_avg[bro]

            if have_uvw:
                # Normalise channel 0 value
                if count > 0:
                    uvw_avg[bro, 0] /= count
                    uvw_avg[bro, 1] /= count
                    uvw_avg[bro, 2] /= count

                # Copy to other channels
                for c in range(1, nchan):
                    uvw_avg[bro + c, 0] += uvw_avg[bro, 0]
                    uvw_avg[bro + c, 1] += uvw_avg[bro, 1]
                    uvw_avg[bro + c, 2] += uvw_avg[bro, 2]

            if have_time_centroid:
                # Normalise channel 0 value
                if count > 0:
                    time_centroid_avg[bro] /= count

                # Copy to other channels
                for c in range(1, nchan):
                    time_centroid_avg[bro + c] = time_centroid_avg[bro]

            if have_exposure:
                # Copy to other channels
                for c in range(1, nchan):
                    exposure_avg[bro + c] = exposure_avg[bro]

            if have_weight:
                # Copy to other channels
                for c in range(1, nchan):
                    for co in range(weight.shape[1]):
                        weight_avg[bro + c, co] = weight_avg[bro, co]

            if have_sigma:
                # Normalise channel 0 values
                for co in range(sigma.shape[1]):
                    sswsum = sigma_weight_sum[bro, co]

                    if sswsum != 0.0:
                        ssva = sigma_avg[bro, co]
                        sigma_avg[bro, co] = np.sqrt(ssva / (sswsum**2))

                # Copy values to other channels
                for c in range(1, nchan):
                    for co in range(sigma.shape[1]):
                        sigma_avg[bro + c, co] = sigma_avg[bro, co]

        return RowAverageOutput(
            ant1_avg,
            ant2_avg,
            time_centroid_avg,
            exposure_avg,
            uvw_avg,
            weight_avg,
            sigma_avg,
        )

    return impl


_rowchan_output_fields = ["visibilities", "flag", "weight_spectrum", "sigma_spectrum"]
RowChanAverageOutput = namedtuple("RowChanAverageOutput", _rowchan_output_fields)


class RowChannelAverageException(Exception):
    pass


@intrinsic
def average_visibilities(
    typingctx, vis, vis_avg, vis_weight_sum, weight, ri, fi, ro, co
):
    import numba.core.types as nbtypes

    have_array = isinstance(vis, nbtypes.Array)
    have_tuple = isinstance(vis, (nbtypes.Tuple, nbtypes.UniTuple))

    def avg_fn(vis, vis_avg, vis_ws, wt, ri, fi, ro, co):
        vis_avg[ro, co] += vis[ri, fi, co] * wt
        vis_ws[ro, co] += wt

    return_type = nbtypes.NoneType("none")

    sig = return_type(vis, vis_avg, vis_weight_sum, weight, ri, fi, ro, co)

    def codegen(context, builder, signature, args):
        vis, vis_type = args[0], signature.args[0]
        vis_avg, vis_avg_type = args[1], signature.args[1]
        vis_weight_sum, vis_weight_sum_type = args[2], signature.args[2]
        weight, weight_type = args[3], signature.args[3]
        ri, ri_type = args[4], signature.args[4]
        fi, fi_type = args[5], signature.args[5]
        ro, ro_type = args[6], signature.args[6]
        co, co_type = args[7], signature.args[7]
        return_type = signature.return_type

        if have_array:
            avg_sig = return_type(
                vis_type,
                vis_avg_type,
                vis_weight_sum_type,
                weight_type,
                ri_type,
                fi_type,
                ro_type,
                co_type,
            )
            avg_args = [vis, vis_avg, vis_weight_sum, weight, ri, fi, ro, co]

            # Compile function and get handle to output
            context.compile_internal(builder, avg_fn, avg_sig, avg_args)
        elif have_tuple:
            for i in range(len(vis_type)):
                avg_sig = return_type(
                    vis_type.types[i],
                    vis_avg_type.types[i],
                    vis_weight_sum_type.types[i],
                    weight_type,
                    ri_type,
                    fi_type,
                    ro_type,
                    co_type,
                )
                avg_args = [
                    builder.extract_value(vis, i),
                    builder.extract_value(vis_avg, i),
                    builder.extract_value(vis_weight_sum, i),
                    weight,
                    ri,
                    fi,
                    ro,
                    co,
                ]

                # Compile function and get handle to output
                context.compile_internal(builder, avg_fn, avg_sig, avg_args)
        else:
            raise TypeError("Unhandled visibility array type")

    return sig, codegen


@intrinsic
def normalise_visibilities(typingctx, vis_avg, vis_weight_sum, ro, co):
    import numba.core.types as nbtypes

    have_array = isinstance(vis_avg, nbtypes.Array)
    have_tuple = isinstance(vis_avg, (nbtypes.Tuple, nbtypes.UniTuple))

    def normalise_fn(vis_avg, vis_ws, ro, co):
        weight_sum = vis_ws[ro, co]

        if weight_sum != 0.0:
            vis_avg[ro, co] /= weight_sum

    return_type = nbtypes.NoneType("none")
    sig = return_type(vis_avg, vis_weight_sum, ro, co)

    def codegen(context, builder, signature, args):
        vis_avg, vis_avg_type = args[0], signature.args[0]
        vis_weight_sum, vis_weight_sum_type = args[1], signature.args[1]
        ro, ro_type = args[2], signature.args[2]
        co, co_type = args[3], signature.args[3]
        return_type = signature.return_type

        if have_array:
            # Normalise single array
            norm_sig = return_type(vis_avg_type, vis_weight_sum_type, ro_type, co_type)
            norm_args = [vis_avg, vis_weight_sum, ro, co]

            context.compile_internal(builder, normalise_fn, norm_sig, norm_args)
        elif have_tuple:
            # Normalise each array in the tuple
            for i in range(len(vis_avg_type)):
                norm_sig = return_type(
                    vis_avg_type.types[i],
                    vis_weight_sum_type.types[i],
                    ro_type,
                    co_type,
                )
                norm_args = [
                    builder.extract_value(vis_avg, i),
                    builder.extract_value(vis_weight_sum, i),
                    ro,
                    co,
                ]

                # Compile function and get handle to output
                context.compile_internal(builder, normalise_fn, norm_sig, norm_args)
        else:
            raise TypeError("Unhandled visibility array type")

    return sig, codegen


@njit(**JIT_OPTIONS)
def row_chan_average(
    meta,
    flag_row=None,
    weight=None,
    visibilities=None,
    flag=None,
    weight_spectrum=None,
    sigma_spectrum=None,
):
    return row_chan_average_impl(
        meta,
        flag_row=flag_row,
        weight=weight,
        visibilities=visibilities,
        flag=flag,
        weight_spectrum=weight_spectrum,
        sigma_spectrum=sigma_spectrum,
    )


def row_chan_average_impl(
    meta,
    flag_row=None,
    weight=None,
    visibilities=None,
    flag=None,
    weight_spectrum=None,
    sigma_spectrum=None,
):
    return NotImplementedError


@overload(row_chan_average_impl, jit_options=JIT_OPTIONS)
def nb_row_chan_average(
    meta,
    flag_row=None,
    weight=None,
    visibilities=None,
    flag=None,
    weight_spectrum=None,
    sigma_spectrum=None,
):
    have_vis = not is_numba_type_none(visibilities)
    have_flag = not is_numba_type_none(flag)
    have_flag_row = not is_numba_type_none(flag_row)
    have_flags = have_flag_row or have_flag

    have_weight = not is_numba_type_none(weight)
    have_weight_spectrum = not is_numba_type_none(weight_spectrum)
    have_sigma_spectrum = not is_numba_type_none(sigma_spectrum)

    def impl(
        meta,
        flag_row=None,
        weight=None,
        visibilities=None,
        flag=None,
        weight_spectrum=None,
        sigma_spectrum=None,
    ):
        out_rows = meta.time.shape[0]
        nchan, ncorrs = chan_corrs(
            visibilities, flag, weight_spectrum, sigma_spectrum, None, None, None, None
        )

        out_shape = (out_rows, ncorrs)

        if not have_flag:
            flag_avg = None
        else:
            flag_avg = np.zeros(out_shape, np.bool_)

        # If either flag_row or flag is present, we need to ensure that
        # effective averaging takes place.
        if have_flags:
            flags_match = np.zeros(meta.map.shape + (ncorrs,), dtype=np.bool_)
            flag_counts = np.zeros(out_shape, dtype=np.uint32)
        else:
            flags_match = None
            flag_counts = None

        counts = np.zeros(out_shape, dtype=np.uint32)

        # Determine output bin counts both unflagged and flagged
        for ri in range(meta.map.shape[0]):
            row_flagged = have_flag_row and flag_row[ri] != 0
            for fi in range(meta.map.shape[1]):
                ro = meta.map[ri, fi]

                for co in range(ncorrs):
                    flagged = row_flagged or (have_flag and flag[ri, fi, co] != 0)

                    if have_flags and flagged:
                        flag_counts[ro, co] += 1
                    else:
                        counts[ro, co] += 1

        # ------
        # Flags
        # ------

        # Determine whether input samples should contribute to an output bin
        # and, if flags are parent, whether the output bin is flagged

        # This follows from the definition of an effective average:
        #
        # * bad or flagged values should be excluded
        #   when calculating the average
        #
        # Note that if a bin is completely flagged we still compute an average,
        # to which all relevant input samples contribute.
        for ri in range(meta.map.shape[0]):
            row_flagged = have_flag_row and flag_row[ri] != 0
            for fi in range(meta.map.shape[1]):
                ro = meta.map[ri, fi]

                for co in range(ncorrs):
                    if counts[ro, co] > 0:
                        # Output bin should only contain unflagged samples
                        out_flag = False

                        if have_flag:
                            # Set output flags
                            flag_avg[ro, co] = False

                    elif have_flags and flag_counts[ro, co] > 0:
                        # Output bin is completely flagged
                        out_flag = True

                        if have_flag:
                            # Set output flags
                            flag_avg[ro, co] = True
                    else:
                        raise RowChannelAverageException("Zero-filled bin")

                    # We should only add a sample to an output bin
                    # if the input flag matches the output flag.
                    # This is because flagged samples don't contribute
                    # to a bin with some unflagged samples while
                    # unflagged samples never contribute to a
                    # completely flagged bin
                    if have_flags:
                        in_flag = row_flagged or (have_flag and flag[ri, fi, co] != 0)
                        flags_match[ri, fi, co] = in_flag == out_flag

        # -------------
        # Visibilities
        # -------------
        if not have_vis:
            vis_avg = None
        else:
            vis_avg, vis_weight_sum = vis_output_arrays(visibilities, out_shape)

            # Aggregate
            for ri in range(meta.map.shape[0]):
                for fi in range(meta.map.shape[1]):
                    ro = meta.map[ri, fi]

                    for co in range(ncorrs):
                        if have_flags and not flags_match[ri, fi, co]:
                            continue

                        wt = (
                            weight_spectrum[ri, fi, co]
                            if have_weight_spectrum
                            else weight[ri, co]
                            if have_weight
                            else 1.0
                        )

                        average_visibilities(
                            visibilities, vis_avg, vis_weight_sum, wt, ri, fi, ro, co
                        )

            # Normalise
            for ro in range(out_rows):
                for co in range(ncorrs):
                    normalise_visibilities(vis_avg, vis_weight_sum, ro, co)

        # ----------------
        # Weight Spectrum
        # ----------------
        if not have_weight_spectrum:
            weight_spectrum_avg = None
        else:
            weight_spectrum_avg = np.zeros(out_shape, weight_spectrum.dtype)

            # Aggregate
            for ri in range(meta.map.shape[0]):
                for fi in range(meta.map.shape[1]):
                    ro = meta.map[ri, fi]

                    for co in range(ncorrs):
                        if have_flags and not flags_match[ri, fi, co]:
                            continue

                        weight_spectrum_avg[ro, co] += weight_spectrum[ri, fi, co]

        # ---------------
        # Sigma Spectrum
        # ---------------
        if not have_sigma_spectrum:
            sigma_spectrum_avg = None
        else:
            sigma_spectrum_avg = np.zeros(out_shape, sigma_spectrum.dtype)
            sigma_spectrum_weight_sum = np.zeros_like(sigma_spectrum_avg)

            # Aggregate
            for ri in range(meta.map.shape[0]):
                for fi in range(meta.map.shape[1]):
                    ro = meta.map[ri, fi]

                    for co in range(ncorrs):
                        if have_flags and not flags_match[ri, fi, co]:
                            continue

                        wt = (
                            weight_spectrum[ri, fi, co]
                            if have_weight_spectrum
                            else weight[ri, co]
                            if have_weight
                            else 1.0
                        )

                        ssv = sigma_spectrum[ri, fi, co] ** 2 * wt**2
                        sigma_spectrum_avg[ro, co] += ssv
                        sigma_spectrum_weight_sum[ro, co] += wt

            # Normalise
            for ro in range(out_rows):
                for co in range(ncorrs):
                    if sigma_spectrum_weight_sum[ro, co] != 0.0:
                        ssv = sigma_spectrum_avg[ro, co]
                        sswsum = sigma_spectrum_weight_sum[ro, co]
                        sigma_spectrum_avg[ro, co] = np.sqrt(ssv / sswsum**2)

        return RowChanAverageOutput(
            vis_avg, flag_avg, weight_spectrum_avg, sigma_spectrum_avg
        )

    return impl


_chan_output_fields = ["chan_freq", "chan_width", "effective_bw", "resolution"]
ChannelAverageOutput = namedtuple("ChannelAverageOutput", _chan_output_fields)


AverageOutput = namedtuple(
    "AverageOutput",
    list(RowMapOutput._fields)
    + _row_output_fields
    +
    # _chan_output_fields +
    _rowchan_output_fields,
)


[docs] @njit(**JIT_OPTIONS) def bda( time, interval, antenna1, antenna2, time_centroid=None, exposure=None, flag_row=None, uvw=None, weight=None, sigma=None, chan_freq=None, chan_width=None, effective_bw=None, resolution=None, visibilities=None, flag=None, weight_spectrum=None, sigma_spectrum=None, max_uvw_dist=None, max_fov=3.0, decorrelation=0.98, time_bin_secs=None, min_nchan=1, ): return bda_impl( time, interval, antenna1, antenna2, time_centroid=time_centroid, exposure=exposure, flag_row=flag_row, uvw=uvw, weight=weight, sigma=sigma, chan_freq=chan_freq, chan_width=chan_width, effective_bw=effective_bw, resolution=resolution, visibilities=visibilities, flag=flag, weight_spectrum=weight_spectrum, sigma_spectrum=sigma_spectrum, max_uvw_dist=max_uvw_dist, max_fov=max_fov, decorrelation=decorrelation, time_bin_secs=time_bin_secs, min_nchan=min_nchan, )
def bda_impl( time, interval, antenna1, antenna2, time_centroid=None, exposure=None, flag_row=None, uvw=None, weight=None, sigma=None, chan_freq=None, chan_width=None, effective_bw=None, resolution=None, visibilities=None, flag=None, weight_spectrum=None, sigma_spectrum=None, max_uvw_dist=None, max_fov=3.0, decorrelation=0.98, time_bin_secs=None, min_nchan=1, ): return NotImplementedError @overload(bda_impl, jit_options=JIT_OPTIONS) def nb_bda_impl( time, interval, antenna1, antenna2, time_centroid=None, exposure=None, flag_row=None, uvw=None, weight=None, sigma=None, chan_freq=None, chan_width=None, effective_bw=None, resolution=None, visibilities=None, flag=None, weight_spectrum=None, sigma_spectrum=None, max_uvw_dist=None, max_fov=3.0, decorrelation=0.98, time_bin_secs=None, min_nchan=1, ): # Merge flag_row and flag arrays flag_row = merge_flags(flag_row, flag) meta = bda_mapper( time, interval, antenna1, antenna2, uvw, chan_width, chan_freq, max_uvw_dist, flag_row=flag_row, max_fov=max_fov, decorrelation=decorrelation, time_bin_secs=time_bin_secs, min_nchan=min_nchan, ) row_avg = row_average( meta, antenna1, antenna2, flag_row, # noqa: F841 time_centroid, exposure, uvw, weight=weight, sigma=sigma, ) row_chan_avg = row_chan_average( meta, # noqa: F841 flag_row=flag_row, visibilities=visibilities, flag=flag, weight_spectrum=weight_spectrum, sigma_spectrum=sigma_spectrum, ) # Have to explicitly write it out because numba tuples # are highly constrained types return AverageOutput( meta.map, meta.offsets, meta.decorr_chan_width, meta.time, meta.interval, meta.chan_width, meta.flag_row, row_avg.antenna1, row_avg.antenna2, row_avg.time_centroid, row_avg.exposure, row_avg.uvw, row_avg.weight, row_avg.sigma, # None, # chan_data.chan_freq, # None, # chan_data.chan_width, # None, # chan_data.effective_bw, # None, # chan_data.resolution, row_chan_avg.visibilities, row_chan_avg.flag, row_chan_avg.weight_spectrum, row_chan_avg.sigma_spectrum, ) BDA_DOCS = DocstringTemplate( """ Averages in time and channel, dependent on baseline length. Parameters ---------- time : $(array_type) Time values of shape :code:`(row,)`. interval : $(array_type) Interval values of shape :code:`(row,)`. antenna1 : $(array_type) First antenna indices of shape :code:`(row,)` antenna2 : $(array_type) Second antenna indices of shape :code:`(row,)` time_centroid : $(array_type), optional Time centroid values of shape :code:`(row,)` exposure : $(array_type), optional Exposure values of shape :code:`(row,)` flag_row : $(array_type), optional Flagged rows of shape :code:`(row,)`. uvw : $(array_type), optional UVW coordinates of shape :code:`(row, 3)`. weight : $(array_type), optional Weight values of shape :code:`(row, corr)`. sigma : $(array_type), optional Sigma values of shape :code:`(row, corr)`. chan_freq : $(array_type), optional Channel frequencies of shape :code:`(chan,)`. chan_width : $(array_type), optional Channel widths of shape :code:`(chan,)`. effective_bw : $(array_type), optional Effective channel bandwidth of shape :code:`(chan,)`. resolution : $(array_type), optional Effective channel resolution of shape :code:`(chan,)`. visibilities : $(array_type) or tuple of $(array_type), optional Visibility data of shape :code:`(row, chan, corr)`. Tuples of visibilities arrays may be supplied, in which case tuples will be output. flag : $(array_type), optional Flag data of shape :code:`(row, chan, corr)`. weight_spectrum : $(array_type), optional Weight spectrum of shape :code:`(row, chan, corr)`. sigma_spectrum : $(array_type), optional Sigma spectrum of shape :code:`(row, chan, corr)`. max_uvw_dist : float, optional Maximum UVW distance. Will be inferred from the UVW coordinates if not supplied. max_fov : float Maximum Field of View Radius. Defaults to 3 degrees. decorrelation : float Acceptable amount of decorrelation. This is a floating point value between 0.0 and 1.0. time_bin_secs : float, optional Maximum number of seconds worth of data that can be aggregated into a bin. Defaults to None in which case the value is only bounded by the decorrelation factor and the field of view. min_nchan : int, optional Minimum number of channels in an averaged sample. Useful in cases where imagers expect at least `min_nchan` channels. Defaults to 1. Notes ----- In all cases arrays starting with :code:`(row, chan)` and :code:`(row,)` dimensions are respectively averaged and expanded into a :code:`(rowchan,)` dimension, as the number of channels varies per output row. The output namedtuple contains an `offsets` array of shape :code:`(out_rows + 1,)` encoding the starting offsets of each output row, as well as a single entry at the end such that :code:`np.diff(offsets)` produces the number of channels for each output row. .. code-block:: python avg = bda(...) time = avg.time[avg.offsets[:-1]] out_chans = np.diff(avg.offsets) The implementation currently requires unique lexicographical combinations of (TIME, ANTENNA1, ANTENNA2). This can usually be achieved by suitably partitioning input data on indexing rows, DATA_DESC_ID and SCAN_NUMBER in particular. Returns ------- namedtuple A namedtuple whose entries correspond to the input arrays. Output arrays will be ``None`` if the inputs were ``None``. See the Notes for an explanation of the output formats. """ ) try: bda.__doc__ = BDA_DOCS.substitute(array_type=":class:`numpy.ndarray`") except AttributeError: pass