Calibration and contributions¶
The Calibration page is where you choose part of a model to calibrate on your computer. The Contribute pages are where you send the result, or observations and weather data, back for review.
Calibration workflow¶
- On the Calibration page, define a slice: an outlet channel and, optionally, inlet channels upstream of it.
- Prepare the slice for download and download it.
- Calibrate the slice on your computer.
- Submit your calibration.cal, with any management files, as a contribution. You can have the server run the slice with it and compare the scores (see Server runs of a slice).
- The platform checks the files and reviewers decide on the contribution. An approved calibration is used in evaluation runs, and in the model runs once the calibration lead switches that on (see Statuses).
Calibration page¶
The page shows a map of the current model version, CoSWATv2.0.0, with the regions that have results for the live period. The left panel has three groups:
| Group | Contents |
|---|---|
| Calibration | The Model, and three tabs for choosing a region: Global, Continent and Region. |
| Map layers | Region boundaries, Subregions, LSU outlines, Channel network, Gauges, Country borders and Basemap. LSU outlines appear when you zoom in. |
| Selection tools | Choose outlet, Add inlet and Clear selection. |
The Calibration page uses the flat map only. It starts with a plain light background and dashed grey country borders, which become more detailed as you zoom in. Turn on Basemap to show OpenStreetMap underneath, or turn off Country borders to hide them. Both choices are remembered in your browser for the next visit. They are also kept in the page address when they differ from the start, so a shared link opens with the same choice.
Choosing a region¶
- Global shows the whole world with the outlines of every region that has results for the live period. Hovering over an outline shows the region's name; clicking it opens the region.
- Continent: choose a continent. The map zooms to its regions and shows only their outlines. Choose a region from the list below the menu or click its outline.
- Region: type in Find a modelled region. Up to eight matching regions are listed with their continent; arrow keys and Enter choose one.
Opening a region, from any of the three tabs, switches to the Region tab. The map zooms to the region and draws its boundaries, subregions and channel network; LSU outlines appear when you zoom in. You can then define a slice.
Switching back to Global or Continent clears the region and any outlet and inlets. Returning to Region reopens the last region, without the selection.
The page address records the tab, the region and the slice, so a link or a reload opens the same view with the same outlet and inlets. On a phone, Your slice covers the bottom of the map, and the map leaves room for it.
Slices¶
A slice is the part of one model that drains to an outlet channel, minus everything that drains in through its inlet channels. Calibrating a slice instead of a whole model keeps the download small and the runs short.
A slice always stays within one model. Where water from an upstream subregion enters the slice, it arrives through recall, as it does in full model runs.
Defining a slice¶
- Select Choose outlet and click a channel. It becomes the outlet.
- The tool switches to Add inlet. Each channel you click upstream of the outlet becomes an inlet, labelled on the map (for example Inlet 1 · 87). Click an inlet again to remove it.
- The slice is shaded on the map, and the area above the inlets is hatched.
An inlet is refused, with a message, when it:
- is not upstream of the outlet;
- is upstream of an inlet you already chose;
- is downstream of an inlet you already chose (remove that inlet first);
- is in another model ("A slice stays within one model").
Clear selection starts again.
Your slice¶
The right pane, Your slice, summarises the selection:
| Item | Meaning |
|---|---|
| Model | The model version. |
| Region · subregion | The model the slice belongs to. |
| Outlet, Inlets | The channels you chose. |
| Objects in slice | The number of HRUs, LSUs and channels in the slice. |
| Model performance | How well the model fits observed flow at the gauges; see Model performance. |
| Area | The area that drains to the outlet, minus the area above the inlets. |
| Run period | The years the slice will simulate, for example 1980 – 1986 (warm-up 2). The line below it gives the simulated years, the warm-up years and the years with maps. |
When water from an upstream subregion enters inside the slice, a note names the channel where it arrives by recall.
Model performance¶
Once a region is open, Model performance shows how well the current model fits observed river flow at its gauging stations, with the same scores as Explore (see Evaluation).
- With no slice, it gives the number of the region's gauges scored for the live period, and the median NSE, KGE and PBIAS over them.
- With a slice, it gives the same for the gauges in the slice, and a table of those gauges with their name and river, NSE, KGE (with a colour dot) and PBIAS. A gauge without scores shows "–"; hovering over its row gives the reason, for example too few months (a gauge needs 24).
A gauge counts as in the slice when it is matched to a channel the slice keeps. Gauges above an inlet or in other subregions are not counted.
On the map, the Gauges switch in Map layers (on by default) shows the gauges coloured by KGE, in the same colours as Explore. With a slice, gauges outside it turn grey and smaller. Hovering over a gauge shows its name, river and KGE. Observed flow series are not shown on this page.
Preparing a download¶
Preparing a slice needs an account. When you are signed out, the button reads Sign in to prepare a download.
Signed in, select Prepare slice download. The slice is checked against the model's routing, saved with a permanent code (such as SLICE-0001) and queued for preparation. Its page then opens. The Download card shows the state of the preparation:
| State | The card shows |
|---|---|
| Queued | "Queued. Waiting for the run worker." |
| Preparing | The current step and percentage, for example "Step: extract, 5%". The steps are plan, extract, check and zip. |
| Ready | The time the download is available until, in UTC, and the button Download SLICE-0001.zip, with the file size. |
| Failed | "Failed." with the reason. |
| Expired | "Expired. The download has been removed; you can prepare it again." |
The page checks the state every 10 seconds and updates itself, so it does not need refreshing. Nothing is sent when the download is ready: keep the page open, or come back to it from Your slices.
Only the person who prepared a slice can download it. The download is removed 3 hours after it is ready, or 1 hour after the first download, whichever comes first; the "available until" time moves earlier after the first download.
Prepare again on the slice's page starts a new preparation when the last one failed or expired. When a slice has been prepared more than once, Earlier preparations lists each one with its date, state and years.
If the run period a slice was defined with has since been deleted, the slice is prepared with the default run period, and its years are shown with "period deleted" beside them. If the slice's years are outside the live period, its page says so.
Your slices lists every slice you defined, with its outlet, inlets, run period and download state.
Contents of the download¶
The download is a ZIP file containing a SWAT+ model of the slice's area. For a slice of the Save (subregion 02-middle-save, outlet channel 82, inlet channel 67, run period 1980 to 1986), preparation took under two minutes and the ZIP was 3.2 MB, about 10 MB unpacked.
| File or folder | Contents |
|---|---|
| README.md | What the slice is, its object counts, its inlets, the result of the check, and how to calibrate it. |
| slice.json | The slice's permanent definition: model, region and subregion, outlet and inlets, objects, area, run period, the SWAT+ build it was checked with, and who prepared it and when. |
| check.json | The result of the check run (see below). |
| mapping.json | For every object in the slice, its number in the slice, its number in the full model, its GIS number and its name. |
| txtinout/ | The SWAT+ input files of the slice. |
The objects of the slice (HRUs, routing units, aquifers, channels) are renumbered from 1, in the order of the full model. The connection files and the tables indexed by those objects contain only the slice's objects; the model's shared tables (soils, land use, plants and the rest) are included whole.
Each inlet becomes a recall object. Its file (for example inlet_67.rec) contains the daily flow and loads that left that channel in a run of the full model over the whole run period, including the warm-up years, and it enters the slice where the inlet channel flowed into it.
The weather file is cut to the cells of the weather stations the slice uses and to the years of the run period, so the weather is the same as in the full model (3.5 MB instead of 109 MB for the example). time.sim gives the run period, and object.prt asks for the daily flow at the slice's outlet.
Check¶
Before a slice is offered for download, it is run with the same SWAT+ build as the full model, and its daily flow at the outlet is compared with the full model's over the map years. For the example slice, the two agreed to within a relative difference of 0.00006% over 1,826 days. check.json gives the figures.
Calibrating a slice¶
The slice runs with the SWAT+ build CoSWAT uses, SWAT+ rev 62.0.1 with NetCDF weather input; README.md names the build. The build is available on request from the CoSWAT team. Run the model from inside txtinout/. For a calibration, write a calibration.cal file in txtinout/ using the slice's object numbers, and name it on the chg line of file.cio. Channel rows (object type rte, for example chk) name a channel by its row number in chandeg.con, which is different from the channel number shown on the map; mapping.json gives both. When you contribute it for the slice, the numbers are translated to the full model through mapping.json. Parameters of tables that apply to the whole model are not taken from a slice.
Contributions¶
Contributions are sent from the Contribute pages, which are open to accounts with the Contributor role. The pages have three tabs: Submit a contribution, My submissions and Request a region.
Contribution types¶
| Type | Files |
|---|---|
| Calibration | calibration.cal, with any .mgt, management.sch and .dtl files and an optional readme, as separate files. A ZIP is not accepted for calibrations. Files other than calibration.cal must match a file of the chosen subregion's model. The management files are kept with the contribution but are not applied to the model. |
| Observations | A CSV file, loose or in a ZIP, with a readme. |
| Weather | Weather data with a readme. A ZIP is accepted. |
Observations format¶
An observations CSV has one row per value, with these columns:
| Column | Content |
|---|---|
| station_id | The station's identifier. |
| station_name | The station's name. |
| lon, lat | The station's location in decimal degrees. |
| date | YYYY-MM-DD for daily values, or YYYY-MM for monthly values. |
| value | The observed value. |
| units | The units of the value. |
| river | Optional: the river name. |
| area_km2 | Optional: the upstream catchment area in km². |
The form links a template file. The automatic checks validate the format.
Submitting¶
Under Submit a contribution, fill in:
- Contribution type: Calibration, Observations or Weather.
- Model version: the current version, which cannot be changed.
- Region, and Subregion for regions that have them. A subregion is required for calibrations.
- Title and Summary.
- Files: select Choose files. Files can be removed from the list before submitting.
- Supporting notes.
- I have permission to share these files. This is required.
- List my name as a contributor on coswat.com, if you want your name shown. Approved contributors who tick this box appear under Recent contributors on the Calibration page.
Then select Submit contribution. The automatic checks run at once, and the submission's page opens.
Contributing from the Calibration page¶
Signed in, you can also contribute from the Calibration page: Contribute a calibration, at the bottom of the right pane next to Your slices, opens a window. Under Apply to, choose:
- Prepared slice: one of your slices that has been prepared. The window lists only prepared slices. Object numbers in the calibration file are the slice's numbers, and they are translated to the full model through the slice's mapping.
- Whole model (name objects): the calibration applies to the full model, to the objects you name (for example
hru:12orsdc:87).
Then add the Calibration file (required), any Additional files, and Notes if you want, tick the permission boxes as on the Contribute pages, and select Submit for review. The contribution then goes through the same checks and review as one sent from the Contribute pages.
Statuses¶
| Status | Meaning |
|---|---|
| Checking | The automatic checks are running. This takes a moment, after submitting and after sending corrected files. |
| New | Waiting for review by the CoSWAT team. |
| Needs changes | The reviewers asked for changes. Select Respond, then Send corrected files; the checks run again and the status returns to New. |
| Approved | The contribution was accepted. An approved calibration "is kept for evaluation runs and applied to production runs once the calibration lead switches it on." Once that is on, every model run applies the approved calibrations and records which ones it applied. |
| Rejected | The contribution was not accepted. |
The submission's page shows its details, the submitted files, the result of each automatic check (with the reason when one fails), and Comments and activity, where you can add a comment.
My submissions lists your contributions, with a search and filters for state, region and type. The list refreshes every 30 seconds.
Overlapping calibrations¶
When an approved calibration sets a parameter on an object that an earlier contribution also set, the overlap is recorded. It does not delay the approval. The CoSWAT team can then run an evaluation over the live period that compares the calibrations in force with each overlapping one (and with any changes to model-wide parameters). The recommended version is the one with the higher median KGE, provided it makes no more gauges worse than better (see Comparing runs), and the reviewer makes the decision.
Server runs of a slice¶
The owner of a prepared slice can have the server run it, with the model's current parameters or with a calibration they contributed, and download the result. These runs are private: nothing is published.
Current parameters¶
On the slice's page, the card Download with the current parameters runs the slice as the model runs now: with the setup's parameters, plus the approved calibrations once the calibration lead has switched them on (see Statuses). Select Run with the current parameters. The card shows the state (Queued, then Planning, Preparing the slice, Running with the current parameters, Evaluating and Packaging). When it is ready, it shows the scores at the slice's gauges and the button Download with current parameters.
The file is named after the slice, for example SLICE-0003-current.zip. It contains:
| File or folder | Contents |
|---|---|
| txtinout/ | The slice's SWAT+ input files, ready to run. It includes calibration.cal only when approved calibrations are applied. |
| outputs/ | The outputs of the run. |
| evaluation.csv, evaluation.json | NSE, KGE and PBIAS at each gauge over the years after the warm-up; the JSON file also has the monthly observed and simulated flow. |
| README.md | What ran, whether approved calibrations were applied and which rows in what order, the scores, and checksums of the executable and the mapping. |
| mapping.json, slice.json, Shapes/, input-manifest.json | As in a slice download: the mapping, the slice's definition, its shapes and a list of its input files. |
Your calibration¶
On the page of a calibration you contributed for a slice, the card Run my slice with this calibration runs the slice twice: once with the current parameters, and once with your calibration.cal on top of them, your rows replacing the current values on the objects they name. Both runs are compared at the slice's gauges. Select Run my slice with this calibration. When it is ready, the card shows each gauge's NSE, KGE and PBIAS before and after, and the button Download calibrated slice.
If another approved calibration sets the same parameter on the same objects and the reviewers have not yet decided between them, the current parameters combine both, while this run uses your values on those objects.
The file is named after the slice and the contribution, for example SLICE-0003-CON-0001-new-calibrated.zip. It has the same layout, with your rows in txtinout/calibration.cal (in the slice's numbering), outputs/ from the calibrated run, baseline/outputs/ from the run with the current parameters, and the before and after scores in evaluation.csv, evaluation.json and the README.
You can run this before your contribution is reviewed, to test it, once its automatic checks have all passed. Until then the card says "The checks must pass before the slice can run with this calibration." A rejected contribution cannot be run: the card says that it was rejected, so the slice cannot run with its calibration. Earlier runs stay listed. For example, a test on a slice of the upper Save with a 5% decrease in curve number (cn2) moved the Rietfontein gauge from NSE 0.885 to 0.869, KGE 0.573 to 0.530 and PBIAS 42.4 to 46.7.
Keeping and limits¶
A finished run is kept for 3 hours, or 1 hour after your first download, and can then be run again. Each slice can have one open run with the current parameters, and each contribution one calibrated run; one person can have three open runs at a time. A gauge is scored only when it has at least 24 months of observations in the period.
Requesting a region¶
To ask for an area that has no model yet, use Request a region:
- Region or basin name (required);
- Why are you requesting this region? (required);
- Countries or area;
- Boundary file: GeoJSON, KML or a zipped shapefile, up to 20 MB;
- Additional information.
Then select Send request. A request moves through New, Under review, Needs info, and then Accepted or Declined.