Using the HydroApp

What the application computes

The hydroperiod of a pixel is the number of days it held surface water during one hydrological year. It is a different question from the one a satellite image answers. An image says whether there was water on the day the satellite passed; the hydroperiod says how long the water stayed, which is the quantity that governs what can live in a wetland.

It is built by classifying every usable observation in the year as water or not water — using a water index and a threshold — and counting.

Why the year starts in September

A calendar year cuts a flooding cycle in half. The application therefore works in hydrological years running from 1 September to 1 September, and a cycle written 2021/2022 begins on 1 September 2021.

One consequence catches everyone once: the most recent cycle you can compute is not last year's. Between January and August, the cycle that began last September is still open and its flooded days do not yet add up to a year. The application knows this and opens on the last cycle that has actually closed.

What it needs from you

A connected Earth Engine account, which the first manual covers. Everything below assumes the badge at the top of the page is green.

Study areas

The home page lists the study areas. A study area is a group of wetlands together with the outline the map frames itself on and refuses to pan outside — for this project, the Danube basin.

1 2 3

Each area holds two registries of sites, which behave identically once you are working: the Ramsar wetlands of the basin, and the eLTER sites that intersect it. They are drawn differently on the map and offered under different headings, but anything the application does with one it does with the other.

The workspace

Opening a study area gives you the working surface: the control panel on the left, the map on the right, and a log along the bottom of the panel. On a narrower screen the two stack, panel first.

1 2 3 4 5 6 7

The panel is one form serving five tabs. The block at the top — the area, and the time series settings under it — is shared: it feeds every tab that needs it. The tabs below choose which product is built from it.

Nothing is remembered between requests. Each time you add a layer the application rebuilds the whole computation from what the panel currently says. This is why changing a setting and pressing the button again is always safe, and why there is no notion of a session to lose.

Choosing the area

Everything computes over one area, chosen in two steps: first where it comes from, then which one.

1 2

Picking a wetland or an eLTER site also frames the map on it. Only one of the two dropdowns is ever active, so the application is never sent two answers to the same question.

Drawing an area

The third source is a shape of your own. Choose Draw on the map and use the polygon or rectangle tool at the left edge of the map.

1 2 3

A drawn shape overrides whatever the dropdowns hold. Drawing is the more deliberate act of the two — a wetland may simply be left over in the dropdown from an earlier run — so the application prefers it. Delete the drawing with the same tools and the choice returns to the dropdown.

Drawings are meant to be drawn: the application refuses a shape with more than 5,000 vertices, which no hand-drawn polygon approaches and no imported coastline stays below.

The time series

These six settings define the series that the hydroperiod and the anomalies are computed from. The terrain wetness index ignores them entirely.

1 2 3 4 5

Sensor

A trade between detail and depth of record. Changing it rewrites what the other fields accept, so choose it first.

Period

Start and end year, in hydrological years. Asking for a year the sensor does not reach is refused with a message saying so rather than quietly returning less.

Water index and threshold

The index turns reflectance into a single number that is high over water. MNDWI is the sensible default and works on all three sensors. AWEI and its shadow-suppressing variant help where terrain shadow is being confused with water; WI2015 is a tuned alternative. MODIS offers only MNDWI and NDWI.

None of them is this project's invention. Each is a published index, and the paper is worth reading before trusting one over another on ground you do not know:

The thresholds these papers propose were tuned on the landscapes each was written about. Zero is a reasonable place to start, not a value any of them guarantees for the Danube.

The threshold is the value above which a pixel counts as water. Zero is the usual starting point: raise it if dry ground is being flagged as flooded, lower it if shallow water is being missed. It is worth checking one cycle you know well before trusting a whole series.

Maximum cloud cover

Scenes cloudier than this are dropped before anything is computed. Twenty per cent is a reasonable default. Raising it admits more observations at the cost of their quality; lowering it can leave parts of a wet season with nothing to count.

Hydroperiod

The first tab, and the one the others build on. Choose which layer of the result to draw and which cycle to draw it for, then press Add data.

1 2 3

