canvod.grids API reference¶

Bases: ABC

Abstract base for hemispherical grid builders.

Parameters:

Immutable container for hemispherical grid structure.

Parameters:

Bases: Enum

Available grid projection types for hemispherical tessellation.

Bases: BaseGridBuilder

Equal solid angle tessellation using concentric theta bands.

The hemisphere is divided into annular bands of constant width in theta. Within each band the number of azimuthal (phi) sectors is chosen so that every cell subtends approximately the same solid angle. This is the only grid type that has been validated for scientific use in this codebase.

Parameters:

Bases: BaseGridBuilder

Equal angular spacing in both theta and phi (NOT equal area).

Every cell is a rectangle of the same angular size Δθ × Δφ in the (theta, phi) parameter space. A cell's solid angle is Δφ · (cos θ_min − cos θ_max) ≈ Δφ · Δθ · sin θ, so cells near the zenith subtend less solid angle than cells near the horizon. A statistic that weights every cell equally therefore gives the sky near the zenith more weight than its share of the hemisphere. Not recommended for scientific analysis – use EqualAreaBuilder instead.

n_phi = floor(2π / Δθ)

Parameters:

Bases: BaseGridBuilder

Simple rectangular grid in (theta, phi) space.

The hemisphere is divided into a regular rectangular array: a constant number of theta bands, each containing the same constant number of phi sectors. Every cell is a rectangle of the same angular size in (theta, phi), except the last band and the last sector, which are narrower when Δθ does not divide their range. It differs from EqualAngleBuilder at the zenith: EqualAngleBuilder makes the innermost half band a single zenith cap and puts its band edges half a band off, while this builder starts the first band at the zenith with the same number of sectors as every other band.

A cell's solid angle is Δφ · (cos θ_min − cos θ_max) ≈ Δφ · Δθ · sin θ, so cells near the zenith subtend less solid angle than cells near the horizon. A statistic that weights every cell equally therefore gives the sky near the zenith more weight than its share of the hemisphere. Not recommended for scientific analysis – use EqualAreaBuilder instead.

n_theta = ceil((π/2 − cutoff) / Δθ)
n_phi   = ceil(2π / Δθ)
total cells = n_theta × n_phi

Parameters:

Bases: BaseGridBuilder

HEALPix tessellation (Hierarchical Equal Area isoLatitude Pixelization).

HEALPix partitions the sphere into 12 base pixels arranged at equal latitudes. Each base pixel is recursively subdivided into 4 children, producing 12 × nside² pixels on the full sphere, all with exactly the same solid angle. This strict equal-area property makes HEALPix the gold standard for pixelisations that must be unbiased under solid-angle weighting.

This builder delegates the pixel geometry entirely to the healpy library. It filters the full-sphere pixelisation down to the northern hemisphere and stores approximate bounding boxes (phi_min/max, theta_min/max) derived from the pixel resolution. The bounding boxes are not the true pixel boundaries (which are curvilinear); they are only approximations suitable for quick spatial queries. For exact pixel membership use healpy.ang2pix directly.

n_pixels   = 12 × nside²           (full sphere)
pixel_area = 4π / n_pixels          (steradians, exact)
resolution ≈ √(pixel_area)          (approximate angular diameter)
           ≈ 58.6° / nside         (degrees)

nside_estimate = round_to_pow2( √(3/π) × 60 / angular_resolution )

Parameters:

Raises:

Bases: BaseGridBuilder

Geodesic grid based on a subdivided icosahedron.

The sphere is tessellated into triangular cells by starting with an icosahedron (20 equilateral triangles) and recursively subdividing each triangle into four smaller triangles. All vertices are projected back onto the unit sphere after each subdivision step, so the final cells are spherical triangles. The grid has no polar singularity and provides near-uniform cell areas, though strict equal-area is not guaranteed — cell areas vary by a few percent depending on how they inherit the icosahedral symmetry axes.

target_edge ≈ 2 × angular_resolution   (degrees)
subdivision_level = ceil(log₂(63.4 / target_edge))

edge ≈ 63.4° / 2ⁿ   (degrees)

Parameters:

Bases: BaseGridBuilder

Fibonacci sphere grid with spherical Voronoi tessellation.

Points are distributed on the sphere using the Fibonacci lattice (golden-spiral method), which provides one of the most uniform point distributions achievable on a sphere without iterative optimization. Each point then becomes the center of a spherical Voronoi cell — the region of the sphere closer to that point than to any other. The resulting tessellation has no polar singularities and near-uniform cell areas.

The tessellation is computed by scipy.spatial.SphericalVoronoi. Because Voronoi cells have curvilinear boundaries, the phi_min/max and theta_min/max columns in the grid are axis-aligned bounding boxes, not the true cell boundaries. They are unreliable for spatial queries — use the voronoi_region column (vertex indices into the SphericalVoronoi.vertices array) for exact geometry.

