DMAP V2.1 Complete User Tutorial

Open PDF Download PDF Formulas → Back to DMAP

1. Introduction

DMAP V2.1 is a Windows desktop application for calculating and analyzing drought indices from station-based or gridded climate data. It covers the full workflow of drought monitoring: defining a network of stations, importing or downloading climate data for those stations, computing any of 19 drought indices at daily, weekly, monthly, seasonal, or yearly resolution, and running follow-on statistical analyses (trend detection, wavelet spectral analysis, drought event extraction, severity-duration-frequency analysis, and teleconnection correlation) on the computed index.

The application window is organized around three top-level tabs: Stations, Data, and Drought Indices. Data flows through these tabs in order. A station list is defined first (Stations tab). Climate variables for those stations are then loaded, either from local Excel/text/NetCDF files or by downloading them directly from public climate archives (Data tab). Once at least one climate variable is loaded, drought indices become available for calculation, and their results can be tabulated, charted, exported, and passed to further analysis windows (Drought Indices tab).

1.1 What DMAP calculates

DMAP groups its 19 drought indices into three families, matching the three columns of the Drought Indices tab:

Every index has specific data prerequisites (for example PDSI needs rainfall, PET, and soil water-holding capacity; VHI needs NDVI and land surface temperature). Section 7.5 of this tutorial gives the complete prerequisite table exactly as the application enforces it.

1.2 Launching the application and the main window frame

The main window title bar reads "DMAP V2.1". Directly below the title bar is a toolbar that is visible regardless of which tab is active, followed by the three top-level tabs (Stations, Data, Drought Indices). The content beneath the tabs changes according to which tab and sub-tab are selected, but the toolbar at the top stays fixed.

Toolbar controls, left to right

The three top-level tabs

Stations: define the list of monitoring locations (name, latitude, longitude, and the soil parameters some agricultural indices require) and see them plotted on an interactive map. Data: import or download the climate variables (rainfall, temperature, humidity, soil moisture, streamflow, vegetation reflectance, and so on) that feed the indices, split into three sub-tabs (Excel, NetCDF, and Download). Drought Indices: select a station-loaded variable set, choose which index to compute and at what time scale, run the calculation, and inspect the results as a table or chart, or hand them off to Trend, Wavelet, Multi-Scale, or Drought Event analysis.

Switching to the Data or Drought Indices tab before at least one station has been added leaves most of their controls disabled; the application enables controls progressively as prerequisite data becomes available, and every disabled control that requires something specific reports that requirement in its tooltip. Hovering over a greyed-out drought index radio button, for instance, always states exactly what data is missing.

2. Registration and Licensing

DMAP distinguishes between a free (unregistered) installation and a registered installation. A defined set of actions require a valid registration: calculating a drought index (the Calculate button on the Drought Indices tab); loading a file on the Data tab's Excel sub-tab (Open File) or NetCDF sub-tab (Select Data File); and every action on the Data tab's Download sub-tab (Start Download, the NASA AppEEARS/MODIS download, and Open CMIP6 Window). Every other tab and control, including station management, the View and Export Data window, and every analysis window once an index has been computed, remains fully usable without a license. An unregistered installation also carries a persistent reminder of its status, described in Section 2.2.

2.1 The Register window

Opened from the key icon in the toolbar (tooltip "Register"), from the Register link in the free-version banner (Section 2.2), or automatically whenever an unregistered user clicks one of the gated actions listed above. Its content depends on whether the current installation is already registered.

On an unregistered installation, the window shows a read-only Machine ID field together with a Copy ID button, and instructions to email that ID, along with proof of payment, to kolsoomi57@gmail.com or support@agrimetsoft.com. Two buttons, one per address, open the default mail client with the Machine ID already filled into the message body. There is no key or activation code to type into this window: a license is issued manually, by AgriMetSoft adding the submitted Machine ID to the application's license list and returning an updated build to the customer.

On an already-registered installation, the window instead shows a simple confirmation ("This installation is registered.") together with the license's expiry date, and omits the Machine ID and email controls entirely, since a registered user has nothing further to do here.

If a gated button is clicked while unregistered, DMAP shows the message "You have an unregistered version. Purchase a license to activate DMAP. Visit www.agrimetsoft.com" and, for Calculate specifically, also opens the Register window directly.

2.2 The free-version banner and startup notice

An unregistered installation displays a banner, visible on every tab, stating that DMAP is running in a free/unregistered mode and offering a direct link that opens the Register window. In addition, a one-time notice appears once per application launch (not on every window activation), restating the free-version status and license-purchase instructions. Both disappear automatically as soon as a valid registration is recognized, with no application restart required.

2.3 About Us

Opened from the people icon in the toolbar. Shows the AgriMetSoft logo (a clickable link to agrimetsoft.com), a short description of the company's mission, Facebook and Twitter icon links, and a one-paragraph description of DMAP itself along with a copyright line. A Back button closes the window and a Visit Our Website button opens the AgriMetSoft home page.

3. The Stations Tab

The Stations tab is the natural starting point for any DMAP session: every drought index calculation, every data import, and every download is performed per station, so at least one station must exist before the Data or Drought Indices tabs become useful. The tab is split into a left column (station list and file-fill controls) and a right pane (an interactive map).

3.1 Fill Station List By File

This group box lets you populate the station table in one step from an existing file rather than typing each station by hand. The "If you want browse text file use delimiter" text box holds the field separator that will be used only if the chosen file is a plain-text (.txt) or comma-style (.csv) file; it defaults to a comma. Clicking Fill List by File opens a file picker restricted to Excel workbooks (.xlsx, .xls), delimited text (.csv), or plain text (.txt).

For a .txt or .csv file, DMAP reads the file directly using the delimiter you specified. Every character in the delimiter box is treated as a separate splitting character, so a multi-character delimiter such as "::" is not treated as one two-character token but as two separate single-character delimiters. For an Excel workbook, DMAP first enumerates its sheet names and opens a secondary dialog where you map columns to station fields and pick which sheet to read before the station list is populated. After the file loads, the station table refreshes and the map redraws its pins automatically.

3.2 List Of Stations

