PlymouthMarineLaboratory/OceanVal: v0.7.0

OceanVal 0.6.0 introduces the OceanVal app: 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, with no Python to write. It checks your units, shows you how OceanVal reads your files, builds an interim report while the matchups are made, and keeps your own observations as recipes you can use again. New features The oceanval command Activate a conda environment that has OceanVal installed, then run oceanval (or OceanVal, or python -m oceanval) in the directory you want to work in: conda activate foo oceanval Replace foo with the name of your own environment. Matchups, scripts and reports are written in that directory unless you choose another, so use a new directory for each simulation. The page is served only on your own computer (127.0.0.1) and only to your browser, and loads nothing from elsewhere. The first page offers four choices: match up new data and validate it, match up only, validate matchups made earlier, or compare existing validations. Every step after it has Back, which keeps what you entered. You can get as far as the report's options, spot a mistake, go back to the simulation to fix it and carry on with everything else as you left it. Once anything is matched up, there is no going back. The steps are: Simulation. Say where the model output is, how many directories down its files sit, which files to skip or keep, and the domain. Type the directory, with folders suggested as you go, or pick it with Browse…, which looks through the folders on the machine OceanVal runs on, so it works on a remote machine too. The page counts the files that pass your filters as you type. A View files in a random subdirectory pop-up lists file names to help you choose filter words. Own data. If you have observations of your own, add them one at a time as point data (csv files) or gridded data (netCDF), with every argument of add_point_comparison() or add_gridded_comparison(). Arguments you have to give are marked in red. Recipes. Check the model variables OceanVal found and choose the observations to validate against. A pop-out table beside each model variable box lists every variable in the model output with its long_name. It is searchable, sorted ignoring case, and its ticks sum variables. Your own data appears in its variable's row, tagged Your data. Datasets validated through the water column need a thickness variable, which you pick from the model's variables. Units. A table of the units of every gridded and point matchup, read from the model's netCDF files and from the recipes or your own netCDF file. Where the units differ and OceanVal can tell how to convert one into the other, it fills in the multiplier and adder for the observations and says what it assumed, such as a seawater density of 1025 kg/m³ between per kilogram and per volume. Units it can't read, or that measure different things, are marked "Not checked". You always have to confirm the units with a box under the tables before you can carry on. The conversions are written into the matchup script as obs_multiplier and obs_adder. Files. The page reads the date of every model file, with a progress bar. It shows a row for each variable and each set of years it is matched up for: the model variable, the observations, the file pattern, the time resolution (monthly, 1d, 5d and so on), and how many files fall in those years. List files lists them with their first and last dates. If dates are missing or appear in more than one file, the row says so, and Show the months shows which months are there. Only the model output is read here: observation servers are not contacted until the matchup is made. If the files are wrong, change the file filters under the table and click Use these filters. The simulation is then read again and you return to the recipes with your choices kept where the model variables are still in the files. Report. Before anything is matched up, the page asks how you would like your report: which matchups to validate, a subregion, regional summaries, a transect, fixed colour scales, PDF and Word versions, a zipped copy, and a concise or detailed report. Stop and store Python script for later stops here, with nothing matched up, and keeps the script with the options you chose. Run. The page shows what the run is doing and its output as it comes in. Any question OceanVal asks, such as whether to try again for observations a server couldn't supply, is asked in the page. Interim report while the matchups are made Matching up a long simulation can take hours. Now each matchup's page is added to an interim HTML report as soon as the matchup is made, and the summary is rebuilt each time. The run page links to it once its first page exists, so you can start reading results while the rest are still running. When all the matchups are done, the full report is built, with PDF, Word and zip if you asked for them, and the finished page links to it. The window serves the reports itself, so the links work over a forwarded port too. The interim report needs jupyter-book 2 or later. With jupyter-book 1, the run carries on without it. Report options that follow what you validate The report's options list every variable and source in a list that opens, all ticked. Untick any to leave them out. Only the options for what is ticked are shown, and the report can't be built with none ticked. A matchup you untick is still matched up but left out of the report. Regional summaries and fixed colour scales are offered when gridded data is ticked. Transect. Give a start and an end longitude and latitude, and each gridded page gets a land map of the line, the monthly climatology along it and, for matchups through the water column, depth sections. The line must run north–south or east–west. The page marks anything else in red and won't let you carry on. The question is left out when only point data was chosen. Transects need nctoolkit 1.3.6 or later. Depth bins. For point data matched through the water column, a table of From/To depths starting from the defaults lets you edit a bin, remove it, Add a bin or Restore defaults. Overlapping or invalid bins are marked in red and hold the run back. When you validate matchups made earlier, the page looks in the matchups directory as soon as you enter it, says how many gridded and point matchups it found, and then shows the options. Compare existing validations The fourth choice on the first page compares up to five simulations. Give each a name and the directory of its validation (each row has a folder browser). The rows are checked before anything runs, then the comparison is built and the finished page opens it. The window serves the comparison along with the validation reports it links to. Your own data, kept for later Observations you use again can be saved as recipes of your own in .oceanvalrc JSON files: in the directory you work in, for that directory, or in your home directory, for everywhere (the one in the directory wins). OCEANVALRC names another home file. Add your own validation data for future use on the first page has a page for point data (csv) and one for gridded data (netCDF on this machine, on a THREDDS server or at a web address). OceanVal opens the data to check it, and checks the recipe against its own and your others, before saving it. Recipes can also be removed from the same page. In the own data step of a matchup, Add this data for use now only adds a dataset to this run. Add this data for use now and in future also saves it as a recipe, after a page asking for what a recipe needs that the form didn't, such as the units and where to save it. What OceanVal will use unless you change it is shown in amber. Units it can't read are shown in red and you have to give them. Saved recipes are offered in the recipes window, tagged Yours. They are ticked when OceanVal finds a unique matching model variable, by name or by the whole phrase of its long_name. Otherwise the model variable is left blank for you to fill in. Try a demo Try a demo on the first page walks you through a real validation with the options filled in for you. Choose one of three CMIP6 models, each from a different ESGF server (NorESM2-LM, MPI-ESM1-2-LR and UKESM1-0-LL), and one to three of its variables (sea surface temperature, surface nitrate and sea surface salinity). Only those files are downloaded, up to 50 MB, 26 MB and 460 MB for the three models. The year 2010 is matched up with COBE-SST 2 (temperature) and the World Ocean Atlas 2023 (nitrate and salinity). A page of instructions asks whether you want the validation concise and fast (the default) or detailed but slower. The detailed one adds global subregions, a transect down the Pacific along 180° and PDF and Word versions. The demo creates an oceanval_demo directory, which you can remove when you have finished. Preferences and Info The cog beside the OceanVal name (Preferences) sets the window's colours (Default, Dark, Silver or Blue) and whether the first page offers the demo. They are kept under "settings" in the .oceanvalrc file in your home directory. The i beside it opens an About OceanVal panel with the version, links to the website and GitHub, and tables of the built-in gridded and point datasets. Both buttons appear on every page of the window, including the recipes page. Simulations remembered OceanVal now remembers the simulation directories you have matched up, the latest 20, in ~/.oceanvalcache (or the file OCEANVALCACHE names). A simulation is remembered as soon as you confirm its matchups, so a run that fails later is still remembered. They are listed by an arrow at the right of the simulation directory box. Pick one and the box fills in, the files are counted and the years are filled in. Alt+Down opens the list from the keyboard. OceanVal never creates the file ahead of use, and leaves one it can't read, or one from a newer version, untouched. Improv