diff --git a/docs/Software/index.md b/docs/Software/index.md index efe3870..5afda4e 100644 --- a/docs/Software/index.md +++ b/docs/Software/index.md @@ -84,3 +84,144 @@ Or to remove all locally cached versions: ``` dc.delete() ``` + +### Command line tool + +The `export_dreq_lists_json.py` script is a simple command line tool +with options to allow the user to control the output by + +1. Constraining the list of opportunities that the user wishes to + respond to. +1. Specifying the experiments to be included in the output. +1. Specifying the filename to write the output to. + +The command syntax is shown using the help shown below along with a +couple of usage examples + +!!! info "help text for export script" + + ``` + $ export_dreq_lists_json.py --help + usage: export_dreq_lists_json.py [-h] [--opportunities_file OPPORTUNITIES_FILE] [--all_opportunities] [--experiments EXPERIMENTS [EXPERIMENTS ...]] {v1.0alpha,first_export,v1.0beta,v1.0-alpha} output_file + + positional arguments: + {v1.0alpha,first_export,v1.0beta,v1.0-alpha} + data request version + output_file file to write JSON output to + + options: + -h, --help show this help message and exit + --opportunities_file OPPORTUNITIES_FILE + path to JSON file listing opportunities to respond to. If it doesn't exist a template will be created + --all_opportunities Respond to all opporunities + --experiments EXPERIMENTS [EXPERIMENTS ...] + limit output to the specified experiments + ``` + + +!!! info "Generate variable list for all opportunities, but for `historical` experiment only" + + ``` + $ export_dreq_lists_json.py v1.0beta historical.json --all_opportunities --experiments historical + + For data request version v1.0beta, number of requested variables found by experiment: + historical : Core=132 ,High=1011 ,Medium=401 ,Low=98, TOTAL=1642 + + Wrote requested variables to historical.json + ``` + The historical.json file will then look similar to + ``` + { + "Header": { + "Opportunities": [ + "Accurate assessment of land-atmosphere coupling", + "Advancing Wind-Wave Climate Modelling for Coastal Zone Dynamics, Impacts, and Risk Assessment through International Collaborative Research Projects as Part of the Coordinated Ocean Wave Climate Project (COWCliP)", + "AerChemMIP", + ... + "Water cycle/budget assessment", + "Wind driven Ocean Surface Waves " + ], + "dreq version": "v1.0beta" + }, + "experiment": { + "historical": { + "Core": [ + "3hr.huss", + "3hr.pr", + "3hr.tas", + "3hr.uas", + "3hr.vas", + ... + ``` + +!!! info "Generate variable list for one opportunity for all experiments" + + Generate opportunity json file (this must not exist when you run this command) + ``` + $ export_dreq_lists_json.py v1.0beta all_experiments.json --opportunities opportunity_selection.json + written opportunities dict to opportunity_selection.json. Please edit and re-run + ``` + The `opportunity_selection.json` file will contain a set of key + value pairs; + ``` + { + "Sea ice changes, drivers and impacts": true, + "Synoptic systems and impacts": true, + "Atmospheric dynamics and variability ": true, + "Role of fire in the Earth system": true, + "Temperature variability": true, + ... + "Causality of Polar Amplification ": true, + "Changes in marine biogeochemical cycles and ecosystem processes": true + } + ``` + Edit this file and change all `true` values to false other than for + the `"Temperature variability"` key. Re-running the + `export_dreq_lists_json.py` command gives + ``` + $ export_dreq_lists_json.py v1.0beta all.json --opportunities opportunity_selection.json + For data request version v1.0beta, number of requested variables found by experiment: + 1pctCO2 : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + 1pctCO2-bgc : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + 1pctCO2-rad : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + High scenario : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + Initialised prediction (2025-2036) : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + Low overshoot scenario : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + Low scenario : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + Medium scenario : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + Overshoot scenario : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + Very low scenario : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + abrupt-4xCO2 : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + amip : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + amip-p4k : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + esm-hist : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + esm-piControl : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + hist-GHG : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + hist-aer : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + hist-nat : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + historical : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + newGeoMIP : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + piControl : Core=0 ,High=16 ,Medium=16 ,Low=0, TOTAL=32 + + Wrote requested variables to all.json + ``` + The top of the output file `all.json` then contains + ``` + { + "Header": { + "Opportunities": [ + "Temperature variability" + ], + "dreq version": "v1.0beta" + }, + "experiment": { + "1pctCO2": { + "Core": [], + "High": [ + "day.hfls", + "day.hfss", + "day.huss", + "day.mrsos", + "day.rlds", + ... + ``` \ No newline at end of file