Skip to content

Axis

1-D monotonic axis (bin grid) and overlap-based bin reductions.

Grid

A 1-D monotonically increasing wavelength (or generic axis) grid.

Carries two orthogonal flags: spacing (linear vs log midpoint convention) and kind (whether values represent bin centers or bin edges). A Grid with kind="centers" and N values describes N bins; with kind="edges" and N values, N - 1 bins. Use to_edges() and to_centers() to convert between the two representations.

Values are stored as either float32 or float64; the dtype is fixed at construction and exposed via the dtype property. Most downstream operations (Spectrum.rebin, photometry.synthetic) require dtypes to match across all inputs.

dtype property

The numpy dtype of the underlying values.

Returns:

Type Description
dtype

Either numpy.dtype('float32') or numpy.dtype('float64').

kind property

Whether the values represent bin centers or bin edges.

Returns:

Type Description
str

Either "centers" or "edges".

spacing property

The spacing (midpoint) convention.

Returns:

Type Description
str

Either "linear" or "log".

values property

The underlying 1-D array of values.

Returns:

Type Description
ndarray

A new copy of the Grid's values. dtype matches the Grid's dtype.

from_array(values, *, rel_tol=1e-09, kind='centers') builtin

Construct a Grid from values and auto-detect the spacing convention.

If the values are strictly positive and uniform in log-space within rel_tol, the spacing is set to "log"; otherwise it falls back to "linear".

Parameters:

Name Type Description Default
values ndarray

1-D array of strictly increasing values. dtype must be float32 or float64.

 required
rel_tol float

Maximum allowed relative deviation of per-step spacing when deciding between log and linear. Default is 1e-9.

 1e-09
kind (centers, edges)

Whether the values are bin centers or bin edges. Default is "centers".

 "centers"

Returns:

Type Description
Grid

Raises:

Type Description
ValueError

If values has fewer than 2 entries, is not strictly increasing, or has an unsupported dtype.

is_uniform(rel_tol=1e-09) method descriptor

Test whether the values are uniform under the Grid's spacing convention.

For spacing="linear" this checks uniform per-step differences; for spacing="log" it checks uniform per-step differences in ln-space. Useful for selecting analytic fast paths in downstream code.

Parameters:

Name Type Description Default
rel_tol float

Maximum allowed relative deviation of per-step spacing from the mean step. Default is 1e-9.

 1e-09

Returns:

Type Description
bool

True if the values are uniform within rel_tol.

linspace(start, end, n, *, kind='centers', dtype=None) builtin

Construct a linearly spaced Grid on [start, end].

Parameters:

Name Type Description Default
start float

First value. Inclusive.

 required
end float

Last value. Inclusive.

 required
n int

Number of values. Must be at least 2.

 required
kind (centers, edges)

Whether the values are bin centers or bin edges. Default is "centers".

 "centers"
dtype numpy dtype

Either numpy.float32 or numpy.float64. Default is numpy.float64.

 None

Returns:

Type Description
Grid

A new Grid with spacing="linear".

Raises:

Type Description
ValueError

If n < 2 or dtype is neither float32 nor float64.

logspace(start, end, n, *, kind='centers', dtype=None) builtin

Construct a logarithmically spaced Grid on [start, end].

The endpoints are the actual axis values (not their logarithms); they must both be strictly positive.

Parameters:

Name Type Description Default
start float

First value. Inclusive. Must be > 0.

 required
end float

Last value. Inclusive. Must be > 0.

 required
n int

Number of values. Must be at least 2.

 required
kind (centers, edges)

Whether the values are bin centers or bin edges. Default is "centers".

 "centers"
dtype numpy dtype

Either numpy.float32 or numpy.float64. Default is numpy.float64.

 None

Returns:

Type Description
Grid

A new Grid with spacing="log".

Raises:

Type Description
ValueError

If n < 2, either endpoint is non-positive, or dtype is neither float32 nor float64.