The picture fills in gradually. Earth Engine computes as the map asks for tiles, so what you are watching is the computation happening, not an image being downloaded.

1 2 3

How the days are counted

A cycle is counted from the scenes that survive the cloud filter, and those are never evenly spaced: a run of cloudy weeks leaves a gap, a good spell leaves several scenes days apart. Rather than treat every scene as one observation, each is made to answer for the stretch of time around it. The boundary between two consecutive scenes falls halfway between them, and the first and last scenes reach out to the start and the end of the cycle.

A pixel a scene sees as water is credited with all the days that scene stands for, and the same weighting counts the days the pixel was observed at all. That second total is what Normalized hydroperiod divides by, which is why it is comparable between pixels that were seen very different numbers of times.

This is not a method invented for this application. It comes from Phydroperiod, a Python package by Diego García Díaz and Javier Bustamante Díaz (EBD-CSIC) written to compute hydroperiods from water masks over Doñana. ndvi2gif carries the same midpoint weighting, generalised to run anywhere on Earth Engine, and that is what this application calls. The diagram above is Phydroperiod's own.

Blank ground inside the wetland has not been forgotten. Hydroperiod products are masked to pixels that held water at some point during the period; ground that never flooded is left undrawn rather than painted as zero.

Layers on the map

Every layer you add stays on the map and appears twice: in the layer switcher at the top-right corner, and in the bar under the map.

1 2 3 4

Layers are named after what they are and the area they were computed over, because with several up the product alone does not tell one run from another. Add the same product for two cycles and you get two layers, ready to compare.

Anomalies

How unusual a cycle was, in days above or below a reference mean.

1 2 3

The reference is the choice that matters:

• Mean of the selected period — the average of the years you asked for. Answers “was this year unusual for this period?”
• Historical mean — the average of the sensor's entire archive. Answers “was this year unusual, full stop?”, and is considerably more expensive to compute.

You can draw either the reference mean itself or the anomaly of one cycle against it. Anomalies run from −180 to +180 days: blue where the cycle was wetter than the reference, red where it was drier.

1 2 3

Terrain wetness

The topographic wetness index, TWI = ln(a / tan β), where a is the upstream drainage area per unit contour length and β the local slope. It says where water tends to gather, from the shape of the ground alone.

1 2

It uses neither the sensor nor the period beside it, so it is the same layer whatever those say. Two elevation models are offered: MERIT Hydro at about 90 m, internally consistent, and a 30 m hybrid that sharpens the slope with NASADEM. In the hybrid the flow accumulation still comes from MERIT at about 90 m — proper sink filling and flow routing at 30 m is not practical on Earth Engine, and claiming 30 m for the whole index would be claiming more than it delivers.

Statistics

Measures any product over points or polygons of your own. It measures what the other tabs are set to produce, so the numbers are of exactly the layer you have been looking at.

1 2 3 4 5

Upload a .geojson, .json or zipped shapefile, up to 20 MB. The application works out for itself whether it holds points or polygons and which column carries the name.

• Points give the value of the pixel each one falls in.
• Polygons give mean, median, minimum, maximum, standard deviation and pixel count.

Leave the scale empty to sample at the product's own resolution — 10 m for Sentinel-2, 30 m for Landsat, 500 m for MODIS, 90 m for TWI.

1 2

The table appears under the map, where it has the width to be read, and survives switching tabs. Download CSV saves exactly those rows directly, without involving Drive.

Compute stats waits for Earth Engine and is capped at 1,000 features — past that the honest answer is a Drive export rather than a request that times out. Send to Drive hands the same job to Earth Engine as a CSV and returns immediately, and is the way to do anything larger.

Exporting

Exports produce GeoTIFFs in your own Google Drive, computed on your own Earth Engine account.

1 2 3 4

There are two quite different jobs behind the one tab:

• Every hydrological cycle of the period — one file per cycle, named hydroperiod_<area>_<year>_<year+1>, each carrying all the bands of that cycle.
• Only the product currently selected — a single file of whatever one layer you name: a TWI, an anomaly, one band of one cycle.