An editable grid with one row per station and the following columns, visible left to right in the screenshot below: Name, Latitude, Longitude, Field Capacity (mm), Surface Soil, and Available Water Capacity (the last two are scrolled out of view in the screenshot but present in the grid; use the horizontal scrollbar beneath the grid to reach them). The grid allows adding new rows directly (a blank row is always available at the bottom) and editing any cell in place.

Field Capacity (mm) column: exact tooltip guidance

Hovering over this column's header reveals specific numeric guidance built into the application: 75 mm is typical for sandy soils, 100 to 125 mm for loam, and 150 to 200 mm for clay; roughly 100 mm is suggested as a reasonable default for an Iowa loam soil. The tooltip also gives a troubleshooting rule: if KBDI output is persistently pinned at 800 (KBDI's maximum possible value, indicating the deepest possible moisture deficit), the Field Capacity value is very likely set too low and should be raised.

Field Capacity is a hard prerequisite for KBDI specifically: it is disabled on the Drought Indices tab for any station where Field Capacity is zero or blank. Surface Soil and Available Water Capacity feed the Palmer-family indices (PDSI, PHDI, PDSI-SC) instead; a station missing either of those two values will not make the Palmer indices available even if rainfall, temperature, and PET are all loaded.

3.3 Station Locations map

The right-hand pane embeds a Leaflet/OpenStreetMap web map. Every station in the grid that has valid numeric latitude and longitude is plotted as a blue pin, labeled with its station name. The map supports the usual pan (click-drag) and zoom (+/- buttons in the top-left corner, or the mouse wheel) interactions of any web map.

Two buttons sit below the map. Fit Stations (tooltip: "Zoom map to show all stations") recenters and rescales the view so every plotted station is visible at once, which is useful after adding a station far from the current view. Clear Pins (tooltip: "Remove all pushpins from map") removes every pin from the map display without deleting any station from the underlying table; the pins reappear the next time the map refreshes (for example after editing the station grid). A status label to the right of these buttons reports the map's current state, for example "Map ready. Add stations to plot them."

4. The Data Tab: Excel Sub-tab

The Data tab holds three sub-tabs (Excel, NetCDF, Download), selected with the small secondary tab strip just below the main Stations / Data / Drought Indices tabs. The Excel sub-tab is the route for loading climate variables from spreadsheet or delimited text files you already have on disk.

4.1 Store As Variable

Three columns of radio buttons determine which internal variable slot the file about to be loaded will fill. Only one variable can be targeted per load: to load both Rainfall and Tmax, for example, the whole Open File / Load Data sequence below must be repeated once per variable, each time with the corresponding radio button selected first.

Rainfall is selected by default whenever the tab is opened. A warning text block beneath this group is hidden by default and only appears for variable choices that need extra caveats explained at load time.

4.2 File Settings

Delimiter: the field separator used when the chosen file is plain text or CSV; defaults to a comma, and, as on the Stations tab, every character typed here is treated as an independent delimiter character rather than a single multi-character token.

Open File: launches a file picker accepting .xlsx, .xls, .csv, or .txt files. For a delimited text file DMAP reads it immediately with the delimiter above. For an Excel workbook, the adjacent sheet-selector combo box (disabled until a workbook is chosen) becomes enabled and populated with every sheet name in the workbook, so a specific sheet can be picked before loading.

Auto-Fill Headers: disabled until a file has been opened; attempts to guess a column-to-station mapping from the file's first row automatically rather than requiring manual assignment of every column.

Date Format: a combo box, disabled until a file is opened, offering a set of preset date-format patterns (for example YYYY, MM/DD/YYYY, other common regional orderings, and full date-and-time patterns with a 12-hour clock and AM/PM designator) plus an "Auto-Detect" option, which is selected by default and instructs DMAP to infer the date format directly from the values in the first data row rather than requiring the format to be specified explicitly. Auto-Detect recognizes both date-only values and full timestamps such as "1/1/1993 12:00:00 AM".

First Row Is Header: checked and disabled by default, reflecting the common case that the first row of the file contains column names rather than data.

Input Timing

A group of three mutually exclusive radio buttons, Daily (checked by default), Monthly, and Yearly, disabled until a file is opened, that tells DMAP the native time step of the values in the file. This setting directly controls how many periods per year are stored for the loaded variable, which in turn determines which drought indices and which Time Scale options become available once the variable is in memory (see Section 7).

Load Data: disabled until a file has been opened and its settings configured; performs the actual import. On success a dialog reports the outcome in the exact form "'{Variable}' loaded successfully. {N} station(s), {M} years." as shown in the screenshot above ("'Rainfall' loaded successfully. 1 station(s), 20 years."). Loading is wrapped in error handling, so a malformed file produces a plain message-box with the underlying error text rather than a silent failure.

4.3 Input Data Preview

A read-only, disabled-until-populated DataGrid beneath the settings that mirrors the raw file after loading: one Date column followed by one column per station, with alternating row shading for readability. Each column header in the underlying file-mapping dialog carries its own small drop-down (visible as "None", "Date", station-name entries in the interface) used to tell DMAP which physical column in the source file corresponds to which role: date column, or a specific station's data column, before the load is finalized.

5. The Data Tab: NetCDF Sub-tab

The NetCDF sub-tab loads gridded climate data directly from NetCDF (.nc) files, the standard format for reanalysis products, CMIP model output, and most other gridded scientific datasets, and extracts a time series for each station (or grid cell) of interest. It is organized into three group boxes: Settings, Loading, and a separate Unit Converter panel on the right.

5.1 Settings

Select Data File opens a file picker for the .nc file. Select Dataset is an editable combo box, disabled until a file is chosen, that lists the data variables found inside the NetCDF file so the correct one can be picked ("pr" in the screenshot, a common short name for precipitation in CF-convention NetCDF files). View Database, disabled until a dataset is selected, opens a separate preview window (distinct from the View and Export Data window covered in Chapter 14) showing the raw contents of the selected dataset before extraction.

The Variables Name group tells DMAP which named dimensions in the file correspond to time, latitude, and longitude. It is pre-filled with the common defaults time, lat, and lon, which match most public reanalysis and CMIP files but can be edited for files that use non-standard dimension names. Time Units and Since together describe the file's time encoding (for example "days" "Since" "1850-1-1", the standard CMIP6 epoch), and Time Calendar names the calendar system in use (for example calendar = "gregorian"). These three settings must match what is actually encoded in the NetCDF file's metadata; DMAP does not attempt to auto-detect them.

