DMAP-AI Research Version Tutorial | SPI Tables, Charts, Severity & Wavelet

Step-by-step: run the Research Version

Follow these steps to run a point-based SPI analysis, review the outputs, and save the result in your DMAP-AI account.

Open the Research Version and sign in. Open the DMAP-AI Research Version app. Sign in with Google so completed runs can be saved and reloaded from the dashboard.
Select the drought index. In the free Research Version, choose SPI — Standardized Precipitation Index. Other drought indices are shown as planned licensed or research capabilities.
Select a point on the map. Choose Point mode, then click the map. The latitude and longitude boxes should be filled automatically. The values can also be typed manually.
Use historical mode. The current free workflow uses historical analysis. Forecast and prediction workflows are planned for licensed or future versions.
Choose the data source. Select NASA POWER for the default free point-based source. Select ERA5-Land / CDS when the advanced reanalysis option is needed and backend CDS access is configured.
Set dates and baseline. Select the analysis period. NASA POWER supports dates from 1981 onward. The baseline box is optional; if it is left empty, the backend can use the selected analysis period as the baseline.
Choose the aggregation. The Research Version is designed for Yearly point-based SPI. For the standard yearly workflow, use Jan–Dec totals.
Click Run. The backend downloads or reads climate data, calculates SPI, and returns tables and charts. ERA5-Land can be slower on the first run because data may need to be downloaded.
Review the result tabs. Use the Table tab explanation, Charts tab explanation, Severity tab explanation, and Wavelet tab explanation below to read the outputs.
Save the run. Click Save current run in the dashboard. Saved runs can be reloaded later from the dashboard.
Use JSON or Debug when needed. The JSON tab is useful for reporting, reproducibility, or AI-ready context. The Debug tab is mainly for checking API requests and troubleshooting.

Table tab: SPI values, categories, and thresholds

The Table tab is the main numerical output of the Research Version. It shows the selected time step, precipitation total, SPI value, and drought/wetness category.

SPI table

What does the SPI column mean?

SPI is a standardized drought index based on precipitation. An SPI value near zero means precipitation is close to the baseline climate. Negative SPI values indicate drier-than-normal conditions, and positive SPI values indicate wetter-than-normal conditions.

SPI below 0: drier than the baseline period.
SPI near 0: close to normal precipitation.
SPI above 0: wetter than the baseline period.
More negative SPI: stronger drought signal.

Detailed background is available in the Standardized Precipitation Index method guide.

Category methods

Four category methods in the Table tab

The category selector changes how the same SPI values are grouped into classes. The SPI values do not change; only the interpretation labels change.

Category method	How it groups the SPI results	How to interpret it
Classic SPI thresholds	Uses common SPI drought/wetness thresholds such as moderate, severe, and extreme drought.	Best for standard SPI reporting and comparison with many drought-index studies.
USDM style	Maps dry SPI values to drought-monitor style classes such as abnormally dry, moderate drought, severe drought, extreme drought, and exceptional drought.	Useful when the result needs to be described in language similar to drought-monitor products.
Percentile bands	Uses the rank or percentile position of values within the selected distribution.	Useful for reading how unusual a value is compared with the local record or baseline.
AI/ML k-means clusters	Uses data-driven clusters. The class boundaries are not fixed; they depend on the analyzed data.	Useful for exploratory grouping, but the classes should be read as relative clusters, not fixed drought thresholds.

Thresholds

Category tables used in the Table tab

The Table tab can display the same SPI values using different category methods. The Classic and USDM-style methods use fixed SPI thresholds. The Percentile and AI/ML k-means methods depend on the distribution of the current run.

