Validate or analyse a simulation from a browser window, with no Python.
The OceanVal app lets you validate a simulation without writing any Python. Run oceanval in a terminal and a page opens in your web browser that takes you from a folder of model output to a validation report: you choose what to do, point it at your simulation, choose the observations to validate against, check the units, and watch the run. The first page offers Analyze simulations, Compare simulations and Validate simulations: Validate simulations leads to the validation choices, and Analyze looks at a simulation on its own (see below).
oceanval only runs from a conda environment that has OceanVal installed (see Installing), as it needs the R packages, cdo and nco that conda provides. In a terminal, activate that environment, then run oceanval in the directory to work in:
conda activate foo oceanval
Replace foo with the name of your own environment. If the command is not found, the environment is not active, or OceanVal is not installed in it. OceanVal and python -m oceanval do the same. Matchups, scripts and reports are written in that directory unless you choose another, so make a new directory for each simulation.
Where the matchups (and the report) are saved, and what the matchup script is called, are asked once you have chosen what to match up, checked the units, and said you are happy with the files OceanVal found: the page Where do you want the matchups to be saved?, whose button is Continue. Nothing is written in that directory before then. If the directory you choose has matchups already, from an earlier run, the page lists them, each with its variable, source and whether it is point or gridded, and asks What do you want to do with existing matchups? What you can do with each depends on what this run matches up. Use, as each is to start with, keeps it as it is, without making it again, and validates it. Replace is offered for one this run matches up, and makes it again. Ignore is offered for one this run does not match up, and leaves it out of the report; without a report, those are left as they are and not listed. Ticking an option at the top of its column chooses it for every row that has it. Nothing is removed from the directory. You must tick to confirm what is done with them before carrying on. The last page, One last thing... How would you like your validation report?, asks for the report’s options and how many cores matchup should use, which has no default. With Match up only, which builds no report, the cores are asked on the page of where the matchups are saved, whose button is then Match up. See Matchups from earlier runs.
Once you have given the directory a simulation’s output is in and how many directories down its files are (type a number, or pick 0 to 5 from the list the arrow in the box opens; if you leave it empty, OceanVal fills it in, in amber, when it recognises the folders: YYYY/MM/**.nc is 2, MM/*.nc (the months 01 to 12) is 1 and files with no subdirectories is 0, and typing a number of your own replaces it), OceanVal reads the years the output covers from the times in its files, never from their names, while you fill in the rest. It takes a few seconds however many files there are: OceanVal reads the time axis of the first and last files of each kind of output, by name and by when they were written, and of some others chosen at random as a check, and reads every file of a kind only if the check finds one out of order. Only the simulation’s main output counts: the kinds of file with at least a tenth as many files as the most numerous kind, and at least two, unless every kind is a single file. Files beside it, such as a post-processed time series or the grids an earlier validation saved, are left out. While it does, the page says Finding key information about your simulation, and Found output for the years once they are read. In the recipes window, the First and Last years to validate then have an arrow at their right-hand end that lists those years. Any year can still be typed, in case the years found are wrong; one outside them is warned about but allowed. The years are remembered in .oceanvalcache in your home directory, and read again only when the files change.
While the files are found the page says Identifying files that meet criteria. Please wait! Once you choose Match up and validate, it shows a grid with a row for each variable and data source. The Matchup column is empty until that matchup starts, has a turning circle while it is made, and a tick once it is (a cross if it could not be). Model extraction, the first column before it, shows how many of the simulation’s files that matchup has read so far, such as 37/120, and a tick once it has read them all. A dash means it read none, for example because it was kept from an earlier run. For gridded data the files are read by CDO, and OceanVal counts each one as CDO finishes with it. It checks twice a second, so a file read in less time than that may only be counted once all of them have been read. Observation extraction, the column just before Matchup, has a turning circle while the observations are read or downloaded (from a server, the data store or your own files), and a tick once they are, or a cross if the matchup could not be made while reading them. A point matchup reads its observations before the model files, a gridded matchup after them. In a narrow window both extraction columns are left out and the count appears under the Matchup circle. The Interim report column does the same as its page is added to the interim validation report, and its tick opens that page; the link to the whole interim report is at the top. The Time column counts up while a matchup is made, and keeps how long it took once it is made (or not made), and Time elapsed under the grid is how long the run has gone on for, the report included. OceanVal’s output is shown only if the run fails, with its errors. If a data server is down or overloaded (NOAA’s for WOA23, say, answering 503 Service Unavailable), a notice at the bottom of the window says so as soon as a matchup fails because of it: which server, what it answered and when, and the matchups it stopped. This is a problem at the server’s end, not with your simulation, so try those matchups again later. The notice stays until the next run, and the × hides it until there is more to say.
Analyze simulations works out the climatology, the phenology, time series and transects of a simulation’s variables, with no observations, and builds an HTML report of them, laid out like a validation report. It takes you through these pages, each with Back, which keeps what you entered:
z_level). The phenology is the day of the seasonal peak at the surface, from a daily climatology, so it is offered only for daily output. The two time series are the mean of each year, and of each month, over the model’s domain, each region you choose and each station (a name, longitude and latitude, in a table in their pop-outs; the nearest model cell is used). Once one is chosen, a card sets the regions and area they share: no regional summaries, the northwest European Shelf, global, or your own .nc file, and a lon/lat box. Map temporal changes maps how a variable changes between a historical period and one or two future periods: for each variable ticked, give the first and last years of the Historical period and of Future 1 (both required) and, if you like, Future 2, tick Surface, Bottom and/or Water column as for the climatology, and choose, in a row below, Plot (Historical + Future (absolute values), Historical + Future (absolute values) + Changes or Historical + Changes) and Change (absolute or percentage); neither is chosen to start with. Transects are the model’s values along straight lines: each variable is ticked to start with (untick those you want no transects of), and you add as many transects as you like to each, on its own. With more than one variable, each has a Copy these transects to every variable button, which gives every other variable the same transects in place of its own (a variable with no depth levels gets them without the Vertical part). A transect is a card with the longitude and latitude of its Start and End (it must run north–south, with the same longitude at both ends, or east–west, with the same latitude) in one line, and, below them, a Surface and a Vertical part, each with a Climatology (at the surface, the monthly climatology along the line; in the vertical, a section of the annual mean through the water column, which asks whether the simulation is z-level or where its cell thickness is) and its Changes, a drop-down of Absolute (the linear trend per year), Absolute change (the last year minus the first) and Percentage change, at the surface or at each depth of the section, which are not offered for a variable with only one year of output (the absolute trend needs three). Each has its own required Start year and End year, and a Use a rolling mean (years) box to the right of those of the changes, 1 to start with (none), smooths the annual means with nctoolkit’s rolling_mean before the trend is worked out. Apart from the variables’ ticks, nothing is ticked or filled in to start with, and each variable’s years of output are shown beside it as a hint. Every start and end year box also has an arrow at its right-hand end (or press the down arrow in the box) that lists all the years of that variable’s output to pick from; a year can still be typed. The Long-term time series pop-out has two more columns after Water column: Use a rolling mean (years), 1 to start with (none), which replaces each year’s annual mean by the mean of that year and the ones before it, and Show as: Absolute value (the annual means, to start with), Absolute change or Percentage change, each year’s change from the first year with a value.oceanval_analysis in the Directory you choose, replacing any analysis there. If there is one, the page says so and you must tick to replace it, and name the directory in the box rather than leave it empty (empty is the directory you started oceanval in); choose another directory to keep the analysis. Also give the name of the script the window writes, analysis.py to start with. For a comparison the folder is oceanval_simulation_comparison, and a comparison already there has to be ticked to be replaced in the same way, and the script is simulation_comparison.py.oceanval.analyze() call into a script, analysis.py unless you choose another name, runs it, and links to the report once it is built. While it runs, a grid has a row for each variable and a column for each analysis chosen for at least one of them (Climatology, Phenology, Long-term series, Seasonal cycles, Map changes, Transects): a hollow circle for what is still to do, a turning circle for what is being worked out now, a tick once it is, and a dash for an analysis that variable does not have. The Time column counts up while a variable is worked out and keeps how long it took, Time elapsed under the grid is how long the run has gone on for, and the Report column ticks as each variable’s page is added, the tick opening that page (in a narrow window the Report column is left out and the analyses’ names are turned on their side). Each variable’s page is built as soon as the variable is worked out, and the window links to this interim analysis report from the first variable on, saying how many of the variables are in it. The netCDF fields it worked out are kept beside the report, in oceanval_analysis/results. Save Python script to run later, to the right of it, writes the same script but does not run it: the window says where it is, and the command to run it in a terminal (python analysis.py), when you want to.Compare simulations does everything Analyze does for two to five simulations, and shows them side by side in one HTML report: the maps are a panel for each simulation on one colour scale, and the time series have a colour for each simulation. It takes you through these pages, each with Back:
to_latlon) or a baseline simulation, whose grid the others are regridded to with regrid. Either way, a cell with no value in any one simulation is made missing in all of them, so that every simulation is compared over exactly the same cells; the page says so.oceanval.compare_simulations() call into a script, simulation_comparison.py unless you choose another name, runs it, and links to the report once it is built, and to the interim report from the first variable on, as for an analysis. The same grid of the variables and their analyses shows how far it has got: each analysis is worked out in each simulation in turn, so between them its cell shows how many simulations have it, such as 1/3, and it is ticked once all have. Save Python script to run later writes the script without running it, as for an analysis.If oceanval cannot open a browser for you, it prints a link to open. Over SSH it never opens a browser on the remote machine, even when X11 forwarding is on (as in MobaXterm); oceanval --no-browser does the same anywhere, and OCEANVAL_BROWSER=1 opens one over SSH anyway. VS Code forwards its port for you. Over plain SSH, for example from a Windows terminal, it prints the command that forwards the port, such as ssh -L 8765:127.0.0.1:8765 you@server: run it in a new terminal on your own computer (PowerShell on Windows 10 or later has ssh), leave it open, and open the link in your browser. When it prints that command, oceanval uses port 8765 if it is free, so the command is the same every time; choose another port with --port. When it opens the browser itself, as in VS Code, it uses any free port. The printed login is a guess: use the one you normally connect with. The run carries on if you close the page, and you can come back to it with the same link.
The built-in observational datasets are downloaded every time a matchup needs them, and their servers can be slow or out of reach. To keep what is downloaded for later matchups, open Preferences (the cog beside the OceanVal name) and give a folder for the data store. The folder must already exist: OceanVal keeps everything in an oceanval_datastore folder it makes inside it, and never writes or removes anything outside that. Choose a disk with a reasonable amount of free space, as the store grows as more data is kept in it and can come to several GB. Leave the folder empty to keep nothing.
Once the folder is saved, Preferences shows where the store is, how much space is free on its disk and the size of the data store. Run a check on the data store looks for data held twice, files that are missing or not the size they were, and anything in the store that is not OceanVal’s built-in data (files of yours, for one), and says what it finds. It only looks: nothing is changed, removed or fixed.
Choose how matchups use it:
Only OceanVal’s own datasets are kept (WOA23, OC-CCI, NSBC, COBE2, GLODAP and ICES), never data of yours. What OceanVal downloads is the area and years a matchup needs, so the store keeps track of them: gridded data is kept for the model’s area, rounded out to whole degrees (or the whole globe, for a model covering 90% of it), and ICES data a year at a time for the area asked for. A later matchup whose area and years are inside what is kept takes it from the store; a wider area is downloaded again, and replaces what was kept with data covering both. Something downloaded earlier in the same run is never downloaded again, so the ICES bottle data every ICES nutrient comes from is downloaded once. What is kept is used however old it is, and the run says when it was downloaded; this year’s COBE2 data, still being added to, is not kept. The setting is used by every matchup, including those run from Python; oceanval.matchup(..., data_store=False) leaves it out for one run.
The window does nothing you could not do in Python. It writes the matchup script first, to matchup.py unless you choose another name, and then runs it. The script holds your own data, every recipe (those you did not tick are commented out), the conversions, the oceanval.matchup() call and, for a matchup and validate run, the oceanval.validate() call, so you can read it, edit it and run it again later with python matchup.py.