Method specification (slope_quality/v1)

This page specifies lunartrace.slope_quality/v1, the method implemented in src/lunartrace/science/slope_quality.py. Every rule below is taken from that module unless a different source is named. The method counts raster cells inside regions of interest (ROIs) that pass validity and inclusion tests at a set of thresholds, and it summarises the slope values of the included cells.

Scope of the result

The output is a count and distribution of valid raster cells under a declared rule set. It is not a surface area, an uncertainty propagation, or a scientific admission. See Limitations and FAQ and Glossary.

Notation and inputs

The method takes three inputs: a slope raster $S$ in degrees, a slope RMS raster $E$ in degrees, and an ROI shapefile $\{P_k\}_{k=0}^{K-1}$ with polygons in metres. Both rasters must share one north-up grid (see Grid and cell centres). Grids are compared exactly and never resampled (check_compatible).

Let the grid have $H$ rows and $W$ columns, so $N = HW$ cells. Cells are indexed by column $c \in \{0,\ldots,W-1\}$ and row $r \in \{0,\ldots,H-1\}$. Write $s_{c,r} = S[r,c]$ and $e_{c,r} = E[r,c]$.

Grid and cell centres

The grid transform is an affine map $(a, b, c_0, d, e, f)$ from pixel corner coordinates to projected metres. The method requires a north-up square grid, $b = d = 0$, $a > 0$ and $e = -a$ (check_compatible). With pixel size $a$ metres, the cell centre of column $c$ and row $r$ is

$$x_c = c_0 + a\left(c + \tfrac{1}{2}\right), \qquad y_r = f - a\left(r + \tfrac{1}{2}\right). \tag{1}$$

Here $f$ is the transform’s $f$ coefficient, so $c_0$ and $f$ are the upper-left corner of the grid. The inverse map used for ROI vertices is $\text{col} = (x - c_0)/a - \tfrac12$ and $\text{row} = (f - y)/a - \tfrac12$ (_check_lattice_polygon). Equation (1) is the same map read in the forward direction.

The production grid is $3200 \times 3200$ cells at $a = 5$ m with transform $(5, 0, -19000, 0, -5, -4000)$ (see Source data).

Validity predicates

Missing values are NaN after loading (load_grid). NaN fails every predicate below, so a missing value is never treated as zero.

Slope validity, for a sample $s$ in degrees:

$$V_S(s) = \mathbf{1}\!\left[\,\operatorname{isfinite}(s)\ \wedge\ 0 \le s \le 90\,\right]. \tag{2}$$

Both endpoints are valid (valid_slope).

Slope RMS validity, for a sample $e$ in the units of the slope RMS raster:

$$V_E(e) = \mathbf{1}\!\left[\,\operatorname{isfinite}(e)\ \wedge\ e > 0\,\right]. \tag{3}$$

Zero is invalid (valid_err).

Joint validity of a cell is

$$J(c,r) = V_S\!\left(s_{c,r}\right) \wedge V_E\!\left(e_{c,r}\right). \tag{4}$$

These predicates are applied cell by cell. The source note that no NaN cells were observed in the production slope rasters does not replace the check (see Source data).

Inclusion at threshold τ

For a finite threshold $\tau \ge 0$ the inclusion predicate is

$$I_\tau(c,r) = J(c,r) \wedge \mathbf{1}\!\left[\,e_{c,r} \le \tau\,\right]. \tag{5}$$

The comparison is inclusive and performed directly on the slope RMS values, with no unit conversion (inclusion_mask). Thresholds are validated by check_taus: the list must be non-empty, and every value must be finite and non-negative. Zero is accepted. The default thresholds are $\tau \in \{0.5,\ 2.0,\ 25.0\}$ (DEFAULT_TAUS).

ROI membership by cell centre

Each polygon $P_k$ is a single Polygon with no interior rings (load_rois). Membership of a cell is decided by its centre $(x_c, y_r)$ from equation (1). The closed rule is

$$M_k(c,r) = \mathbf{1}\!\left[\,(x_c, y_r) \in \overline{P_k}\,\right], \tag{6}$$

where $\overline{P_k}$ is the interior together with the boundary. This matters because ROI vertices lie on cell centres, so a strictly interior test would omit boundary cells (roi_mask docstring).

The method realises equation (6) with three steps, in the order used by roi_mask:

1. Lattice precondition. Every exterior vertex must lie exactly on a cell centre, with no floating-point tolerance, and every consecutive exterior vertex pair, including the closing edge, must differ by at most one cell in column and in row. Otherwise the polygon fails closed with MethodInputError (_check_lattice_polygon).
2. Linework validity. The polygon is passed through shapely.make_valid(..., method="linework") (_closed_region). This keeps pinch lobes as separate parts and keeps collapsed spurs as lines, so that every ring segment is preserved.
3. Buffered centre-inside test. The geometry is buffered by $\delta = 0.5$ m with mitre joins and rasterised with all_touched=False (roi_mask).

The buffer $\delta = 0.5$ m is fixed in metres. It is chosen so that a centre on the boundary falls inside the buffer, while a centre not on the boundary lies more than $\delta$ from it. Under the lattice precondition, any centre not on the boundary lies at least $5/\sqrt{2} \approx 3.54$ m from it on the 5 m grid (slope_quality module docstring). The margin is the reason the test equals “inside or on the boundary”.

Missing values do not affect membership. A cell with a NaN slope is still a member of $\overline{P_k}$ and is counted in roi_cells (slope_quality module docstring).

Multi-ROI union

The union row uses set union over the cells, not a sum over ROIs:

$$U(c,r) = \bigvee_{k} M_k(c,r). \tag{7}$$

A cell that lies in several ROIs is therefore counted once (roi_union). With no ROIs, $U$ is all false. The number of cells in the union is in general less than the sum of the per-ROI roi_cells.

Counts and the included fraction

For a membership mask $M$ (one ROI or $U$), the method forms these counts over the masked cells only:

$$\begin{aligned} n_{\text{roi}} &= \textstyle\sum M, & n_{S} &= \textstyle\sum M\,V_S(s), & n_{E} &= \textstyle\sum M\,V_E(e), \\ n_{J} &= \textstyle\sum M\,J, & n_{I} &= \textstyle\sum M\,I_\tau. && \end{aligned} \tag{8}$$

The included fraction is a valid-cell fraction:

$$f_\tau = \begin{cases} n_I / n_J, & n_J > 0,\\ \text{null}, & n_J = 0. \end{cases} \tag{9}$$

$f_\tau$ is undefined, not zero, when $n_J = 0$. It is exactly zero when $n_J > 0$ and no joint cell passes $\tau$ (_row). It counts grid cells and is not an area fraction. Polar stereographic cells are not equal-area, and no area correction is applied (see Limitations).

Slope statistics of included cells

Let $\{x_{(1)} \le \cdots \le x_{(n)}\}$ be the sorted included slope values, with $n = n_I$. For a probability $p \in \{0.05, 0.25, 0.5, 0.75, 0.95\}$ the inverted-CDF quantile (Hyndman and Fan type 1) is

$$Q(p) = x_{(\lceil np \rceil)}. \tag{10}$$

Each quantile is an observed sample value. The code calls numpy.quantile(..., method="inverted_cdf") (_row), which returns the smallest observed value whose empirical CDF is at least $p$. The quantile keys are str(p).

The mean is computed in float64:

$$\bar{x} = \frac{1}{n_I}\sum_{i=1}^{n_I} x_i. \tag{11}$$

The histogram has 45 bins of width 2 degrees with edges $E_j = 2j$ for $j = 0,\ldots,45$. The count in bin $j$ is

$$h_j = \#\left\{\,x_i : E_j \le x_i < E_{j+1}\,\right\}, \quad j = 0,\ldots,43, \qquad h_{44} = \#\left\{\,x_i : 88 \le x_i \le 90\,\right\}. \tag{12}$$

The final bin is closed, so it includes $90$ (HISTOGRAM_EDGES; np.histogram). Every included value is in $[0, 90]$, so no value falls outside the bins.

When $n_I = 0$, the quantiles and mean are null and the histogram is a list of 45 zeros. This is distinct from $n_J = 0$, which makes $f_\tau$ null (_row).

Algorithm

The following block gives the per-ROI and union procedure in the order that evaluate executes it.

Input : S (H x W), E (H x W), polygons P_0 .. P_{K-1}, taus T
Output: rows[(label, tau)] for label in {"0".."K-1", "union"} and tau in T