Classic SPI threshold table
SPI range	Category	Interpretation
SPI ≤ -2.00	Extreme drought	Very strong dry signal.
-2.00 < SPI ≤ -1.50	Severe drought	Strong dry signal.
-1.50 < SPI ≤ -1.00	Moderate drought	Moderate dry signal.
-1.00 < SPI < 1.00	Near normal	Close to normal precipitation conditions.
1.00 ≤ SPI < 1.50	Moderately wet	Moderate wet signal.
1.50 ≤ SPI < 2.00	Very wet	Strong wet signal.
SPI ≥ 2.00	Extremely wet	Very strong wet signal.

USDM-style category table used by the Research Version
SPI range	USDM-style label	Interpretation
SPI ≤ -2.00	D4 – Exceptional drought	The strongest USDM drought category in the SPI/SPEI classification range.
-2.00 < SPI ≤ -1.60	D3 – Extreme drought	Extreme dry conditions.
-1.60 < SPI ≤ -1.30	D2 – Severe drought	Severe dry conditions.
-1.30 < SPI ≤ -0.80	D1 – Moderate drought	Moderate drought conditions.
-0.80 < SPI ≤ -0.50	D0 – Abnormally dry	Dryness signal; D0 is abnormally dry and is not counted as drought in the same way as D1–D4.
SPI > -0.50	No drought / normal or wet	No USDM-style dry class is assigned from SPI. The official USDM table lists this as -0.49 or above.

These USDM-style labels are adapted from the official U.S. Drought Monitor drought classification table, which provides approximate SPI/SPEI ranges for D0–D4 classes. They are used inside the Research Version only as SPI-based communication labels. They are not an official U.S. Drought Monitor map because the official USDM uses multiple indicators, local information, expert assessment, and drought impacts; see the U.S. Drought Monitor drought classification table.

Percentile bands used by the Research Version
Band	Label	Interpretation
Lowest ≈5%	Extreme drought	One of the lowest SPI values in the current record.
≈5% to ≈20%	Moderate drought	Lower-than-usual SPI value relative to the current record.
≈20% to ≈80%	Near normal	Middle part of the SPI distribution.
≈80% to ≈95%	Moderate wet	Higher-than-usual SPI value relative to the current record.
Top ≈5%	Extreme wet	One of the highest SPI values in the current record.

AI/ML k-means clusters
Cluster position	Label style	Interpretation
Driest cluster	AI: Extreme drought	The lowest SPI cluster in the current data.
Dry clusters	AI: Severe or moderate drought	Clusters below the near-normal group.
Middle cluster	AI: Near normal	Cluster closest to typical SPI behavior in the current data.
Wet clusters	AI: Moderately wet, very wet, or extremely wet	Clusters above the near-normal group.

K-means is data-driven. Its class boundaries change from one run to another, so it is useful for exploratory grouping but should not replace fixed SPI drought threshold interpretation.

Charts tab: SPI line, precipitation anomaly, and boxplot

The Charts tab helps users see the drought history visually. It is useful for finding dry periods, wet periods, shifts in precipitation behavior, and unusual years.

SPI chart

SPI time-series chart

The SPI chart plots SPI values through time. Values below zero show dry conditions, and values above zero show wet conditions. The farther the line moves away from zero, the stronger the dry or wet signal.

Periods below -1 usually indicate drought conditions.
Periods below -1.5 or -2 show stronger drought intensity.
Periods above 1 indicate wet conditions.

Bounds

Lower and upper bounds

The lower and upper bounds are visual reference lines. They help users see when SPI moves outside the near-normal range.

Lower bound: commonly used to highlight dry or drought conditions.
Upper bound: commonly used to highlight wet conditions.
When SPI stays beyond a bound for several time steps, the event is more persistent.

Anomaly chart

Precipitation anomaly chart

The anomaly chart shows whether precipitation is above or below a reference level. Positive bars indicate wetter-than-reference periods, and negative bars indicate drier-than-reference periods.

Large negative anomalies often align with negative SPI values.
Large positive anomalies often align with positive SPI values.
Repeated negative anomalies can help explain drought development.

Boxplot

Boxplot chart interpretation