cell_area  ≈ angular_resolution²   (radians²)
n_points   = max(10, round(2π / cell_area))

d ≈ 2 √(2π / n_points)   (radians)
  ≈ 2 × angular_resolution

Parameters:

Raises:

Bases: BaseGridBuilder

Hierarchical Triangular Mesh (HTM) grid.

HTM divides the sphere into an octahedron (8 triangular faces), then recursively subdivides each face into 4 smaller triangles by inserting edge-midpoint vertices projected onto the unit sphere. The recursion depth is controlled by htm_level. This produces a strictly hierarchical triangulation: every triangle at level n is the union of exactly 4 triangles at level n + 1.

Cell areas are approximately equal but not strictly so — area uniformity improves with level because the icosahedral edge-length asymmetry averages out over many subdivisions.

target_edge ≈ 2 × angular_resolution   (degrees)
htm_level   = min(15, ceil(log₂(90 / target_edge)))

edge ≈ 90° / 2ⁿ

Parameters:

Polars-based per-cell aggregation helpers.

Bases: ABC

Abstract base for hemispherical grid builders.

Parameters:

Immutable container for hemispherical grid structure.

Parameters:

Bases: Enum

Available grid projection types for hemispherical tessellation.

Bases: BaseGridBuilder

Equal solid angle tessellation using concentric theta bands.

The hemisphere is divided into annular bands of constant width in theta. Within each band the number of azimuthal (phi) sectors is chosen so that every cell subtends approximately the same solid angle. This is the only grid type that has been validated for scientific use in this codebase.

Parameters:

Bases: BaseGridBuilder

Equal angular spacing in both theta and phi (NOT equal area).

Every cell is a rectangle of the same angular size Δθ × Δφ in the (theta, phi) parameter space. A cell's solid angle is Δφ · (cos θ_min − cos θ_max) ≈ Δφ · Δθ · sin θ, so cells near the zenith subtend less solid angle than cells near the horizon. A statistic that weights every cell equally therefore gives the sky near the zenith more weight than its share of the hemisphere. Not recommended for scientific analysis – use EqualAreaBuilder instead.

n_phi = floor(2π / Δθ)

Parameters:

Bases: BaseGridBuilder

Simple rectangular grid in (theta, phi) space.

The hemisphere is divided into a regular rectangular array: a constant number of theta bands, each containing the same constant number of phi sectors. Every cell is a rectangle of the same angular size in (theta, phi), except the last band and the last sector, which are narrower when Δθ does not divide their range. It differs from EqualAngleBuilder at the zenith: EqualAngleBuilder makes the innermost half band a single zenith cap and puts its band edges half a band off, while this builder starts the first band at the zenith with the same number of sectors as every other band.

A cell's solid angle is Δφ · (cos θ_min − cos θ_max) ≈ Δφ · Δθ · sin θ, so cells near the zenith subtend less solid angle than cells near the horizon. A statistic that weights every cell equally therefore gives the sky near the zenith more weight than its share of the hemisphere. Not recommended for scientific analysis – use EqualAreaBuilder instead.

n_theta = ceil((π/2 − cutoff) / Δθ)
n_phi   = ceil(2π / Δθ)
total cells = n_theta × n_phi

Parameters:

Bases: BaseGridBuilder

HEALPix tessellation (Hierarchical Equal Area isoLatitude Pixelization).

HEALPix partitions the sphere into 12 base pixels arranged at equal latitudes. Each base pixel is recursively subdivided into 4 children, producing 12 × nside² pixels on the full sphere, all with exactly the same solid angle. This strict equal-area property makes HEALPix the gold standard for pixelisations that must be unbiased under solid-angle weighting.

This builder delegates the pixel geometry entirely to the healpy library. It filters the full-sphere pixelisation down to the northern hemisphere and stores approximate bounding boxes (phi_min/max, theta_min/max) derived from the pixel resolution. The bounding boxes are not the true pixel boundaries (which are curvilinear); they are only approximations suitable for quick spatial queries. For exact pixel membership use healpy.ang2pix directly.

n_pixels   = 12 × nside²           (full sphere)
pixel_area = 4π / n_pixels          (steradians, exact)
resolution ≈ √(pixel_area)          (approximate angular diameter)
           ≈ 58.6° / nside         (degrees)

nside_estimate = round_to_pow2( √(3/π) × 60 / angular_resolution )

Parameters:

Raises:

Bases: BaseGridBuilder

Geodesic grid based on a subdivided icosahedron.

The sphere is tessellated into triangular cells by starting with an icosahedron (20 equilateral triangles) and recursively subdividing each triangle into four smaller triangles. All vertices are projected back onto the unit sphere after each subdivision step, so the final cells are spherical triangles. The grid has no polar singularity and provides near-uniform cell areas, though strict equal-area is not guaranteed — cell areas vary by a few percent depending on how they inherit the icosahedral symmetry axes.

