Creating search grids

API references

class doatools.estimation.grid.SearchGrid(axes, axis_names, units)[source]

Bases: abc.ABC

Base class for all search grids. Provides standard implementation.

Parameters:
  • axes – A tuple of 1D ndarrays representing the axes of this search grid. The source locations on this search grid will be generated from these axes.
  • axis_names – A tuple of strings denoting the names of the axes.
  • units (str) – A tuple of strings representing the unit used for each axis.
ndim

Retrieves the number of dimensions of this search grid.

size

Retrieves the number of elements on this search grid.

shape

Retrieves the shape of this search grid.

Returns:A tuple of integers representing the shape.
source_placement

Retrieves the source placement based on this grid.

For a multi-dimensional search grid with shape \((d_1, d_2, \ldots, d_n)\), the returned SourcePlacement instance will contain \(d_1 \times d_2 \times \cdots \times d_n\) elements, which are ordered in such a way that the first dimension changes the slowest, the second dimension changes the second slowest, and so on. For instance, the elements in the following 2x3 grid

(1, 1) (1, 2) (1, 3)
(2, 1) (2, 2) (2, 3)

will be ordered as

(1, 1) (1, 2) (1, 3) (2, 1) (2, 2) (2, 3)

Do not modify.

units

Retrieves a tuple of strings representing the unit used for each axis.

axes

Retrieves a tuple of 1D numpy vectors representing the axes.

The sources locations can be recovered with the Cartesian product over (axes[0], axes[1], ...).

Do not modify.

axis_names

Retrieves a tuple of strings representing the axis names.

create_refined_axes_at(coord, density, span)[source]

Creates a new set of axes by subdividing the grids around the input coordinate into finer grids. These new axes can then be used to create refined grids.

For instance, suppose that the original grid is a 2D grid with the axes:

Axis name Axis data
Azimuth [0, 10, 20, 30, 40]
Elevation [0, 20, 40]

Suppose that coord is (3, 1), density is 4, and span is 1. Then the following set of axes will be created:

Refined axes around the coordinate (3, 1) (or azimuth = 30, elevation = 20):

Axis name Axis data
Azimuth [20, 22.5, 25.0, 27.5, 30, 32.5, 35, 37.5, 40]
Elevation [0, 5, 10, 15, 20, 25, 30, 35, 40]
Parameters:
  • coord – A tuple of integers representing a single coordinate within this grid.
  • density (int) – Controls number of new intervals between two adjacent points in the original grid.
  • span (int) – Controls how many adjacent intervals in the original grid will be considered around the point specified by coord when performing the refinement.
Returns:

A tuple of ndarrays representing the refined axes.
create_refined_grids_at(*coords, **kwargs)[source]

Creates multiple new search grids around the given coordinates.

Parameters:
  • *coords – A sequence of list-like objects representing the coordinates of the grid points around which the refinement will be performed. The length of coords should be equal to the number of dimensions of this grid. The list-like objects in coords should share the same length. coords[j][i] denotes the j-th element of the i-th coordinate.
  • density (int) – Controls number of new intervals between two adjacent points in the original grid.
  • span (int) – Controls how many adjacent intervals in the original grid will be considered around the point specified by coords when performing the refinement.
Returns:

A list of refined grids.
create_refined_grid_at(coord, density, span)[source]

Creates a finer search grid around the given coordinate.

Parameters:
  • coord – A tuple of integers representing a single coordinate within this grid.
  • density (int) – Controls number of new intervals between two adjacent points in the original grid.
  • span (int) – Controls how many adjacent intervals in the original grid will be considered around the point specified by coord when performing the refinement.
Returns:

A refined grid.
class doatools.estimation.grid.FarField1DSearchGrid(start=None, stop=None, size=180, unit='rad', axes=None)[source]

Bases: doatools.estimation.grid.SearchGrid

Creates a search grid for 1D far-field source localization.

When both start and stop are scalars, the resulting search grid consists only one uniform grid. When both start and stop are lists the resulting search grid is a combination of multiple uniform grids specified by start[k], stop[k], and size[k].