5.2 Loading

Three mutually exclusive radio buttons control how grid points are selected and, correspondingly, what "a station" means for this particular extraction:

Is CORDEX data is a checkbox that adjusts how DMAP parses the file for the regional-climate-model CORDEX archive's particular NetCDF layout, which differs slightly from standard CMIP-style files. VariableName is the exact internal variable name to extract (matching the Select Dataset choice). Load Data performs the extraction using all the settings above; View Data (distinct button from View Database) opens a simple read-only grid of the values just extracted, one column per station and one row per date, with a Close button and no editing, filtering, or export controls of its own. For filtering, charting, or exporting loaded NetCDF data, use the Export All Data / View and Export Data window described in Chapter 14 instead.

Use Progress Bar and its accompanying progress bar apply to the NetCDF loading step specifically, independent of the equivalent toggle in the main toolbar.

5.3 Unit Converter (for Gridded Data)

Gridded scientific datasets are frequently expressed in units drought calculations do not use directly: temperature in Kelvin, precipitation as a flux rather than an accumulated depth, radiation in energy-per-area-per-time rather than an equivalent evapotranspiration depth. This panel, disabled until data has been loaded, converts the just-extracted values in place.

Variable offers two columns of radio buttons selecting which loaded variable the conversion applies to: Tmax, Tmin, Tave, Rainfall (default) on the left; Soil Moisture, Stream Flow, PET, AET on the right.

Conversion mode radio group

Save and Convert applies the selected conversion to the currently loaded data for the selected variable and writes the converted result back into memory as that variable. Unlike the NetCDF loading step in Section 5.2, this operation has no progress bar of its own: unit conversion runs quickly enough on already-loaded data that a progress indicator is unnecessary. An explanatory line beneath the button states plainly: "Save and convert the extract data from NetCDF files."

6. The Data Tab: Download Sub-tab

The Download sub-tab retrieves climate data directly from public archives over the internet, extracting the value nearest each defined station without requiring any file to be downloaded and imported manually first. Four of its five sources require no account or login of any kind; the fifth (CMIP6) and the separate NASA AppEEARS download window both require a free account with the respective data provider.

6.1 Data Source

Five mutually exclusive radio buttons choose the archive to query. Selecting a different source immediately repopulates the Variable list and the source-information panel described below.

6.2 Date Range and Variable

Start Year and End Year set the requested period; Time Scale and Variable are populated according to the selected source (for example GPCC only ever offers Monthly Rainfall, while NCEP/NCAR offers the full variable list above). A grey confirmation line reports which internal variable slot the download will be stored as. A static italic note reiterates the core mechanism of this whole sub-tab: "Uses station Lat/Lon from the Stations tab to extract nearest grid cell.", meaning at least one station with valid coordinates must already exist before a download can be started.

Below the variable picker, a scrollable information panel updates automatically for the selected source, giving its full name in bold, its date range, its authentication requirement, a bold note field with practical guidance (visible in the screenshot: "RECOMMENDED for long-record SPI analysis. 129-year record. OPeNDAP subsetting: ~1KB per station request. No authentication. Land areas only, ocean and some coastal pixels may return missing values."), and a gray italic academic citation for the dataset.

6.3 Actions, log, and availability legend

Start Download begins the transfer; it is disabled until a station exists and a valid variable/date combination is selected. Cancel, disabled until a download is running, stops an in-progress transfer. Diagnose Source fetches the archive's raw metadata and a small sample slice, intended to help identify why a particular source or variable combination is failing to parse rather than to retrieve usable data itself. Show Progress, checked by default, drives the adjacent progress bar and percentage label.

Open CMIP6 Window is hidden by default and only appears once CMIP6 is selected as the source, at which point clicking it opens the dedicated CMIP6 configuration window described in Section 6.4 (the variable and date range for that download are configured inside that window, not on this tab). NASA AppEEARS-MODIS is always visible and opens the separate AppEEARS download window (Section 6.5) for MODIS-derived vegetation and reflectance products, entirely independent of the five sources listed above.

The Download Log is a read-only, fixed-width (Consolas) text box that records every step of a transfer. The screenshot shows a representative log ending in "NOTE: GPCC data ends 2019-11-30, request end date clamped from 2019-12-01.", "Stored Rainfall for 1 station(s), 24 years.", "Done. Refreshing UI...", "Complete.", useful for confirming exactly what was clamped, skipped, or substituted during a download.

The Variable Availability panel at the bottom is a static, color-coded legend (not tied to the currently selected source) summarizing which download route is needed for every remote-sensing and climate variable in the application: green text lists what the Download tab itself provides instantly; blue text lists what requires the NASA AppEEARS point-extraction window; orange text lists NOAA STAR's large-file variables; dark-blue text lists CMIP6 projection variables; gray text notes that Stream Flow is only available through Excel or NetCDF import, since no download source in the application provides gauge-based streamflow directly.

6.4 The CMIP6 Download window

Opened by Open CMIP6 Window once CMIP6 is selected as the Data Source. This is a separate, fuller-featured configuration window because a CMIP6 request needs a model, an emissions scenario, an ensemble member, and a spatial buffer specified, none of which apply to the four instant-download sources.

Copernicus CDS account

A password-style field holds your CDS Personal Access Token, obtained free from a Copernicus Climate Data Store account; Save Key stores it via Windows Credential Manager so it does not need to be re-entered each session, and a status label confirms whether a key is currently saved.

Request settings

Download + Extract for all stations submits the job to the CDS asynchronous processing API for every defined station, retries automatically on transient failures, and polls for completion over a period that can extend to roughly two hours for a large or heavily-queued request. A status log, progress bar, and Copy Log button track its progress. A second tab within this window, Downloaded Data Preview, lets you pick a station from a combo box and inspect the values retrieved for it in a simple grid once the job completes.

6.5 The NASA AppEEARS Download window

