Documentation: "Running the tool for a single job"

[DrYool]

Hopefully a minor issue. The information in section of the document entitled "Running the tool for a single job" seems to be out of date, and I'm not 100% sure that it's working as intended.

For instance:

1. The command bgcval2 -j jobID fails with a -bash: bgcval2: command not found error
2. The command analysis_timeseries --jobID u-bc179 --keys kmf level1 works ... but falls over (see below)
3. The command analysis_p2p u-bc179 level2 2010 needs to be rephrased as something like analysis_p2p -j u-cz846 -k 'bgc' -y 1990 ... although it falls over (see below)
4. The command bgcval2_make_report u-bc179 2010 needs to be rephrased as bgcval2_make_report -i u-bc179 -y 2010 ... and this appears to work and produce viable HTML

Items 2 and 3 above (once they're rephrased and working) both report a strange error ... FileNotFoundError: /home/users/ayool/bgcval2/key_files/n.yml does not exist. I'm at a bit of a loss for what this file is. Any ideas?

Item 4 seems to work exactly as expected. Although it's only time-series and I'd been hoping for some geographical output (presumably that's what analysis_p2p will help with?).

[ledm]

1. Sorry the single job bgcval2 command is very old and has rotted. I've have to edit the readme. It's best to run the tasks one at a time for now.
2. analysis_timeseries should be working as you use it every time that you run analysis_compare. What exactly was your command line argument?
3. analysis_p2p should work but might be quite fussy, so we might need to work together to get something working here. Happy to help. Also, there is different key lists for time series and p2p. Have you tried using -k physics_p2p bgc_p2p?
4. Great!

When in doubt, most of these commands have --help options now (thanks @valeriupredoi )

analysis_p2p --help

produces:

BGCVal2: 1.0.0
usage: analysis_p2p [-h] -j JOBID [JOBID ...] -y YEARS [YEARS ...] [-k KEYS [KEYS ...]] [-c CONFIG_FILE]

.. module:: analysis_p2p
   :platform: Unix
   :synopsis: A script to produce point to point analysis of model vs data.
.. moduleauthor:: Lee de Mora <[email protected]>

options:
  -h, --help            show this help message and exit
  -j JOBID [JOBID ...], --jobID JOBID [JOBID ...]
                        One or more UKESM Job IDs (automatically generated by the cylc/rose suite).
  -y YEARS [YEARS ...], --years YEARS [YEARS ...]
                        One or more years to focus in on.
  -k KEYS [KEYS ...], --keys KEYS [KEYS ...]
                        Runtime keys - each key links to a pre-determined list of variables to analyse. Keys are: alkalinity, fast, level1, salinity, spinup, ukesm1, physics, bgc, alkalinity_norivalk, bgc_p2p, integration_test, ma_debug, missionatlantic, nowmaps, physics_p2p, kmf,
                        debug, mpas
  -c CONFIG_FILE, --config-file CONFIG_FILE
                        User configuration file (for paths).

``

[DrYool]

1. I figured that the documentation was just a bit old - this isn't part of BGCVal2 that we use quite so often, so I guess footfall has been less here
2. I just went with analysis_timeseries --jobID u-cz846 --keys kmf level1 mostly because that's what was suggested in the documentation. I've just tried again with --keys bgc and that seems to have worked. I assume it's just processed u-cz846 for the fields specified by the bgc key?
3. If I try something a little cleverer here like analysis_p2p -j u-cz846 -k 'bgc' -y 1990 it runs for a bit then spits out this error message ...

testsuite_p2p.py:	INFO:	Made it though initial tests. Running: u-cz846 1990 AirSeaFluxCO2 ['layerless']
Traceback (most recent call last):
  File "/home/users/ayool/miniconda3/envs/bgcval2/bin/analysis_p2p", line 8, in <module>
    sys.exit(run())
             ^^^^^
  File "/home/users/ayool/bgcval2/bgcval2/analysis_p2p.py", line 247, in run
    analysis_p2p(
  File "/home/users/ayool/bgcval2/bgcval2/analysis_p2p.py", line 149, in analysis_p2p
    testsuite_p2p(
  File "/home/users/ayool/bgcval2/bgcval2/p2p/testsuite_p2p.py", line 165, in testsuite_p2p
    b = matchDataAndModel(av[name]['dataFiles'],
                          ~~~~~~~~^^^^^^^^^^^^^
KeyError: 'dataFiles'

Alternatively, when I try another key that looks sensible, analysis_p2p -j u-cz846 -k 'bgc_p2p' -y 1990, it fails again with another quite strange error ...

Traceback (most recent call last):
  File "/home/users/ayool/miniconda3/envs/bgcval2/bin/analysis_p2p", line 8, in <module>
    sys.exit(run())
             ^^^^^
  File "/home/users/ayool/bgcval2/bgcval2/analysis_p2p.py", line 247, in run
    analysis_p2p(
  File "/home/users/ayool/bgcval2/bgcval2/analysis_p2p.py", line 97, in analysis_p2p
    av[key] = load_key_file(key, paths, jobID)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/users/ayool/bgcval2/bgcval2/analysis_timeseries.py", line 307, in load_key_file
    output_dict['gridFile'] = list_input_files(gridFile, key_dict, paths)[0]
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/users/ayool/bgcval2/bgcval2/analysis_timeseries.py", line 112, in list_input_files
    raise OSError(f"Base {basedir} is not a valid directory.")
OSError: Base /users/modellers/ledm/workspace/coast/AMM7_grid is not a valid directory.

In the first instance, all I'm just after some basic fields of BGC quantities like the original BGCVal did. But I clearly don't understand what's needed here.

4. Yeah - great that this just, like, worked. The output even told me how to view the output too (although Linux Firefox is balls).

[valeriupredoi]

Linux Firefox is balls

no it's not 🤣

[DrYool]

Well, I humbly disagree. It takes ages to fire up, spends most of its time hung, and even when it does work it's laggy and unresponsive. It could be that some feature of my configuration has somehow screwed it, but I'm using it out of the box (I don't know any other way). It's exactly the same on my local Linux.

[ledm]

While I'm tempted to mark this as irrelevant - opening firefox through an x-window is a terrible idea (assuming that you're launching this on jasmin!) and at best a short term solution jsut to check everything worked. Your best bet is to either make a local copy or rsync it to the web-facing machine and check your output report there.

[ledm]

Your errors in 2, 3 & 4 are all caused by the same thing: the choice of key lists. level1 is for time-series. (Remember when we decided on these levels: level1: time series, level2: point to point, level3: emergent properties? Pretty sure you were in the meeting - but it might have been before Julien and V's time.) Unfortunately, level1 no longer is relevant and has been superseded with the individual lists: kmf bgc physics. (Because some UKESM runs are physics only and don't have BGC in them anymore!)

However, kmf, bgc & physics are still lists of time series ("level 1") analyses, so are not set up to run p2p ("level 2") analyses. You need to use a list of p2p keys, which should be in bgc_p2p and physics_p2p.

Unfortunately, the bgc_p2p list only contains:

keys:
  AMM7_O3c: True
  AMM7_talk : True  

and the physics_p2p contains:

keys:
  AMM7_SST: True
  AMM7_SSS: True

Both of which are clearly set up for the AMM7 domain, not eORCA1. No one has asked for UKESM p2p analysis for 6+ years, so it's not there anymore. (People have asked for AMM7 stuff though!)

So what needs to be done is:

• set up a new key_lists/ukesm_p2p.yml file
• load that file with a few p2p-friendly UKESM key_files.
• Test test test.
  I'm happy to help with this though.

[DrYool]

Actually, that all sounds useful. I just did what the output told me to do and spawned a Firefox session from the prompt. I have to do that on occasion from my local Linux, so it didn't seem an unreasonable request. I must admit that, although I use rsync_to_esmeval.sh for my normal BGCVal2 reports, I don't really know how best to handle the report produced by bgcval2_make_report. Presumably there's a place on the web-facing machine I should drop the report? I had a look, and found this place ...

/gws/nopw/j04/esmeval/public/AXY

... but it doesn't seem visible now that I'm going looking for it. As it had my name and was empty, I thought "Perfect!", but it clearly isn't the right sort of place.

Anyway, where do you put your reports? I can mimic that for mine I reckon.

[DrYool]

Both of which are clearly set up for the AMM7 domain, not eORCA1. No one has asked for UKESM p2p analysis for 6+ years, so it's not there anymore. (People have asked for AMM7 stuff though!)

So what needs to be done is:

• set up a new key_lists/ukesm_p2p.yml file
• load that file with a few p2p-friendly UKESM key_files.
• Test test test.
  I'm happy to help with this though.

This is what I suspected. I'll try to do this when I can (this week's not a good one for experimenting). It would be good if this functionality could be resurrected.