Module Ymir.Observation

Measured samples on a grid.

An observation is data of shape batch @ Grid.shape g on a grid g, with optional variance, validity and area.

Validity. valid is true where a sample was measured. Data and variance under an invalid sample are replaced by 0 wherever one arises, so a NaN or a sentinel there reaches no result under any derivative. Validity only narrows: Observation.restrict conjoins, and only Observation.v sets a mask anew. Windows always have a mask, false beyond the data. Masks carry no gradient.

Area. A pipeline that defined its surface brightness against a nominal area, such as JWST's PIXAR_SR, or a per-pixel area map, states it as area. The grid's Grid.measure stays each cell's own.

The unit rule. Data whose unit has Grid.cell⁻¹ are values per cell, and a cell counts as one cell. Every other unit is a field over the cells, and a cell counts by the observation's area where it has one, its measure otherwise.

#type ('w, 'e, 'd) t

The type for observations on a grid whose world is 'w, at dtype 'e.

val v : 
  ?variance:(float, 'e, 'd) Nx.t Quantity.t ->
  ?valid:'d Nx.bit_t ->
  ?area:(float, 'e, 'd) Nx.t Quantity.t ->
  ('w, 'e, 'd) Grid.t ->
  (float, 'e, 'd) Nx.t Quantity.t ->
  ('w, 'e, 'd) t

v ?variance ?valid ?area g data is data, batch @ Grid.shape g, on g. variance is in the data's unit squared. valid is true where a sample was measured. area is the measure each cell's data are per, when it is not the cell's own: one value per cell, its last axes g's shape, or one for all cells.

Raises Invalid_argument if data does not end with g's shape, the variance's unit is not the data's squared, or area is not a measure of g's cells or has another shape.

#val grid : ('w, 'e, 'd) t -> ('w, 'e, 'd) Grid.t

grid o is o's grid.

#val data : ('w, 'e, 'd) t -> (float, 'e, 'd) Nx.t Quantity.t

data o is o's data, 0 where invalid.

#val variance : ('w, 'e, 'd) t -> (float, 'e, 'd) Nx.t Quantity.t option

variance o is o's variance, 0 where invalid.

#val valid : ('w, 'e, 'd) t -> 'd Nx.bit_t option

valid o is where o's samples were measured, if known.

#val area : ('w, 'e, 'd) t -> (float, 'e, 'd) Nx.t Quantity.t option

area o is the measure o's data are per, when not the cells' own.

#val restrict : 'd Nx.bit_t -> ('w, 'e, 'd) t -> ('w, 'e, 'd) t

restrict m o keeps a sample valid where it was valid and m holds.

#val map_world : ('w, 'v, 'd) Transform.t -> ('w, 'e, 'd) t -> ('v, 'e, 'd) t

map_world t o is o on Grid.map_world t (grid o): its data, variance, validity and area are o's.

Arithmetic

Sums, differences and scalings, whose variances combine exactly for independent samples. Products, ratios and other functions of data are the program's, on data, with variances from Rune.jvp.

#val add : ('w, 'e, 'd) t -> ('w, 'e, 'd) t -> ('w, 'e, 'd) t

add a b is a's data plus b's, in a's unit, on a's grid. The variance is the sum of both when both have one; a sample is valid where it is valid in both.

Raises Invalid_argument if the grids do not agree (Grid.agree) or the areas differ, naming the first difference, as in "Observation.add: the grids do not agree at transform.3.matrix: element (0, 1) is -8.6e-06 in the first and -8.7e-06 in the second"; numbers that differ raise through Nx.check. Raises if b's unit does not convert to a's.

#val sub : ('w, 'e, 'd) t -> ('w, 'e, 'd) t -> ('w, 'e, 'd) t

sub a b is a's data less b's, as add combines them.

#val scale : (float, 'e, 'd) Nx.t Quantity.t -> ('w, 'e, 'd) t -> ('w, 'e, 'd) t

scale k o is o's data times k, in their units' product, with the variance times k².

val window : 
  start:'d Nx.int64_t ->
  shape:int array ->
  ('w, 'e, 'd) t ->
  ('w, 'e, 'd) t

window ~start ~shape o is o on Grid.window ~start ~shape (grid o): data, variance, validity and a per-cell area sliced with the grid, invalid beyond o's cells.

#val around : 'w -> shape:int array -> ('w, 'e, 'd) t -> ('w, 'e, 'd) t

around x ~shape o is o on Grid.around x ~shape (grid o), sliced as window slices.

#type ('e, 'd) integral = {

#value : (float, 'e, 'd) Nx.t Quantity.t;
(*
Σ data × w × a over valid cells, a a cell's area for a field and one cell for values per cell.
*)
#variance : (float, 'e, 'd) Nx.t Quantity.t option;
(*
Σ variance × w² × a², the variance of value for independent samples, when the observation has a variance.
*)
#area : (float, 'e, 'd) Nx.t Quantity.t;
(*
Σ w × a over valid cells: value / area is the mean.
*)
#coverage : (float, 'e, 'd) Nx.t;
(*
The valid cells' overlap with the region as a share of the region's own area, both in the region's plane: below 1 where the region reaches beyond the image's edge or over invalid samples, through a window or the whole image alike, and 0 for a region of zero size.
*)

}

The type for integrals of an observation over a region, each of the region's and window's batch axes broadcast.

#val integrate : ('w, 'e, 'd) Region.t -> ('w, 'e, 'd) t -> ('e, 'd) integral

integrate r o weighs o's cells with Region.weights and sums each term once in double-word arithmetic at 'e, with w the weight.

Raises Invalid_argument through Nx.check where a cell of the window's border is inside the base, the base continues beyond it, and the region is not exactly outside it: the window clipped the region, as in "Observation.integrate: the region reaches the border of its 104x104 window at sample (0, 51); take a larger ~shape". Raises as Region.weights does.

#val ptree : unit -> (('w, 'e, 'd) t, 'd) Nx.Ptree.t

ptree () is the structure of observations: the grid, then the data, variance, validity and area, each present or not.