Opened by the NASA AppEEARS-MODIS button on the Download sub-tab. AppEEARS (Application for Extracting and Exploring Analysis Ready Samples) is a NASA service that extracts point time series from MODIS satellite products without requiring the full gridded file to be downloaded. It is well suited to a station network, since DMAP submits every defined station's coordinates as a batch of points in one request.

NASA Earthdata Login

A username and password field (password masked), with Save Credential storing them via Windows Credential Manager and Test Login verifying them against NASA's servers before a real request is submitted. A free Earthdata account, obtained at urs.earthdata.nasa.gov, is required; there is no anonymous access path for AppEEARS.

Product selection

There is no separate point-list control in this window; every station already defined on the Stations tab is submitted automatically as an AppEEARS point. Date Range defaults to 2020-01-01 through 2024-12-31 and is validated against MODIS's actual coverage: the earliest possible start date is February 18, 2000, and the end date is automatically clamped to about two weeks before today to account for MODIS's typical processing latency.

Submit Request logs in, submits the point-extraction task, polls for completion (checking every 5 seconds at first, then every 15 seconds), downloads the resulting CSV files once the task finishes, and parses them into the appropriate DMAP variable slots, applying MODIS's documented scale factors and range checks along the way (for example land surface temperature values are range-checked between 150 and 400 Kelvin and then converted to Celsius; reflectance bands are range-checked between -0.01 and 1.6). Cancel, disabled until a request is running, stops the process. A scrollable status log reports each stage of the submission and, on completion, gives explicit next-step guidance (for example instructing the user to go to the Drought Indices tab and select VHI after an NDVI + LST request finishes).

7. The Drought Indices Tab

This is where a loaded climate variable becomes a drought index. The tab is laid out top to bottom: a compact settings bar (year range, time scale, PET method, accumulation period, and the action buttons), a three-column Drought Indices group box for choosing which index to compute, a Results panel with its own Threshold sub-panel, and a Chart panel at the bottom.

7.1 Settings bar

Year Range (From / To) is disabled until at least one variable is loaded, and is then populated with the full span of years available in memory; it can be narrowed to compute an index over a subset of the loaded record. Time Scale is populated dynamically and differently for every index. It is not a fixed Daily/Monthly/Yearly list, but is rebuilt each time a different index radio button is checked, offering only the resolutions that index actually supports given the data currently loaded (for example, selecting Monthly for SPI additionally unlocks the Accumulation Period box described below, but only for SPI, CZI, MCZI, and ZSI).

PET Method has one entry, Thornthwaite, and is only enabled when a Palmer-family index (PDSI, PHDI, PDSI-SC) is selected; if the fuller Penman-Monteith input set (Tmax, Tmin, Humidity, Wind Speed, Solar Radiation) is all loaded, a second option, Penman-Monteith (FAO-56), is added automatically to this same combo box. Standardize for RDI, a checkbox, is enabled only when RDI is selected and applies an additional standardization step specific to that index.

KBDI Options is a small panel that stays hidden until KBDI is selected, at which point it appears with a Wet-day (mm) threshold field. DMAP inspects the loaded rainfall series when KBDI is selected and pre-fills this threshold intelligently: if more than 10% of rainfall values fall in the near-zero range between 0 and 0.1 mm (a pattern typical of gridded or model-derived rainfall, which frequently reports trace "drizzle" values that station gauges would round to zero), the threshold defaults to 0.1 mm with a note explaining the detection; otherwise it defaults to 0, with a note that station data was detected.

7.2 Calculate PET and the PET Calculator window

The Calculate PET button, tooltip: "Compute PET from Temperature (Thornthwaite/Hamon), Tmax+Tmin (Hargreaves-Samani), or the full Penman-Monteith variable set -- then PDSI/PHDI/SPEI become available.", opens a dedicated PET Calculator window. This is the recommended route for making PET available whenever only temperature data (rather than a downloaded or imported PET/ETo variable) has been loaded, since SPEI, RDI, ARI, PDSI, and PHDI all require PET directly.

Inside the PET Calculator window, four mutually exclusive methods are offered, each greyed out until its required inputs are present in memory:

Latitude and elevation are never typed into this window: they are read automatically from each station's own record on the Stations tab. If more than one method's inputs are all available, DMAP pre-selects the most sophisticated one automatically, in the order Penman-Monteith, then Hargreaves-Samani, then Thornthwaite. Clicking Calculate PET computes the result for every station over the currently selected Year Range and stores it as the PET (ETo) variable, reporting a count of how many stations succeeded and, if any were skipped for lacking the needed inputs, how many. On success the window also records which method was used, and if PDSI, PHDI, or SPEI was already selected on the main tab, that index's settings are refreshed immediately so the newly available PET is picked up without needing to reselect the index.

7.3 Choosing a Drought Index: The Three-Column Selector

The Drought Indices group box presents every index as a radio button (only one can be active at a time) arranged in three labeled columns: Meteorological, Agricultural, and Hydro & Remote (the last split further into Hydrological and Remote Sensing sub-groups). A disabled index radio always explains, in its own tooltip, exactly what is missing before it can be selected. The table below reproduces those requirements exactly as the application checks them.

Complete prerequisite table

When a two-variable index is selected (for example SPEI, needing Rainfall and PET together), DMAP additionally checks whether the two variables' loaded year ranges actually overlap. If they do not overlap at all, selecting that index radio has no effect and clicking Calculate later shows an explicit error. If they overlap only partially, the Year Range fields are automatically narrowed to the overlapping years and a note appears above the index list explaining the adjustment, so results are never silently computed over years where one of the two required variables has no data.

A handful of indices carry their own additional resolution warning even once nominally enabled: KBDI and PDSI-SC both refuse to proceed with anything coarser than monthly data and show an explicit dialog naming the problem (for example "KBDI requires DAILY precipitation and Tmax data... Results will be scientifically incorrect." if seasonal data is detected) rather than silently computing a numerically meaningless result on seasonal or yearly data.

7.4 Accumulation Period

This combo box, disabled unless the Time Scale is set to Monthly and the selected index is one of SPI, CZI, MCZI, or ZSI, offers moving-window accumulation lengths of 3, 6, 9, 12, 18, 24, 36, or 48 months. Selecting one of these computes the index over a rolling multi-month accumulation of the underlying variable rather than a single month at a time: the standard technique for examining drought at progressively longer timescales (a 3-month SPI reflects short-term agricultural conditions, a 24- or 36-month SPI reflects longer hydrological drought). SWSI, SMDI, SPEI, and ARI also make use of this moving-window mechanism internally when Monthly is selected, even though the combo box itself is only exposed for the four indices listed above.