target_edge ≈ 2 × angular_resolution   (degrees)
subdivision_level = ceil(log₂(63.4 / target_edge))

edge ≈ 63.4° / 2ⁿ   (degrees)

Parameters:

Bases: BaseGridBuilder

Fibonacci sphere grid with spherical Voronoi tessellation.

Points are distributed on the sphere using the Fibonacci lattice (golden-spiral method), which provides one of the most uniform point distributions achievable on a sphere without iterative optimization. Each point then becomes the center of a spherical Voronoi cell — the region of the sphere closer to that point than to any other. The resulting tessellation has no polar singularities and near-uniform cell areas.

The tessellation is computed by scipy.spatial.SphericalVoronoi. Because Voronoi cells have curvilinear boundaries, the phi_min/max and theta_min/max columns in the grid are axis-aligned bounding boxes, not the true cell boundaries. They are unreliable for spatial queries — use the voronoi_region column (vertex indices into the SphericalVoronoi.vertices array) for exact geometry.

cell_area  ≈ angular_resolution²   (radians²)
n_points   = max(10, round(2π / cell_area))

d ≈ 2 √(2π / n_points)   (radians)
  ≈ 2 × angular_resolution

Parameters:

Raises:

Bases: BaseGridBuilder

Hierarchical Triangular Mesh (HTM) grid.

HTM divides the sphere into an octahedron (8 triangular faces), then recursively subdivides each face into 4 smaller triangles by inserting edge-midpoint vertices projected onto the unit sphere. The recursion depth is controlled by htm_level. This produces a strictly hierarchical triangulation: every triangle at level n is the union of exactly 4 triangles at level n + 1.

Cell areas are approximately equal but not strictly so — area uniformity improves with level because the icosahedral edge-length asymmetry averages out over many subdivisions.

target_edge ≈ 2 × angular_resolution   (degrees)
htm_level   = min(15, ceil(log₂(90 / target_edge)))

edge ≈ 90° / 2ⁿ

Parameters:

Polars-based per-cell aggregation helpers.

Bases: ABC

Base class for all filters. Filters NEVER modify original data.

Bases: Filter

Remove statistical outliers using z-score method.

Bases: Filter

Remove outliers using Interquartile Range method.

Bases: Filter

Filter values outside specified range.

Bases: Filter

Filter values outside percentile range.

Bases: Filter

Apply a user-supplied callable as filter.

Parameters:

Bases: Filter

Filter dataset by GNSS system, frequency band, and tracking code.

Operates on the sid dimension of a dataset, where SIDs have the format SV|Band|Code (e.g. G01|L1|C).

Parameters:

Examples:

>>> filt = SIDPatternFilter(system="G", band="L1", code="C")
>>> ds_gps_l1c = filt.filter_dataset(ds)

Manage multiple filters applied sequentially or combined.

Non-destructive: creates new DataArrays, never modifies originals.

Parameters:

Bases: ABC

Base class for per-cell filtering operations.

Sub-classes implement :meth:compute_cell_mask for a single cell's 1-D data array; the base class handles iteration over cells, auto-detection of the cell_id_* variable, and output assembly.

Bases: PerCellFilter

Per-cell IQR outlier rejection.

Values outside [Q1 − factor·IQR, Q3 + factor·IQR] are removed independently within each cell.

Bases: PerCellFilter

Per-cell z-score outlier rejection.

Values with |z| > threshold are removed independently within each cell.

Bases: PerCellFilter

Per-cell hard-bound range filter.

Identical bounds applied to every cell.

Bases: PerCellFilter

Per-cell percentile-bound filter.

Bounds are computed independently within each cell.

Sequential or combined multi-filter pipeline for per-cell filtering.

Parameters:

Create spatial masks for grid cells.

Masks are boolean arrays where True = include cell, False = exclude cell. Multiple constraints can be combined with AND or OR logic.

Parameters:

Examples:

>>> mask = SpatialMask(grid)
>>> mask.add_phi_range(0, np.pi)          # Northern hemisphere
>>> mask.add_theta_range(0, np.pi / 3)    # Exclude low elevations
>>> mask.add_quality_threshold('mean_snr', min_value=40)
>>> spatial_mask = mask.compute()          # Returns boolean array

>>> custom = np.array([True, False, True, ...])
>>> mask.add_custom_mask(custom)

>>> def high_snr_north(grid):
...     snr   = grid.grid['mean_snr'].to_numpy()
...     phi   = grid.grid['phi'].to_numpy()
...     return (snr > 40) & (phi < np.pi)
>>> mask.add_custom_mask(high_snr_north)

>>> # Northern sector, 30° wide, excluding low elevations
>>> mask.add_radial_sector(center_phi=0, sector_width=30,
...                        theta_max=60, degrees=True)