1  check_compatible(S, E)                      # same shape, transform, CRS; north-up square
2  T <- check_taus(T)                          # finite, >= 0, non-empty
3  for k in 0..K-1:
4      check lattice precondition on P_k        # fail closed
5      M_k <- rasterise(buffer(make_valid_linework(P_k), 0.5 m, mitre), all_touched=False)
6  U <- OR_k M_k                                # set union; all-false if K = 0
7  for (label, M) in [("0", M_0), ..., ("union", U)]:
8      for tau in T:
9          s <- S[M]; e <- E[M]                 # masked samples, NaN retained
10         vs <- finite(s) and 0 <= s <= 90
11         ve <- finite(e) and e > 0
12         j  <- vs and ve
13         inc <- j and (e <= tau)
14         v  <- s[inc]                         # included slopes only
15         rows.append(counts(M, vs, ve, j, inc),
16                     fraction = sum(inc)/sum(j) if sum(j) > 0 else null,
17                     quantiles = inverted_cdf(v, P) if sum(inc) > 0 else null,
18                     mean = mean(v) if sum(inc) > 0 else null,
19                     histogram = hist(v, edges 0..90 step 2) )
20 return rows

Complexity

Let $N = HW$, $K$ the number of ROIs, $T$ the number of thresholds, $M_{\text{roi}}$ the number of cells in a mask and $k$ the number of included cells.

• Rasterisation. Each ROI mask is produced over the grid, so mask construction is $O(KN)$ time. The primary path (GDAL) stores one boolean mask of $N$ bytes per ROI and one for the union. The lattice check is $O(V)$ in the number of exterior vertices.
• Per (ROI, $\tau$) statistics. The validity, joint and inclusion predicates are elementwise over the $M_{\text{roi}}$ masked cells, so each pair costs $O(M_{\text{roi}})$.
• Quantiles and histogram. Sorting the $k$ included values costs $O(k \log k)$ for each pair. The histogram costs $O(k)$.
• Total. $O(KN + (K+1)\,T\,\bar{M} + \sum k\log k)$ time, where $\bar M$ is the mean mask size. Memory is dominated by the two float64 grids and the boolean masks.

For the production grid, $N = 3200^2 = 10\,240\,000$ cells. One float64 grid occupies $8N = 81\,920\,000$ bytes, about 78.1 MiB. The two raster inputs together therefore occupy about 156 MiB as float64 arrays before masks are formed (load_grid returns float64 copies).

Worked example (SYNTHETIC)

Synthetic data

The grid, ROIs and values below are SYNTHETIC. They are invented for this page to show the rules. They are not Site01 data and carry no scientific meaning. The numbers were computed by hand from equations (1)–(12) and the rules above. tests/science/test_method_worked_example.py runs the same synthetic inputs through evaluate and asserts every number on this page, so the page and the code cannot drift apart unnoticed.

Grid. A $3 \times 3$ grid with 5 m pixels and origin $(c_0, f) = (0, 0)$, so the transform is $(5, 0, 0, 0, -5, 0)$. Cell $(c, r)$ has centre $(5(c+\tfrac12),\ -5(r+\tfrac12))$. Columns run left to right and rows top to bottom.

Slope $s$ (degrees):

row r \ col c	0	1	2
0	10	20	NaN
1	30	95	40
2	50	60	70

Slope RMS $e$ (degrees):

row r \ col c	0	1	2
0	0.5	2.0	1.0
1	0.0	3.0	25.0
2	0.4	NaN	30.0

ROIs. Vertices are given as cell-centre indices $(c, r)$.

• $P_0$: $(0,0), (1,0), (2,0), (2,1), (1,1), (1,2), (0,2), (0,1), (0,0)$. This is an L-shape with every edge a one-cell step. By the closed rule it contains the 8 cells $(0,0), (1,0), (2,0), (0,1), (1,1), (2,1), (0,2), (1,2)$. The corner $(2,2)$ is outside.
• $P_1$: $(1,1), (2,1), (2,2), (1,2), (1,1)$. It contains $(1,1), (2,1), (2,2), (1,2)$.

The two ROIs share three cells, $(1,1), (2,1), (1,2)$, so the union has $8 + 4 - 3 = 9$ cells.

ROI 0 counts (equations 2–5, 8).

• $n_{\text{roi}} = 8$.
• Slope valid ($V_S$): $(0,0), (1,0), (0,1), (2,1), (0,2), (1,2)$, so $n_S = 6$. Cells $(2,0)$ (NaN) and $(1,1)$ ($95 > 90$) fail.
• RMS valid ($V_E$): $(0,0), (1,0), (2,0), (1,1), (2,1), (0,2)$, so $n_E = 6$. Cells $(0,1)$ ($0$, not $> 0$) and $(1,2)$ (NaN) fail.
• Joint ($J$): $(0,0), (1,0), (2,1), (0,2)$, so $n_J = 4$.