Parameters:
  • start (float) –

    A scalar of the starting angle or a list of starting angles. If not specified, the following default values will be used depending on unit:

    • 'rad': \(-\pi/2\)
    • 'deg': -90,
    • 'sin': -1
  • stop (float) –

    A scalar of the stopping angle or a list of stopping angles. This angle is not included in the grid. If not specified, the following default values will be used depending on unit:

    • 'rad': \(\pi/2\)
    • 'deg': 90
    • 'sin': 1
  • size (int) – Specifies the grid size. If both start and stop are lists, size must also be a list such that ‘size[k]’ specifies the number of grid points between start[k] and stop[k]. Default value is 180.
  • unit (str) – Can be 'rad' (default), 'deg' or 'sin'.
  • axes – A tuple of 1D ndarrays representing the axes of the search grid. If specified, start, stop, and size will be ignored and the search grid will be generated based only on axes and units. Default value is None.
Returns:

A search grid for 1D far-field source localization.
create_refined_grid_at(coord, density=10, span=1)[source]

Creates a finer search grid for 1D far-field sources.

Parameters:
  • coord – A tuple of integers representing a single coordinate within this grid.
  • density (int) – Controls number of new intervals between two adjacent points in the original grid. Default value is 10.
  • span (int) – Controls how many adjacent intervals in the original grid will be considered around the point specified by coord when performing the refinement. Default value is 1.
Returns:

A refined 1D far-field search grid.
class doatools.estimation.grid.FarField2DSearchGrid(start=None, stop=None, size=(360, 90), unit='rad', axes=None)[source]

Bases: doatools.estimation.grid.SearchGrid

Creates a search grid for 2D far-field source localization.

The first dimension corresponds to the azimuth angle, and the second dimension corresponds to the elevation angle.

Parameters:
  • start –

    A two-element list-like object containing the starting azimuth and elevation angles. If not specified, the following default values will be used depending on unit:

    • 'rad': (\(-\pi\), 0)
    • 'deg': (-180, 0)
  • stop –

    A two-element list-like object containing the stopping azimuth and elevation angles. These two angles are not included in the search grid. If not specified, the following default values will be used depending on unit:

    • 'rad': (\(\pi\), \(\pi/2\))
    • 'deg': (180, 90)
  • size – A scalar or a two-element list-like object specifying the size of the search grid. If size is a scalar, a size by size grid will be created. If size is a two-element list-like object, a size[0] by size[1] grid will be created. Default value is (360, 90).
  • unit (str) – Can be 'rad' (default) or 'deg'.
  • axes – A tuple of 1D ndarrays representing the axes of the search grid. If specified, start, stop, and size will be ignored and the search grid will be generated based only on axes and units. Default value is None.
Returns:

A search grid for 2D far-field source localization.
create_refined_grid_at(coord, density=10, span=1)[source]

Creates a finer search grid for 2D far-field sources.

Parameters:
  • coord – A tuple of integers representing a single coordinate within this grid.
  • density (int) – Controls number of new intervals between two adjacent points in the original grid. Default value is 10.
  • span (int) – Controls how many adjacent intervals in the original grid will be considered around the point specified by coord when performing the refinement. Default value is 1.
Returns:

A refined 2D far-field search grid.
class doatools.estimation.grid.NearField2DSearchGrid(start=None, stop=None, size=None, axes=None)[source]

Bases: doatools.estimation.grid.SearchGrid

Creates a search grid for 2D near-field source localization.

The first dimension corresponds to the x coordinate, and the second dimension corresponds to the y coordinate.

Parameters:
  • start – A two-element list-like object containing the starting x and y coordinates.
  • stop – A two-element list-like object containing the stopping x and y coordinates. These two coordinates are not included in the search grid.
  • size – A scalar or a two-element list-like object specifying the size of the search grid. If size is a scalar, a size by size grid will be created. If size is a two-element list-like object, a size[0] by size[1] grid will be created. Default value is (360, 90).
  • axes – A tuple of 1D ndarrays representing the axes of the search grid. If specified, start, stop, and size will be ignored and the search grid will be generated based only on axes and units. Default value is None.
Returns:

A search grid for 2D near-field source localization.
create_refined_grids_at(coord, density=10, span=1)[source]

Creates a finer search grid for 2D near-field sources.

Parameters:
  • coord – A tuple of integers representing a single coordinate within this grid.
  • density (int) – Controls number of new intervals between two adjacent points in the original grid. Default value is 10.
  • span (int) – Controls how many adjacent intervals in the original grid will be considered around the point specified by coord when performing the refinement. Default value is 1.
Returns:

A refined 2D near-field search grid.