7.5 Calculate, and the other action buttons

Calculate runs the selected index for every defined station over the selected Year Range. If the current index requires two variables whose overlap the selected range exceeds, a confirmation dialog offers to narrow the range automatically before proceeding. While running, the button set switches state: Calculate disables and Cancel (which stops the in-progress run) becomes available. On completion a confirmation dialog reads "Index Calculated.", followed by a second warning dialog if the calculation produced any caveats worth flagging (for instance, a station skipped for missing data). Any station-specific configuration error (for example an index with no valid data type resolvable from the current UI state) is reported by name rather than failing silently.

The remaining buttons in this row are launch points for the rest of this tutorial and are covered in their own chapters: Wavelet opens the Wavelet Analysis window (Chapter 9) using the just-computed result; To Table simply selects the first station in the Results panel's Station drop-down, which is a convenience shortcut rather than a separate feature; Add Average computes an averaged "virtual station" across every station currently in the network (averaging latitude, longitude, and the soil parameters, and averaging each loaded climate variable point-by-point) and, after a short confirmation dialog, adds it to the station list as a new row; Trend opens the Trend Analysis window (Chapter 8); Multi-Scale opens the Multi-Scale SPI/SPEI Heatmap window (Chapter 13).

7.6 Results panel

Station selects which station's results are displayed in the table beneath it; choosing a station (or, after a calculation, the first station being auto-selected) populates a DataGrid whose row headers are years and whose columns adapt to the index's time scale: a single "Yearly" column for yearly-resolution results, four seasonal columns (Winter/Spring/Summer/Fall, or the SDI-specific Oct-Dec/Oct-Mar/Oct-Jun/Yearly set) for four-period results, twelve month-abbreviation columns for monthly results, and numbered Day/Week/Period columns for finer resolutions. Export saves the currently displayed station's table to an Excel, legacy Excel, or plain-text file, with a confirmation message on success.

Threshold panel

Threshold is a numeric field (paired internally with a scroll control) defining the index value that separates "in drought" from "not in drought" for the purposes of event extraction; it defaults to 0 in the interface but the field is otherwise free-text, and an unparsable entry silently falls back to -1.0 with no warning shown, so it is worth confirming the value actually took effect before relying on it. Above / Below chooses whether values above or below the threshold count as drought conditions. Below is selected by default, matching the usual convention that low index values indicate drought.

Analyze opens the Drought Events window (Chapter 10), passing it the selected station's complete computed series, the threshold, and the above/below direction. The From/To year combo boxes that visually sit alongside the threshold controls are not actually connected to anything in the underlying logic. Changing them has no effect on Analyze, which always passes the entire computed record rather than a sub-range. If a shorter analysis window is needed, narrow the Year Range in the main settings bar and recompute before analyzing.

7.7 Chart panel

Year Range narrows the plotted span independently of what was used for calculation. Filter by station, unchecked by default, enables a per-station checklist combo box so a subset of stations can be plotted together rather than every station at once. Style options: Zero Line (checked by default) draws a horizontal reference line at zero; a color picker sets the plotted series color (used only for the Box chart type); Title is a free-text field for the chart's title, defaulting to the literal placeholder text "Title" until changed.

Chart Type offers Box (default), Line, or Bar; the color picker applies only to Box mode and is disabled automatically when Line or Bar is selected instead. Plot draws the chart using the currently selected stations, year range, and style options; at least one station must be selected in the per-station checklist if Filter by station is enabled, and the end year must be later than the start year, or the button reports the specific validation problem instead of drawing an empty chart.

A second button sits directly beside Plot and saves the chart just drawn to an image file (bmp, jpg, jpeg, png, or tiff) via a standard save dialog. This is the same save-to-image function documented as "Plot2Pic" in earlier versions of this tutorial; it has been moved from the main toolbar to sit next to Plot, since it only ever applies to this chart.

8. The Trend Analysis Window

Opened by the Trend button on the Drought Indices tab once at least one index has been calculated. This window is not modal: it can stay open alongside the main window and alongside other analysis windows. It also runs automatically the moment it opens, computing an initial result before any button is clicked.

8.1 Settings

Trend Method offers five options: Mann-Kendall + Sen's Slope (selected by default), Modified Mann-Kendall (Hamed-Rao), Spearman's Rho, Linear Regression, and Innovative Trend Analysis (ITA). Station selects which station's computed series to analyze. Significance Level offers 0.05 (default), 0.01, or 0.10 as the alpha threshold used to classify a trend as significant. Run Analysis re-executes the analysis on demand, though changing the Trend Method or Station combo boxes also triggers a fresh run automatically.

Show trend line on plot, checked by default, controls only whether the fitted trend (or, for ITA, the 1:1 no-trend reference line) is drawn on the chart; it does not affect the numeric results table.

8.2 Results table

The columns displayed change completely depending on the selected method, since each test produces different statistics:

Because the table has more columns than fit on screen at once for every method, a horizontal scrollbar beneath the grid reaches the remaining columns. Any row classified as statistically significant is highlighted with a light green background so significant stations stand out immediately in a multi-station analysis.

8.3 Chart