Exports are queued, not waited for. The application returns as soon as Earth Engine accepts the tasks and names them in the log; Earth Engine runs them on its own time, and the files appear in Drive later. Progress is followed from the Earth Engine task manager, not from here.

One thing to know before opening the files in QGIS: inside a per-cycle GeoTIFF the IRT band is stored as thousandths in a whole number, because Earth Engine will not export bands of different types in one file. Divide that band by 1,000 to get back the 0–1 value the map shows. The other bands are day counts and need nothing done to them.

Reading and comparing

Reading a value

The button below the drawing tools turns the map into a value reader: the pointer becomes a crosshair, and a click asks what the layer says at that point instead of panning.

1 2

It reads the layer that is drawn, not whatever the panel happens to have selected by the time you click — the browser sends back the very settings that produced the layer you are looking at.

Comparing two layers

Add two layers, then split the map between them with a divider you drag across. A hydroperiod against its anomaly, two cycles of the same band, the TWI against either.

1 2 3

Nothing here goes back to Earth Engine: both layers are already on the map, so the curtain is instant. Removing either layer ends the comparison and says so in the log.

The map itself

The switcher at the top-right corner carries the basemaps and every layer you have added, each of which can be turned off without being removed. The map opens framed on the study area outline and will not pan outside it. Fullscreen is worth knowing about when showing the application to a room.

The log

The strip at the foot of the panel narrates every request: what was asked of Earth Engine, over which area, and what came back.

1 2 3

It is the first place to look when something does not appear. Errors are in red and are written to say what to change — which cycle is outside the period, which file is missing, which computation was too large — rather than only that something failed. Clear empties it; nothing else does.

A worked example

End to end, the way it would be demonstrated: how flooded were the Braila Islands over the last five cycles, and was the most recent one unusual?

1. Open the Danube Basin study area from the home page.
2. Set Area source to Ramsar wetlands and pick the wetland. The map frames it.
3. Leave the sensor on Sentinel-2 and the period on the five cycles it opens with. Leave MNDWI and a threshold of 0.
4. On the Hydroperiod tab, leave the layer on Normalized hydroperiod, choose the most recent cycle, and press Add data. Watch it fill in.
5. Turn on the value reader and click a few pixels — a permanent lake, a seasonal margin, a field outside — to get a feel for the numbers behind the colours.
6. Switch to Anomalies, keep the reference on Mean of the selected period, and add the anomaly for the same cycle. Blue is wetter than the five-year mean, red is drier.
7. In Compare side by side, put the hydroperiod on the left and the anomaly on the right, and drag the divider across.
8. To take it away: Export tab, every cycle of the period, 10 m, and Start export. Five tasks are queued and named in the log; the files arrive in Drive shortly afterwards.

That is roughly a five-minute demonstration, and every step of it is one the audience can repeat on their own account.

Limits and errors

“The computation does not fit in Earth Engine.”

Earth Engine refused it for size. Shorten the period, choose a coarser sensor, or work on a smaller area. Long periods over large wetlands at 10 m are the usual cause, and the historical anomaly reference is the most expensive thing the application can be asked for.

Everything has become slow

Your project's monthly Earth Engine allowance is probably spent, which puts it into a restricted mode rather than cutting it off. It resets on the first of the month; the first manual covers the tiers.

“Your Earth Engine authorization has expired.”

The stored token has stopped working. Reconnect the account from the badge at the top of the page.

The layer covers only part of the wetland

Working as intended: only pixels that held water at some point in the period are drawn. Ground that never flooded is left blank rather than painted as zero.

The layer looks wrong, or far too dry

Check Days with valid data for the same cycle. Few valid observations — a cloudy season, a cloud limit set too low — makes a hydroperiod that is poorly constrained rather than wrong. After that, suspect the threshold.

“The chosen cycle falls outside the period.”

The cycle asked for is not among those the period covers. Widen the period or pick a cycle inside it.

The statistics refuse to run

Above 1,000 features they will not be computed while you wait. Use Send to Drive.

Nothing happens when I press a button

Read the log. An area that was never chosen, a file that was never uploaded and a map that has not finished loading all say so there.