$\tau$	included cells	$n_I/n_J$	$Q(0.05)$	$Q(0.25)$	$Q(0.5)$	$Q(0.75)$	$Q(0.95)$	mean	non-zero histogram bins
0.5	$\{(0,0), (0,2)\}$	2/4 = 0.5	10	10	10	50	50	30	bin 5: 1; bin 25: 1
2.0	$\{(0,0), (1,0), (0,2)\}$	3/4 = 0.75	10	10	20	50	50	80/3 ≈ 26.67	bin 5: 1; bin 10: 1; bin 25: 1
25.0	$\{(0,0), (1,0), (2,1), (0,2)\}$	4/4 = 1.0	10	10	20	40	50	30	bin 5: 1; bin 10: 1; bin 20: 1; bin 25: 1

The bin index is $\lfloor s/2 \rfloor$, so slope 10 is in bin 5, 20 in bin 10, 40 in bin 20 and 50 in bin 25. Quantiles follow equation (10). For example, at $\tau = 2.0$ the sorted values are $10, 20, 50$ with $n = 3$. Then $\lceil 3 \cdot 0.5\rceil = 2$, so $Q(0.5) = 20$, and $\lceil 3 \cdot 0.75\rceil = 3$, so $Q(0.75) = 50$.

The boundary inclusion is visible at $\tau = 2.0$ and $\tau = 25.0$. Cell $(1,0)$ has $e = 2.0$, which is included at $\tau = 2.0$ because the comparison is $\le$. Cell $(2,1)$ has $e = 25.0$, which is included at $\tau = 25.0$.

ROI 1 counts. $n_{\text{roi}} = 4$, $n_S = 3$, $n_E = 3$, $n_J = 2$ (cells $(2,1)$ and $(2,2)$).

• $\tau = 0.5$ and $\tau = 2.0$: no joint cell has $e \le \tau$. So $n_I = 0$, $f_\tau = 0/2 = 0.0$ (not null, because $n_J > 0$), and the quantiles, mean and histogram are null, null and all zero.
• $\tau = 25.0$: $(2,1)$ with $e = 25 \le 25$ is included, and $(2,2)$ with $e = 30$ is not. So $n_I = 1$, $f = 1/2 = 0.5$, all five quantiles equal 40, the mean is 40, and bin 20 has count 1.

Union (equation 7). $n_{\text{roi}} = 9$. The union joint set is $\{(0,0), (1,0), (2,1), (0,2), (2,2)\}$, so $n_J = 5$, and $n_S = n_E = 7$. The union includes $(2,2)$ in $J$ but never in $I$, because its $e = 30$ exceeds 25.

$\tau$	$n_I$	$f_\tau$	statistics
0.5	2	2/5 = 0.4	same as ROI 0 at $\tau = 0.5$
2.0	3	3/5 = 0.6	same as ROI 0 at $\tau = 2.0$
25.0	4	4/5 = 0.8	same as ROI 0 at $\tau = 25.0$

The union has $n_{\text{roi}} = 9$ rather than $8 + 4 = 12$. The three shared cells are counted once, which is the set-union rule of equation (7).

Output

evaluate returns one row per (ROI, $\tau$) pair, grouped by ROI in shapefile order and then by threshold, followed by the union rows. Each row has the fields roi, tau, roi_cells, valid_slope_cells, valid_err_cells, joint_cells, included_cells, included_fraction, slope_quantiles, slope_mean and slope_histogram (Row). Its canonical JSON form has sorted keys, compact separators, allow_nan=False and a trailing LF (canonical_json). The same inputs and thresholds therefore give the same bytes.

What this does not establish

• Not an area. $f_\tau$ is a valid-cell fraction. It does not measure surface area, and polar stereographic cells are not equal-area on the sphere.
• Not an uncertainty interval. $\tau$ is a data-quality cutoff on the slope RMS raster. It is not a confidence level, an error bar, or a propagated uncertainty.
• Not a statement about the whole site or the Moon. Statistics describe the cells that pass the rules within the ROIs of one source witness. They do not generalise beyond it.
• Not a scientific admission. The standing of the Site01 numeric result is NUMERIC_REPRODUCED. This records agreement between two implementations and is not admission (see Glossary).
• Not valid for other geometry. The closed rule applies only to lattice-centred rings with one-cell steps. Other polygons fail closed rather than being rasterised approximately.

Related pages

• Verification: oracle, hash gating and byte-identical replay.
• Source data: the frozen PGDA product and its grid.
• Limitations and FAQ: interpretation limits.
• Glossary: definitions of terms used here.