For every method except ITA, the chart plots the raw flattened index series as a line against calendar year, with a dashed red trend line overlaid (using the Linear Regression slope and intercept if that method is active, or the Sen's Slope estimate otherwise) and a gray dashed zero-reference line. For ITA specifically, the chart instead plots a scatter of the sorted first half of the record against the sorted second half, with a red 1:1 reference line, the correct way to read an ITA plot, since points that fall above the reference line indicate an increasing trend at that portion of the distribution and points below indicate a decreasing trend, rather than reading it as a conventional time series.

8.4 Export to Excel

Produces a three-sheet workbook: Chart Data (year, index value, and trend-line value per point), Statistics (the currently displayed results table plus footer rows recording which station, which trend-line equation, and which start year were used), and Chart (a native Excel chart reproducing the on-screen plot). If no analysis has been run yet, the button reports "No data to export. Run analysis first." instead of producing an empty file.

9. The Wavelet Analysis Window

Opened by the Wavelet button on the Drought Indices tab. Unlike Trend Analysis, this window always opens maximized to full screen, reflecting how much screen space its three simultaneous plots need. Like Trend Analysis, it runs an initial analysis automatically as soon as it opens, for the first station in the list.

9.1 Settings

Station selects the series to analyze. Significance offers 95% (default), 99%, 90%, or None; selecting None disables significance testing entirely, which removes both the threshold line from the Global Spectrum plot and any dominant-period detection, since dominant periods are only ever identified relative to a significance threshold. Morlet ω0 sets the characteristic parameter of the Morlet mother wavelet used for the transform, offering 6 (the conventional default), 8, or 10. A higher ω0 trades time resolution for better frequency resolution. Run Analysis re-executes the transform for the current settings.

The status line above the plots reports, in the exact form shown in the screenshot, the station name, the total number of time steps analyzed, the number of scales computed, and the count of dominant periods found, a dominant period being a local maximum in the Global Wavelet Spectrum that also exceeds the chosen significance threshold at that period.

9.2 The three plots

Wavelet Power Spectrum (Scalogram), a heat map of wavelet power across time (horizontal axis) and period in years (vertical axis, log-scaled), using a rainbow color scale from dark blue (low power) through yellow and orange to dark red (high power). A white dashed curve marks the Cone of Influence, the boundary beyond which edge effects make the transform unreliable. Power values outside this curve should be interpreted cautiously. When significance testing is enabled, horizontal dotted lines mark each dominant period, labeled with its exact value in years ("11.0191 yr" in the screenshot).

Global Wavelet Spectrum, the time-averaged wavelet power at each period, plotted as power (horizontal axis) against period in years (vertical axis, matching the scalogram's period axis so the two plots can be read side by side). A dashed red line marks the significance threshold; any point on the blue Global Power curve that crosses to the right of this line at a local maximum is one of the dominant periods reported in the status line.

Index Time Series, simply the raw flattened index values plotted against date, provided for reference alongside the spectral plots above.

9.3 Export options

Export to Excel produces a five-sheet workbook (Global Spectrum, Dominant Periods with a plain-language interpretation of each period's likely physical meaning, for example a period of 2 to 7 years is labeled "ENSO band", one of 12 to 22 years "Solar cycle / AMO", Power Matrix, Time Series, and an Info sheet naming the mother wavelet, ω0, significance level, and the Torrence & Compo 1998 citation for the method). Export Charts (PNG) saves the Scalogram and Global Spectrum plots as two separate high-resolution PNG files (the Index Time Series plot is not included in this export); it is not wrapped in the same error handling as the Excel export, so if the target file is open in another program the export can fail without a graceful message.

9.4 Teleconnection Analysis button

This button is the entry point into the Teleconnection window (Chapter 12) and requires an extra step the button itself does not perform automatically: DMAP does not ship with any built-in climate-oscillation dataset, so clicking it opens a file picker asking you to supply your own CSV file of a monthly climate index, for example a monthly Oceanic Nino Index (ONI), Pacific Decadal Oscillation (PDO), or North Atlantic Oscillation (NAO) series obtained from a national climate center, with two columns, Date and Value.

If the supplied file turns out to be coarser than monthly, a dialog offers to expand it to monthly by repeating each value across the calendar months it covers, explicitly labeling this as an approximation rather than genuine monthly data; declining cancels the analysis so a proper monthly file can be chosen instead. Once a usable climate series is loaded, the Teleconnection window opens automatically, comparing it against whichever station's wavelet series was active in this window at the time.

10. The Drought Events Window

Opened by the Analyze button in the Threshold panel of the Drought Indices tab. This window applies run theory to the selected station's full computed series: it walks the series period by period and extracts every maximal run of consecutive periods that cross the chosen threshold in the chosen direction (above or below) as one discrete drought event, then tabulates and charts each event.

10.1 Drought Events table

Five columns: Event #, Start Date, Duration, Severity, and Peak. The Duration column's header and the units used throughout the window adapt automatically to the time scale of the underlying index: years, seasons, months (as in the screenshot, where a monthly SPI series produces durations such as 0.82 months), weeks, 8-day periods, or days. Severity is the sum of the absolute departure from the threshold across every period in the event; Peak is the single most extreme departure reached during the event. Both are expressed in the index's own units, not a separate standardized severity scale.

Exactly where an event is judged to start and end is refined by linear interpolation between the last non-drought value and the first drought value (and symmetrically at the end of the event), rather than being pinned to the coarse grid of the underlying time step. This is why Event 1 in the screenshot starts on "1996-01-27" even though the underlying data is monthly.

10.2 Drought Event Chart

The full index series is plotted as a line, with a red dashed horizontal line marking the threshold and its numeric value. Every detected event is shaded (a semi-transparent tan fill between the series and the threshold line) and labeled directly on the chart with its severity value, exactly as visible in the screenshot's cluster of "Sev:" labels along the lower portion of the plot. A drought spell still in progress at the very end of the record is still closed off and counted as a completed event using the last available date.

10.3 Tools panel

11. The Severity-Duration-Frequency (SDF) Window

Opened by Frequency Analysis (SDF) from the Drought Events window. This window fits a joint statistical model to the duration and severity of the events just detected, allowing drought severity to be expressed as a function of return period (how rare an event of a given severity and duration is expected to be) rather than only as a historical record of what has already happened.

11.1 Summary line

A single status line reports N events, Record length in years, Mean events per year, Kendall's tau (the rank correlation between event duration and severity, used to fit the dependence structure below), and Gumbel theta (the fitted copula parameter derived directly from Kendall's tau, capped at a maximum of 20).

11.2 Statistical method

Duration and severity are each fitted independently to a Gamma distribution using the method of moments. Their joint dependence (the fact that longer droughts also tend to be more severe, reflected in the positive Kendall's tau) is captured with a Gumbel-Hougaard copula, whose single parameter (theta) is derived directly from Kendall's tau. From this fitted joint model, both a joint-AND return period (both duration and severity equalled or exceeded together) and a joint-OR return period (either one equalled or exceeded) can be computed for any combination of the two variables.

At least 5 events with genuine spread in both duration and severity are required for the fit to proceed; a record with too few events, or with essentially no variation in duration or severity, produces an explicit warning rather than an unreliable fit.

11.3 Severity-Duration-Frequency table and curves

Representative durations are chosen as the 25th, 50th, 75th, and 90th percentiles of the observed event durations (four values in the typical case, fewer if percentiles happen to coincide). For each representative duration, the table lists the fitted severity value corresponding to six standard return periods (2, 5, 10, 25, 50, and 100 years), solved numerically from the copula model. The SDF Curves chart plots these same relationships as one line per representative duration, with return period on a logarithmic horizontal axis and severity on the vertical axis, letting the shape of the severity-frequency relationship be compared visually across different event durations.

11.4 Historical Events: Joint (Copula) Return Periods

A separate table lists every actually observed historical event with its own fitted joint-AND and joint-OR return period, computed by plugging that event's specific duration and severity into the fitted copula model and sorted with the rarest (largest return period) events first. This table answers a different question from the curves above: rather than "how severe is a 25-year event of this duration," it answers "how rare was this specific historical event, jointly considering both how long it lasted and how severe it was." A dash is shown in either return-period column when the underlying calculation is undefined (the event falls so close to the center of the joint distribution that no finite return period is meaningful).

11.5 Export to Excel

Produces a three-sheet workbook: SDF Curve (the raw numeric duration/return-period/severity table), Historical Joint Return Periods (adding the marginal and joint cumulative-probability values that underlie the on-screen return periods but are not displayed directly in the window itself), and an Info sheet naming the fitting method ("Gamma marginals (method of moments) + Gumbel-Hougaard copula") and the Shiau (2006) citation for the technique.

12. The Teleconnection Window

Opened only from the Teleconnection Analysis button in the Wavelet Analysis window (Section 9.4), after supplying a monthly climate-index CSV file. It measures how strongly a drought index correlates with a large-scale climate oscillation such as ENSO, the PDO, or the NAO, and at what lead or lag.

12.1 Settings

Correlation Method offers Pearson (default) or Spearman; this choice only determines which coefficient is treated as "active" for the highlighted line on the chart and the confidence flag in the table. Both Pearson and Spearman values are always computed and always shown regardless of which is selected. Significance Level offers 90%, 95% (default), or 99% confidence.

There is no dropdown of built-in climate indices in this window: the drought index is whatever was active in the Wavelet Analysis window when Teleconnection Analysis was clicked, and the climate index is entirely defined by whatever CSV file was picked at that time. If the loaded drought index is coarser than monthly (seasonal or yearly, for example), a warning banner appears explaining that each drought data point is being matched only to that one calendar month's climate value, so the resulting lag correlations reflect a narrower relationship than a true month-to-month comparison would.

12.2 Lag correlation computation

Correlation is computed across a fixed window of -12 to +12 months (this range is not adjustable in the interface). The sign convention is stated directly in the window: a positive lag means the climate index leads the drought index by that many months, a negative lag means the drought index leads the climate index. Each lag requires at least 8 matched monthly pairs to produce a result; lags with fewer valid pairs show a dash rather than a number.

The summary line above the table and chart reports the overall strongest correlation found, the lag at which it occurs, and a plain-language description of which series leads (for example "ClimateIndexName leads by N mo", "DroughtIndexName leads by N mo", or "no lag (simultaneous)" when the strongest correlation occurs exactly at zero lag).

12.3 Table and chart

The Lag Correlation Table lists, for every lag from -12 to +12 months: the lag itself, Pearson r, Spearman rho, the number of valid pairs used, a p-value (labeled for whichever method is active), and a Significant column reflecting the chosen confidence level. The chart plots both correlation measures across the same lag range, with the currently active method drawn bolder and the inactive one drawn thinner, a dotted confidence-interval band, and a vertical dotted line marking zero lag for reference.

12.4 Export to Excel

Produces a two-sheet workbook: Lag Correlation (every lag's Pearson and Spearman coefficients, p-values, pair counts, and significance flag) and an Info sheet naming both index series, the active method and confidence level, the best lag found, and the sign convention used throughout ("Positive lag = climate index leads the drought index by that many months.").

13. The Multi-Scale SPI/SPEI Heatmap Window

Opened by the Multi-Scale button on the Drought Indices tab, provided rainfall has been loaded. Rather than committing to a single accumulation period as the Accumulation Period control on the main tab does, this window computes SPI or SPEI simultaneously at several accumulation scales and displays them all at once as a heatmap, making it easy to see at a glance whether a given period was dry only briefly or across every timescale examined.

13.1 Settings

Index offers SPI (default) or SPEI only. No other index in the application supports this multi-scale view. Scales (comma-separated) accepts a free-text list of integer month-lengths, defaulting to "1,3,6,9,12,24"; every value must be a whole number between 1 and 48, and an invalid entry (a non-numeric token, a decimal, or a value outside that range) produces the message "Scales must be comma-separated integers between 1 and 48." rather than attempting to plot a malformed request. Duplicate scale values are not removed automatically: entering "1,1,3" computes the 1-month scale twice as two separate heatmap rows. Station selects which station's rainfall (and, for SPEI, PET) series to use.

Generate computes every requested scale and builds the heatmap; if SPEI is selected but no PET or AET data has been loaded for the chosen station, the button reports "SPEI requires ET data. Load PET or AET first." instead of proceeding.

13.2 Reading the heatmap

The vertical axis is accumulation scale in months (matching the values entered in Scales), the horizontal axis is time, and cell color follows a standard SPI/SPEI color ramp from deep red (severe drought, roughly -3) through white/yellow (near normal) to deep green (severe wet, roughly +3). The gray wedge visible along the left edge of the plot is not missing or bad data: it is a genuine artifact of the accumulation calculation itself. A 24-month accumulation, for instance, needs 24 months of prior rainfall before it can produce its first value, so the first 23 time steps of that scale's row are undefined, while a 1-month scale needs no run-in at all. Because larger scales need a longer run-in than smaller ones, stacking every scale's row together produces a wedge that narrows as scale decreases, exactly as shown in the screenshot.

13.3 Export options

Export Plot is the only export button in the entire application that offers a choice of PNG, SVG, or PDF output (every other plot-export button in DMAP produces PNG only), using a standard Windows file-type filter to select the format. Export to Excel produces a three-sheet workbook: Multi-Scale Data (one row per scale, one column per time step, with cell shading reproducing the on-screen heatmap's red-white-blue color scale so the exported table remains visually readable), Chart (one line series per scale), and Statistics (per-scale minimum, maximum, mean, standard deviation, count of "drought months" defined simply as any value below -1.0, and the percentage of the record those months represent).

14. The View and Export Data Window

Opened by the Export All Data button in the main toolbar (present on every tab, not gated by registration). Its window title is literally "View and Export Data": this is the general-purpose utility for inspecting, charting, and exporting every variable currently held in memory, independent of whichever specific index or workflow the Drought Indices tab is focused on.

14.1 Variables panel

A scrollable list of every variable DMAP recognizes (Tmax, Tmin, T-Average, Rainfall, Stream Flow, Soil Moisture, PET (ETo), AET, NDVI, LST, and the five reflectance bands), each with two independent selectors, exactly as the group box header explains: a radio button (filled circle = preview, only one variable can be previewed at a time) and a checkbox (checked box = export, any number of variables can be checked for export simultaneously). A variable with nothing loaded for it is greyed out and its tooltip reads "{name} - not loaded"; a variable that is loaded shows how many stations have data for it, and for PET specifically, which calculation method produced it if it was computed rather than imported or downloaded.

14.2 Station and Time Range

All stations (default) previews and exports every station at once; Selected station narrows either operation to one specific station chosen from the adjacent combo box. From year and To year default to the loaded record's actual span (or 1950-2020 as a fallback if that cannot be determined) and are validated as plain integers with From no greater than To.

14.3 Data Preview and actions

Preview builds a table for whichever variable's radio button is selected, sliced to the chosen year range, with column headers that adapt to the variable's native resolution exactly as on the Drought Indices tab's Results grid (twelve month columns for monthly data, and so on). The status line above the grid reports precisely what is being shown, in the form visible in the screenshot: "Previewing: Rainfall [Downloaded] | showing station 1 of 1 | 1996-2019 | 12 periods/year."

View Chart opens the same VariableChartWindow for whichever variable is currently selected for preview, not for export, plotting it as a single-station, single-variable time series with its own Time Scale combo box for re-aggregating the plot on the fly (for example collapsing daily data to monthly or yearly without altering the underlying loaded data). Whether the chart sums or averages when coarsening the time scale depends on the nature of the variable: accumulative quantities such as Rainfall, Stream Flow, PET, and AET are summed, while state quantities are averaged.

Export Selected exports every variable whose checkbox is currently ticked; Export All is a convenience shortcut that ticks every available checkbox first and then runs the same export. Both accept Excel, CSV, or plain-text output; exporting more than one variable to Excel produces a single workbook with one sheet per variable (sheet names truncated to Excel's 31-character limit), while a single-variable export or any CSV/text export produces one flat file. A confirmation dialog on success names exactly how many variables were written and to what path; exporting with nothing loaded, or with the year range containing no data, reports the specific reason instead of producing an empty file silently.

15. Remaining Utility Windows

A handful of smaller windows round out the application. None of them have their own screenshot in this tutorial since they are simple, single-purpose dialogs, but each is described here for completeness since the original request covers every functional component of the application.

15.1 Add Average dialog

Triggered by the Add Average button on the Drought Indices tab (Section 7.5). Before this dialog even opens, DMAP has already computed the mean latitude, longitude, Available Water Capacity, Field Capacity, and Surface Soil value across every existing station, along with a point-by-point average of every currently loaded climate variable. The dialog itself displays a message summarizing exactly which variables were averaged and what the computed mean station-metadata values are, then presents those same values in editable fields (Latitude/Longitude, AWC/Surface Soil, Field Capacity/Name; the name field defaults to the literal text "Average") in case any of them should be adjusted before the new station is actually added. Yes commits the new averaged station to the station list; Cancel discards it without adding anything.

15.2 The NetCDF "View Data" popup

A separate, much simpler window from the View and Export Data window in Chapter 14, opened specifically by the View Data button on the Data tab's NetCDF sub-tab (Section 5.2). It shows a single flat, read-only grid (one Date column followed by one column per station) of whatever was most recently extracted from a NetCDF file, with no filtering, charting, editing, or export controls of its own beyond a single Close button. Any editing capability the grid might appear to offer is discarded when the window closes; nothing typed into it is saved back to the loaded data.

15.3 Converter

A small legacy unit-conversion picker (No Converting / Fahrenheit to Centigrade / Kelvin to Centigrade / Flux to mm/day) reached only from within the NetCDF database-viewer window, not from the main Data tab flow described in Chapter 5. In current everyday use, the NetCDF sub-tab's own Unit Converter panel (Section 5.3) is the supported route for converting gridded data units.

15.4 About Us and Register

Both covered in full in Chapter 2. They are listed again here only to confirm they are reachable from every tab via the fixed toolbar, not just from the Stations tab where the earlier screenshots happen to show the toolbar.

16. Summary Workflow

Put together, a complete first session in DMAP V2.1 follows this order: add one or more stations on the Stations tab, including their latitude, longitude, and (if agricultural indices will be used) Field Capacity, Surface Soil, and Available Water Capacity; load or download the climate variables those indices require, using whichever of the Excel, NetCDF, or Download sub-tabs matches the data source at hand; on the Drought Indices tab, set the Year Range and Time Scale, select an index (using the prerequisite table in Section 7.3 to understand why an index might still be greyed out), and click Calculate; inspect the results in the Results table and Chart panel, or hand the computed series off to Trend, Wavelet, Multi-Scale, or (via the Threshold panel's Analyze button) Drought Event and Frequency analysis; and finally use Export All Data at any point to pull any loaded or computed variable out to Excel, CSV, or text for use outside the application.

Because every drought index in DMAP is computed per station, adding more stations to the network at any time (including after data has already been loaded for existing stations) does not disturb previously computed results; it simply means the newly added station will need its own data loaded before it, too, can be included in a calculation.

Open PDF Download PDF Formulas → Back to DMAP