A boxplot summarizes the spread of SPI or precipitation values. It shows the central range, typical variability, and possible outliers.

Boxplot item	Meaning	Interpretation
Median line	The middle value of the distribution.	Shows the typical condition for the selected group.
Box	The middle 50% of values.	A taller box means more variability.
Whiskers	The wider range of non-outlier values.	Long whiskers show a wider spread.
Outliers	Values far from the main distribution.	Can indicate unusual dry or wet periods.

Use the SPI table categories together with the charts. The table gives exact values, and the charts show the temporal pattern.

Severity tab: drought events, shaded SPI events, and drought magnitude

The Severity tab identifies drought events and summarizes their duration, intensity, and drought magnitude. This section focuses on drought severity, not wetness magnitude.

Drought events

What is a drought event?

A drought event is a continuous period when SPI remains below the selected drought threshold. For example, if the threshold is -1.0, each continuous sequence of SPI values at or below -1.0 is treated as one drought event.

Start: the first time step when SPI crosses below the threshold.
End: the time step when SPI returns above the threshold.
Duration: the number of time steps in the event.
Minimum SPI: the driest SPI value during the event.

Shaded events

Drought severity — SPI line with shaded events

This chart shows the SPI line and shades the parts of the record classified as drought events. The shaded sections represent drought periods only. Wet periods above zero are not included in the drought-event magnitude calculation.

Longer shaded sections indicate longer drought duration.
Deeper SPI values inside shaded sections indicate stronger drought intensity.
Several shaded sections close together may show repeated drought stress.

Drought threshold SPI

Which drought threshold should be entered?

The drought threshold is the SPI value used to decide whether a time step is part of a drought event. The common threshold for moderate drought detection is -1.0. The tool may show this as SPI ≤ -1.0 or SPI ≤ -0.99.

Threshold entered	Event meaning	Use in interpretation
-1.0	Moderate drought and worse	General drought-event detection.
-1.5	Severe drought and worse	Focuses on stronger drought events.
-2.0	Extreme drought	Focuses only on the most extreme dry events.

Magnitude

What is drought magnitude?

Drought magnitude summarizes how far the SPI values fall below the drought threshold during an event. It combines drought intensity and duration. Larger magnitude means a stronger and/or longer drought event.

Item	Meaning	Unit
SPI deficit for one step	Difference between the drought threshold and the SPI value when SPI is below the threshold.	SPI units; SPI itself is dimensionless.
Magnitude for an event	Sum of drought deficits across all time steps in the drought event.	SPI × time step. For yearly analysis, this can be read as SPI-years.
Larger magnitude	The drought was deeper, longer, or both.	Relative severity value, not precipitation in millimeters.

A magnitude greater than 2 does not have one universal category by itself. It depends on the selected threshold and time scale. For example, a magnitude near 2 could come from one very dry year or from several moderately dry years. Compare magnitude together with SPI category thresholds, event duration, and minimum SPI.

Method details are available in the drought severity method guide.

Wavelet tab: scalogram, global spectrum, coherence, and dominant periodicity

Wavelet diagnostics help users examine when drought variability is strong and which time scales are dominant. In the Research Version, the period axis is interpreted in the time step of the analysis: years for yearly SPI and months for monthly SPI.

Scalogram

Wavelet scalogram

A wavelet scalogram shows wavelet power across time and period. The horizontal axis is time, the vertical axis is period or scale, and the color intensity shows the strength of SPI variability.

Unit: time is in the selected analysis time step; period is also in time steps. For yearly SPI, a period of 4 means about 4 years.
Application: shows when drought variability was strongest and whether it was short-term or multi-year.
Interpretation: strong power concentrated at a period means SPI fluctuated strongly at that drought time scale during that part of the record.

Global spectrum

Global wavelet spectrum and dominant periodicity

The global spectrum summarizes wavelet power across the whole record for each period. Peaks in this chart indicate dominant periodicities.

