A cell can contain zero and still be a real observation
A rainfall grid contains several zeros. Some mean that the instrument recorded no rain; others fill places where no observation was available. The numbers look identical, but using them in an average answers two different questions. A validity mask carries the missing distinction: whether the stored value may participate in a particular calculation.
This guide starts with a small grid and follows that distinction through multiband calculations, mosaics, resampling and summary statistics. It is about preserving the evidence behind a raster, not choosing the most attractive transparent background. You will learn to separate a measured zero, an invalid cell, a quality rejection and a location outside the intended study area.
The examples use imaginary observations and deliberately small arrays. They are not rainfall, vegetation or hazard findings about Singapore or any other real place. The arithmetic is transferable; the acceptance rules are not universal. For an actual product, read its band definitions, quality documentation and the behaviour of the software version that processes it.
Geoinformatics subject guide · Learning that transfers into life · How X Works hub
Choose your reading route
Route 1: Understand the two layers · Chapters 1–3
Route 2: Calculate without losing zeros · Chapters 4–5
Route 3: Combine bands and scenes · Chapters 6–8
Route 4: Check summaries and exports · Chapters 9–10
Route 5: Transfer the reasoning · Chapters 11–12
Full chapter index · Independent worked case · Questions and practical checks
Chapter index
Understand the two layers · Chapters 1–3
Give every cell a value and an eligibility statement
Distinguish a missing value from a reserved numerical code
Read mask polarity before applying Boolean logic
Calculate without losing zeros · Chapters 4–5
Calculate the mean with the correct denominator
Separate validity, quality and confidence
Combine bands and scenes · Chapters 6–8
Use the intersection of bands required by the formula
Keep coverage stable when comparing dates
Treat mosaics and resampling as explicit transformations
Check summaries and exports · Chapters 9–10
Report observed support before making a regional claim
Verify the saved file rather than only the preview
Transfer the reasoning · Chapters 11–12
Transfer the test to a different measurement
Make a compact evidence record that a reader can check
CHAPTER 1 OF 12
1. Give every cell a value and an eligibility statement
Imagine four equal-area squares on paper. Write 0, 4, 8 and 99 in them. Beneath the values, write valid, valid, valid and invalid. The 99 is merely a placeholder in this exercise. Its size says nothing about the environment because the eligibility statement excludes it from interpretation. The first square, however, contains a valid zero and must remain in the evidence.
A raster stores measurements or categories on a grid. A mask is a corresponding grid that marks which entries are usable under a stated convention. The value and its mask form a pair. Looking only at the value array can lose information, even when every cell contains a perfectly readable number. Conversely, possessing a mask does not explain the reason for each rejection unless a quality record carries that meaning.
Begin an audit by asking what the values represent and what the mask represents. A footprint mask may identify where the sensor observed. A scientific quality mask may reject cloud, saturation or another condition. A user-created study-area mask limits the analysis geographically. These can be combined, but they should not be described as the same observation.
A useful learner check is to cover the values and explain the mask first. Then cover the mask and explain why the numbers alone cannot recover it. This is the first-principles relationship: eligibility is information in its own right, not a cosmetic property of the picture.
CHAPTER 2 OF 12
2. Distinguish a missing value from a reserved numerical code
One storage strategy reserves a number as the NoData marker. For example, a temperature product might reserve −9999 while storing ordinary temperatures separately. This works only if the reserved number cannot also be a legitimate observation in that representation. The file metadata must declare its meaning, and the receiving software must preserve that declaration.
A separate mask avoids having to sacrifice a legitimate number. Consider an eight-bit band that can represent integers from 0 to 255. If all of those numbers have valid meanings, there is no spare code left for missingness. Assigning zero to missingness would make real zeros indistinguishable from absent observations unless an additional validity channel remains available.
Do not repair a file by simply declaring every zero invalid. That is a decision about evidence, not a harmless metadata edit. In our rainfall example it would erase dry observations and raise the average over the remaining wet cells. In a class-coded map it could erase a legitimate class whose code happens to be zero.
Before changing a marker, inspect the documented range, scaling and existing masks. Preserve the original file and record why any reinterpretation is justified. A value that looks implausible may be a fill code, a genuine extreme, a decoding error or a different unit. Those explanations require different repairs.
CHAPTER 3 OF 12
3. Read mask polarity before applying Boolean logic
GDAL valid-data masks use zero for invalid cells and nonzero values for valid cells, commonly 255. This is not the convention of every programming interface. A NumPy masked-array mask uses True to indicate an invalid entry. Rasterio documents both conventions because confusing them can invert the intended selection while leaving the program syntactically correct.
Our four-square mask could therefore be written as GDAL-style values 255, 255, 255, 0, or as invalidity flags False, False, False, True. The arrays mean the same thing under their respective definitions. Copying one into the other without conversion would reverse the eligibility of every square.
Name a variable by its meaning: valid_cells or invalid_cells is clearer than mask2. When converting, check one known valid cell and one known invalid cell. A conversion should preserve their interpretation, not necessarily their numerical values. Checking that the arrays have the same shape is necessary but will not detect reversed polarity.
A good tiny test has at least three cases: a valid zero, a valid nonzero value and an invalid placeholder. If your display or summary handles only the middle case correctly, the successful result is not evidence of a sound pipeline. Small adversarial examples expose a misunderstanding more clearly than a large map with a plausible colour ramp.
CHAPTER 4 OF 12
4. Calculate the mean with the correct denominator
Return to the values 0, 4, 8 and invalid. The observed total is 0 + 4 + 8 = 12. Three eligible cells contribute, so the valid-cell mean is 12 ÷ 3 = 4. Keeping the valid zero matters: it contributes nothing to the numerator but contributes one observation to the denominator.
If the invalid square is silently replaced by zero, the mean becomes 12 ÷ 4 = 3. That is not an improved estimate of the same quantity. It is a different calculation that treats missingness as a known zero. If instead all numerical zeros are discarded, the mean becomes 12 ÷ 2 = 6. Both mistakes can produce believable results.
State the target of the mean. Four is the mean among the three observed equal-area cells, not necessarily the mean of the entire four-cell region. To estimate the regional mean, you need an assumption or additional information about the unobserved square. A correct mask prevents one false inference; it does not automatically solve the statistical problem created by missing observations.
Report coverage beside the statistic: three of four cells, or 75% of this equal-area region, were eligible. In an actual geographic grid, cells may differ in physical area. Then a count fraction is not automatically an area fraction. Use a suitable area calculation and preserve the distinction between the sampled support and the intended region.
CHAPTER 5 OF 12
5. Separate validity, quality and confidence
A cell can be technically present yet unsuitable for a scientific question. An image reader may mark a pixel valid because bytes exist, while a quality band identifies cloud contamination. A temperature can be present but outside an instrument’s calibrated range. Eligibility for a calculation should reflect the task, not merely successful decoding.
For an original example, suppose six cells are readable. Four pass a quality rule and two do not. The storage-valid fraction is 6/6, but the task-eligible fraction is 4/6. Calling the dataset fully observed for this analysis would hide the rejection. Conversely, calling the rejected values nonexistent would obscure the fact that measurements were acquired but excluded for a reason.
Confidence is another distinction. A valid observation can have substantial uncertainty. A binary mask cannot express a complete probability distribution or calibration error. Keep an uncertainty band or accompanying assessment when the product supplies it. Do not convert an uncertainty estimate into a hard rejection threshold without explaining the intended decision and its consequences.
For teaching, ask three separate questions: was something recorded, may it be used here, and how uncertain is the usable value? These questions lead to different evidence. A green checkmark cannot stand in for all three, and a beautiful image cannot establish any of them on its own.
CHAPTER 6 OF 12
6. Use the intersection of bands required by the formula
A multiband formula needs the inputs it actually uses. Suppose band A is valid at cells 1, 2 and 3, while band B is valid at cells 2, 3 and 4. A calculation requiring both bands is eligible only at cells 2 and 3. Taking the union would incorrectly allow cells where one necessary input is missing.
Write eligibility as a sentence before writing a logical expression: use this cell if A is valid AND B is valid AND the denominator is allowed. The third condition matters for ratios. Both measured inputs can be present while their sum is zero, leaving a particular ratio undefined. Data validity and mathematical domain validity are connected but distinct checks.
Different formulas can legitimately have different masks. An A-only summary uses three cells in this example; an A-and-B comparison uses two. If the reported means differ, investigate whether values changed or whether the eligible support changed. Comparing statistics over different supports without noticing can create a false story about environmental change.
Dataset-wide display masks may not equal the band intersection required by your formula. Read the interface’s documented precedence and semantics. Do not assume a colourful RGB preview establishes that every scientific band is usable at every location. The appropriate rule follows the computation’s dependencies, not the number of channels visible on the screen.
CHAPTER 7 OF 12
7. Keep coverage stable when comparing dates
Consider four places observed on two dates. On the first date, all four are valid; on the second, only the two naturally warmer places are visible. The mean of the available observations can rise even if no place warmed. This is a change in which places contribute, not necessarily a change in the measured process.
A paired comparison can use the intersection of valid locations across dates. That answers what changed at places observed on both occasions. It does not answer what happened everywhere, and it may exclude a systematic part of the region. State this narrower target rather than presenting common-support analysis as a universal cure for missingness.
An original numerical check makes the distinction visible. Day one has values 2, 4, 8 and 10; day two has the same values, but only 8 and 10 are valid. The available-cell mean rises from 6 to 9. The paired changes at the two common cells are both zero. Neither calculation is arithmetically wrong; the misleading step is treating their targets as identical.
Publish the eligible area or count for each date and for the overlap. If you fill gaps, distinguish observed from estimated cells and evaluate the filling method independently. Retaining a provenance flag lets a later reader ask whether a trend depends on observations, imputation or a changing mixture of both.
CHAPTER 8 OF 12
8. Treat mosaics and resampling as explicit transformations
When two scenes overlap, a mosaic needs a rule for which valid value wins. It might use acquisition priority, quality ranking or a specified blend. A missing placeholder should not overwrite a valid observation merely because its file is processed last. But software behaviour depends on its nodata, alpha and mask settings, so test the actual operation.
Resampling adds another issue: a target cell can depend on several source cells. The handling of invalid contributors differs by method and implementation. GDAL’s reprojection documentation describes kernel-specific rules. A simple hand average is useful for understanding eligibility, but it must not be advertised as a complete description of every bilinear or cubic warp.
Build a tiny source image with a conspicuous invalid region and known valid neighbours. Reproject it using the intended settings, then inspect both output values and output mask. Does a missing edge grow, shrink or acquire interpolated values? Compare the result with the method’s documented behaviour instead of deciding correctness from smooth appearance.
For categorical rasters, preserve the separate question of whether the resampling method respects category meaning. A correct mask cannot make arithmetic averaging of class identifiers meaningful. The connected land-cover resampling guide explains that problem. Here the task is to ensure that the chosen method receives the intended eligible inputs and describes its output support honestly.
CHAPTER 9 OF 12
9. Report observed support before making a regional claim
Suppose a study region covers ten equal squares and only eight are eligible. Their values sum to 40, giving an observed-cell mean of 5. Without information about the remaining squares, the full-region total and mean are not identified. The mask tells you where evidence is absent; it does not tell you what those values would have been.
If the two missing values are known from a defensible domain restriction to lie between 0 and 10, a conditional bound is possible. The full total lies between 40 and 60, and the ten-cell mean between 4 and 6. Those bounds rely on the stated range, not on the file format. If that range is unjustified, the apparent precision of the interval is unjustified too.
A second common mistake is dividing a valid total by the entire region while describing the result as an observed mean. That may be appropriate for a deliberately defined density only under explicit treatment of the unobserved area. It is not a neutral default. Name both numerator and denominator in the caption.
For unequal-area cells, use weights representing the intended geographic support. A valid-cell count, valid surface area and valid population coverage can differ substantially. The right coverage statistic depends on the question. Keep enough information for another analyst to reconstruct the denominator rather than reporting only a rounded percentage.
CHAPTER 10 OF 12
10. Verify the saved file rather than only the preview
Masks can be stored internally or in associated files, depending on format and options. A transfer that moves the main image but leaves an external mask behind can change how the receiver interprets the same numbers. A successful file open is therefore weaker evidence than a round-trip comparison of values, masks and metadata.
Use an authorised test copy. Record dimensions, band count, coordinate reference, transform, datatype, scaling, nodata declarations, mask conventions and counts of valid zeros. Export, close the writer, reopen with the intended receiving tool and repeat the checks. Include cells near the footprint edge and cells where bands have different validity.
The comparison should be semantic. One program may expose a validity mask as 255/0 and another as an inverted Boolean mask; these can agree despite different bytes. Conversely, identical numeric values with a lost mask can disagree scientifically. State the interpretation you are testing before choosing a byte or value comparison.
Do not assume transparency equals missingness in every workflow. An alpha channel can support display blending, while scientific acceptance may use different quality rules. Check what the consumer actually uses. An output that appears correct on a white background can still contain invalid values participating in downstream statistics.
CHAPTER 11 OF 12
11. Transfer the test to a different measurement
Replace rainfall with night-time light intensity. Zero can now represent a genuinely dark observation, while missingness might indicate no usable acquisition. The arithmetic lesson survives, but the physical reasons for low values and rejection change. Explain those reasons from the new product rather than importing the rainfall story word for word.
Next replace the continuous measurement with a land-use category. A valid class code of zero still belongs in the legend, but taking its mean with codes one and two is generally not a meaningful environmental measurement. Validity answers whether the label is usable; the measurement scale determines which operations are sensible.
Finally imagine a derived flood indicator requiring elevation, rainfall and a drainage input. Its eligibility depends on all required layers and the model’s domain. A missing drainage record should not automatically become perfect drainage, zero drainage or no risk. Each substitution imposes a different assumption with potential consequences for the result.
The transfer check is to identify what remains invariant: value and eligibility stay paired, conventions are explicit, dependencies determine the combined mask, and coverage accompanies conclusions. Then name what changes: measurement meaning, quality criteria, permitted arithmetic and the evidence required for extrapolation beyond observed cells.
CHAPTER 12 OF 12
12. Make a compact evidence record that a reader can check
A useful result statement might read: the mean among 75 eligible equal-area cells was 4.2 units; 25 cells were excluded under the documented cloud and footprint rule; no missing values were replaced by zero. This is more informative than saying the raster average was 4.2. It identifies the target and the absent support.
For reproducibility, retain source versions, mask definitions, quality criteria, software versions and processing settings. For a multiband result, list required bands and the logical combination used. For a comparison across dates, record whether each statistic used all available observations or a shared eligible footprint.
Separate failures by cause. A reversed Boolean mask needs a convention repair. Lost sidecar files need a transfer repair. Wrong band intersections need a dependency repair. Biased coverage needs a sampling or inference response. Applying the same fix to all four can conceal the actual weakness rather than restoring the evidence.
The practical endpoint is not a file with no blank areas. It is a result whose observed, rejected and estimated parts remain distinguishable. You should be able to point to a zero and explain why it belongs, point to a blank and explain why it does not, and say which conclusions would change if the missing observations became available.
Independent worked case and evidence checks
Try this independent six-cell exercise before checking the arithmetic. All cells have equal area. Band A contains 0, 2, 4, 6, 8 and 10. Its valid cells are 1–5. Band B contains 1, 3, 5, 7, 9 and 11. Its valid cells are 2–6. The placeholder values in invalid positions are deliberately readable; their presence does not make them eligible.
First calculate A’s own observed mean: (0 + 2 + 4 + 6 + 8) ÷ 5 = 4. B’s own observed mean is (3 + 5 + 7 + 9 + 11) ÷ 5 = 7. Subtracting these two means gives 3, but it compares different sets of cells. That difference cannot be interpreted as the mean paired difference at common observed locations.
The common eligible set is cells 2, 3, 4 and 5. Their B − A differences are 1, 1, 1 and 1. The paired mean difference is therefore 1. A’s mean on that common support is 5 and B’s is 6. The apparent discrepancy between 3 and 1 is explained by the support change, not a rounding error.
Now suppose the task uses A divided by B at common cells. The four ratios are 2/3, 4/5, 6/7 and 8/9. Each is defined because the eligible B values are nonzero. Their mean is approximately 0.8032. Dividing the common-support totals gives 20/24 ≈ 0.8333, a different aggregation. Correct masks are necessary but do not make these two estimands identical.
For a changed-context check, make cell 2’s B value a valid zero. The paired difference remains mathematically defined there, but A/B does not. The ratio needs an additional domain exclusion, leaving cells 3–5. Describe this as a formula-specific exclusion rather than pretending the original B observation was missing.
A final reviewer should ask for the mask polarity, source validity rule, common-support list and denominator of each statistic. If only the final numbers survive, the two competing explanations are difficult to separate. If those small pieces of evidence survive, another learner can reproduce the result with a pencil.
For one last storage check, encode the original common support as 0,255,255,255,255,0 in a valid-data mask. Its equivalent invalidity flags are True,False,False,False,False,True. Both select four cells. Count the selected cells after any conversion and inspect cells 1 and 2 individually. An accidentally inverted conversion selects two cells instead, including precisely the positions where one required band is absent. This test needs no large satellite image: six known cells establish whether the convention has survived.
Worked comparison
| Operation | Eligible support | What the result does not establish |
|---|---|---|
| A-only mean | Cells where A is valid | The mean of unobserved locations |
| A minus B | Cells where both are valid | A comparison over different footprints |
| A divided by B | Both valid, with allowed denominator | That valid inputs guarantee a defined ratio |
| Two-date change | A stated common or modelled support | A region-wide trend without coverage evidence |
| Export and reopen | Equivalent value-mask interpretation | That the same picture means the same data |
Questions and practical checks
Is zero always NoData?
No. A zero can be a valid observation or category. Read the product’s declaration and mask; do not infer missingness from magnitude alone.
Why does my Boolean mask seem reversed?
Different interfaces use different polarity. GDAL-style nonzero means valid; a NumPy masked-array True flag marks invalidity. Test known cells when converting.
Should I combine band masks with AND or OR?
A formula requiring every band normally needs their valid-cell intersection. Other tasks may use different rules; state the dependency explicitly.
Can a valid-cell mean describe the whole region?
Only with appropriate assumptions or additional evidence about missing support. Report coverage and avoid silently treating missing values as zero.
What should I inspect after exporting?
Reopen the saved file and compare values, masks, valid zeros, bands, spatial alignment and metadata using the intended receiving software.
Continue with the connected subjects
Build the geographic foundations
Raster algebra: what cell-by-cell calculations mean
Categorical resampling: why class identifiers are not continuous measurements
Check aggregation and support
Subzone means: limits imposed by coarse spatial support
Local rates versus pooled totals: choosing the denominator
Sources and scope
GDAL RFC 15: valid-data masks and mask flags
Rasterio: mask polarity, band masks and dataset-mask behaviour
GDAL: resampling-specific source-validity handling
GDAL GeoTIFF driver: internal and external mask storage
The numerical cases in this guide are original fictional teaching examples, not measurements from a real site. This is an educational explanation, not a field safety instruction, engineering approval or an official certification. For a real project, use qualified practitioners, current product documentation and site-specific evidence. Sources were checked on 30 October 2026.
Continue the representation checks
A raster mask governs which observations enter a calculation; tile identity governs which representations count as one object; a spatial join governs which relationships enter a total; and an index governs which candidates reach an exact test. Use the companion guide when your question crosses one of those boundaries.
Vector-Tile Feature Counts, Clipped Fragments and Source Identity
Spatial-Join Multiplicity, Boundary Matches and Allocation Totals
GeoPackage RTree Indexes, Stale Bounds and Spatial Query Completeness