to_centers() method descriptor

Return a new Grid expressed as bin centers.

If the Grid is already kind="centers", this returns a clone. If it is kind="edges", centers are computed via the spacing's midpoint convention (arithmetic mean for linear, geometric mean for log).

Returns:

Type Description
Grid

A new Grid with kind="centers" and the same spacing and dtype. Length is len(self) - 1 when converting from edges, otherwise unchanged.
Notes

to_edges followed by to_centers is an exact round-trip only when the original Grid is strictly uniform under its spacing convention. For irregular Grids the conversion is lossy.

to_edges() method descriptor

Return a new Grid expressed as bin edges.

If the Grid is already kind="edges", this returns a clone. If it is kind="centers", interior edges are computed via the spacing's midpoint convention (arithmetic mean for linear, geometric mean for log) and the two outer edges are extrapolated half a bin out from the first/last pair.

Returns:

Type Description
Grid

A new Grid with kind="edges" and the same spacing and dtype. Length is len(self) + 1 when converting from centers, otherwise unchanged.

Overlap

rebin(source_grid, source_values, target_grid) builtin

Flux-density-conserving rebin from a source grid onto a target grid.

For each target bin i, the output is out[i] = (sum_j overlap[i, j] * source_values[j]) / target_width[i], where overlap[i, j] is the linear-space intersection width between target bin i and source bin j and target_width[i] is the full linear-space width of target bin i. This preserves the integral sum_i out[i] * target_width[i] over the region of overlap, so the values behave like a density.

Target bins partially or fully outside the source range are NOT treated as errors: the sum is taken over whatever overlap exists. Use coverage to identify and mask such bins.

Parameters:

Name Type Description Default
source_grid Grid

Source wavelength axis.

 required
source_values ndarray

Per-bin source density. Length must equal the source bin count and dtype must match source_grid.

 required
target_grid Grid

Target wavelength axis. dtype must match source_grid.

 required

Returns:

Type Description
ndarray

Rebinned values, length equal to the target bin count. dtype matches the inputs.

Raises:

Type Description
ValueError

If dtypes mismatch across inputs, or if source_values length does not match the source bin count.

rebin_variance(source_grid, source_variance, target_grid) builtin

Variance propagation for rebin assuming independent source bins.

For each target bin i, the output is out[i] = sum_j (overlap[i, j] / target_width[i])^2 * source_variance[j]. As with rebin, partial-coverage target bins are not errors; their variance is computed against the partial sum and should usually be masked by the caller using coverage.

Parameters:

Name Type Description Default
source_grid Grid

Source wavelength axis.

 required
source_variance ndarray

Per-bin source variance (1-sigma squared). Length must equal the source bin count and dtype must match source_grid.

 required
target_grid Grid

Target wavelength axis. dtype must match source_grid.

 required

Returns:

Type Description
ndarray

Propagated variance per target bin. dtype matches the inputs.

Raises:

Type Description
ValueError

If dtypes mismatch across inputs, or if source_variance length does not match the source bin count.
Notes

Independence is an assumption, not a property of the operator: if the caller's source bins are correlated (for example because the spectrum was previously upsampled), the output underestimates the true variance.

coverage(source_grid, target_grid) builtin

Geometric coverage fraction of each target bin by the source range.

For each target bin i, out[i] = (sum_j overlap[i, j]) / target_width[i] lies in [0, 1]. A target bin completely inside the source range yields 1.0; one completely outside yields 0.0; a half-covered edge bin yields 0.5. This is the standard mask companion for rebin and rebin_variance.

Parameters:

Name Type Description Default
source_grid Grid

Source wavelength axis.

 required
target_grid Grid

Target wavelength axis. dtype must match source_grid.

 required

Returns:

Type Description
ndarray

Coverage fraction per target bin, in [0, 1]. dtype matches the inputs.

Raises:

Type Description
ValueError

If dtypes mismatch across inputs.