Unit: the period axis is in the analysis time step. For yearly SPI, a peak near 5 means an approximate 5-year dominant periodicity.
Application: identifies the main drought-relevant time scales in the full record.
Interpretation: the highest peak is the dominant periodicity, but it should be checked against the scalogram to see whether it exists across the full record or only during part of it.

Coherence

SPI–precipitation coherence vs period

Coherence is a unitless value from 0 to 1 that shows how consistently SPI and precipitation vary together at each period. In the Research Version, SPI is calculated directly from precipitation, so coherence can be very high and may often be close to 1.

Unit: coherence has no unit; it ranges from 0 to 1.
Application: checks whether SPI behavior is aligned with the precipitation signal used to calculate it.
Interpretation: if coherence is always near 1, it mainly confirms that the SPI output is consistent with the precipitation input. It is less useful as an independent discovery chart in this single-variable SPI workflow.

Interpretation workflow

How to interpret the three wavelet charts together

The three wavelet charts answer different questions. The scalogram shows when strong drought variability occurred, the global spectrum shows the dominant periodicity across the full record, and coherence checks how strongly SPI follows the precipitation signal at each period.

Chart	Main question	Drought-analysis use
Wavelet scalogram	When did strong SPI variability occur?	Find drought periods with strong short-term or multi-year variability.
Global spectrum	What period is dominant overall?	Identify dominant periodicity, such as an approximate 3-year, 5-year, or 8-year drought cycle in the analyzed record.
SPI–precipitation coherence	Does SPI follow precipitation at this period?	Confirm consistency between precipitation and SPI. If it is always 1, read it mostly as a calculation/consistency check.

A dominant periodicity is not automatically a forecast. It describes repeated variability found in the historical record. It should be interpreted together with drought event severity, SPI charts, and the selected data source.

See the wavelet diagnostics method guide for additional scientific background.

Other Research Version interpretation rules

These rules help explain data-source behavior, saved runs, and supporting output tabs.

Data source rules

NASA POWER and ERA5-Land/CDS

NASA POWER is the default free point data source. ERA5-Land/CDS is available as an advanced option and may require backend CDS configuration.

Data source	Use in the Research Version
NASA POWER	Available from 1981 onward for point-based Research Version runs.
ERA5-Land/CDS	Advanced reanalysis option. Long requests may take more time.
Baseline empty	The backend can use the selected analysis period as the baseline.
Baseline entered	The entered baseline period is used if it is valid for the selected source.

NASA POWER supports dates from 1981 onward. ERA5-Land/CDS requires CDS access configured on the backend server.

Saved runs

Project organization

Saved runs help users compare locations, dates, and data sources. Each saved run keeps the selected inputs, outputs, and related metadata.

Action	Purpose
Save current run	Save the active SPI results and metadata to the dashboard.
Load	Reload a previous result without running the API again.
Delete	Remove a saved run from the dashboard.
JSON tab	Use for reporting, reproducibility, or AI-ready scientific context.

Learn more about each method

This tutorial explains how to use and interpret the Research Version. The method pages explain the scientific background, formulas, and assumptions.

Related pages: Open the DMAP-AI Research Version drought analysis app, return to the DMAP-AI tutorial hub, or review the DMAP-AI drought methods and thresholds page.

Standardized Precipitation Index methodLearn how SPI is calculated and why it is used for drought analysis. SPI drought and wetness thresholdsReview the threshold classes used to label SPI values. Drought severity and event detectionRead about drought thresholds, duration, minimum SPI, and severity metrics. Wavelet scalogram and global spectrumUnderstand wavelet power, dominant periods, and time-scale diagnostics. Copula dependence and persistence diagnosticsReview dependence, Kendall tau, tail dependence, and drought persistence concepts. NASA POWER and ERA5-Land/CDS data sourcesLearn how the Research Version uses precipitation data sources.

How to run the Research Version and interpret SPI outputs