<jupyter_start><jupyter_text>Monsoon (Sperber)This notebook demonstrates how to use the PCDMI Monsoon (Sperber) driver.It is expected that you have downloaded the sample data as demonstrated in [the download notebook](Demo_0_download_data.ipynb)The following cell reads in the choices you made during the download data step.<jupyter_code>from user_choices import demo_data_directory, demo_output_directory<jupyter_output><empty_output><jupyter_text>For immediate help with using the monsoon (sperber) driver, use the `--help` flag, demonstrated here:<jupyter_code>%%bash
driver_monsoon_sperber.py --help<jupyter_output>usage: driver_monsoon_sperber.py [-h] [--parameters PARAMETERS]
                                 [--diags OTHER_PARAMETERS [OTHER_PARAMETERS ...]]
                                 [--mip MIP] [--exp EXP]
                                 [--results_dir RESULTS_DIR]
                                 [--reference_data_path REFERENCE_DATA_PATH]
                                 [--modpath MODPATH] [--frequency FREQUENCY]
                                 [--realm REALM]
                                 [--reference_data_name REFERENCE_DATA_NAME]
                                 [--reference_data_lf_path REFERENCE_DATA_LF_PATH]
                                 [--modpath_lf MODPATH_LF] [--varOBS VAROBS]
                                 [--varModel VARMODEL]
                                 [--ObsUnitsAdjust OBSUNITSADJUST]
                                 [--ModUnitsAdjust MODUNITSADJUST]
                                 [--units UNITS] [--osyear OSYEAR]
                                 [--msy[...]<jupyter_text>Basic Example This metric uses daily precipitation data and computes monsoon scores over 6 preset regions, shown below.<jupyter_code>from IPython.display import Image

Image(filename = "../../../pcmdi_metrics/monsoon_sperber/doc/monsoon_domain_map.png")<jupyter_output><empty_output><jupyter_text>First we demonstrate the parameter file for the basic example. Along with model and observational data, this metric needs to be provided with land fraction masks (`modpath_lf` and `reference_data_lf_path`). The model needs to have `mip` and `exp` specified at a minimum. `frequency`, `realm`, and `realization` are optional. Furthermore, start and end years must be selected for both model and observations.<jupyter_code>with open("basic_monsoon_sperber_param.py") as f:
    print(f.read())<jupyter_output>import os

#
#  OPTIONS ARE SET BY USER IN THIS FILE AS INDICATED BELOW BY:
#
#

# MODEL VARIABLES THAT MUST BE SET
mip = 'cmip5'
exp = 'historical'
#frequency = 'da'
#realm = 'atm'
#realization = 'r6i1p1'

# MODEL VERSIONS AND ROOT PATH
modnames = ['GISS-E2-H']
modpath = 'demo_data/CMIP5_demo_timeseries/historical/atmos/day/pr/pr_day_GISS-E2-H_historical_r6i1p1_20000101-20051231.nc'
modpath_lf = 'demo_data/CMIP5_demo_data/cmip5.historical.GISS-E2-H.sftlf.nc' # land fraction mask

varModel = 'pr'
ModUnitsAdjust = (True, 'multiply', 86400.0)  # kg m-2 s-1 to mm day-1
units = 'mm/d'

msyear = 2000
meyear = 2005

# ROOT PATH FOR OBSERVATIONS
reference_data_path = 'demo_data/obs4MIPs_PCMDI_daily/NASA-JPL/GPCP-1-3/day/pr/gn/latest/pr_day_GPCP-1-3_PCMDI_gn_19961002-20170101.nc'
reference_data_name = 'GPCP-IP'
reference_data_lf_path = 'demo_data/misc_demo_data/fx/sftlf.GPCP-IP.1x1.nc'  # land fraction mask

varOBS = 'pr'
ObsUnitsAdjust = (True, 'multiply', 86400.0)  # kg m-2 s-1 to mm day-1

[...]<jupyter_text>To run the driver using only a parameter file for inputs, do the following:<jupyter_code>%%bash
driver_monsoon_sperber.py -p basic_monsoon_sperber_param.py<jupyter_output>models: ['GISS-E2-H']
realization:  r1i1p1
demo_output/monsoon_sperber/Ex1
demo_output/monsoon_sperber/Ex1
demo_output/monsoon_sperber/Ex1
debug:  False
 -----  obs  ---------------------
lf_path:  demo_data/misc_demo_data/fx/sftlf.GPCP-IP.1x1.nc
 ---  obs  ---
demo_data/obs4MIPs_PCMDI_daily/NASA-JPL/GPCP-1-3/day/pr/gn/latest/pr_day_GPCP-1-3_PCMDI_gn_19961002-20170101.nc
check: calendar:  gregorian
check: year, d.shape:  1998 (365, 180, 360)
check: year, d.shape:  1999 (365, 180, 360)
timechk:  obs obs 12.038519859313965
 -----  GISS-E2-H  ---------------------
lf_path:  demo_data/CMIP5_demo_data/cmip5.historical.GISS-E2-H.sftlf.nc
 ---  r1i1p1  ---
demo_data/CMIP5_demo_timeseries/historical/atmos/day/pr/pr_day_GISS-E2-H_historical_r6i1p1_20000101-20051231.nc
check: calendar:  365_day
check: year, d.shape:  2000 (365, 90, 144)
check: year, d.shape:  2001 (365, 90, 144)
check: year, d.shape:  2002 (365, 90, 144)
check: year, d.shape:  2003 (365, 90, 144)
check: year, d.shape:  2004 (365[...]<jupyter_text>Output optionsThere are several options for output data format. Users can choose to generate metrics in netCDF format along with png graphics.To save these results in a different folder, the `--result_dir` value is changed. Using `$1` to refer to the `demo_output_directory` variable is a trick for the Jupyter Notebook and is not needed for regular command line use.<jupyter_code>%%bash -s "$demo_output_directory"
driver_monsoon_sperber.py -p basic_monsoon_sperber_param.py \
--nc_out --plot --results_dir $1/monsoon_sperber/Ex2<jupyter_output>models: ['GISS-E2-H']
realization:  r1i1p1
demo_output/monsoon_sperber/Ex2
demo_output/monsoon_sperber/Ex2
demo_output/monsoon_sperber/Ex2
debug:  False
 -----  obs  ---------------------
lf_path:  demo_data/misc_demo_data/fx/sftlf.GPCP-IP.1x1.nc
 ---  obs  ---
demo_data/obs4MIPs_PCMDI_daily/NASA-JPL/GPCP-1-3/day/pr/gn/latest/pr_day_GPCP-1-3_PCMDI_gn_19961002-20170101.nc
check: calendar:  gregorian
plot: region AIR nrows 3 ncols 2 index 1
plot: region AUS nrows 3 ncols 2 index 2
plot: region Sahel nrows 3 ncols 2 index 3
plot: region GoG nrows 3 ncols 2 index 4
plot: region NAmo nrows 3 ncols 2 index 5
plot: region SAmo nrows 3 ncols 2 index 6
check: year, d.shape:  1998 (365, 180, 360)
check: year, d.shape:  1999 (365, 180, 360)
timechk:  obs obs 11.28656816482544
 -----  GISS-E2-H  ---------------------
lf_path:  demo_data/CMIP5_demo_data/cmip5.historical.GISS-E2-H.sftlf.nc
 ---  r1i1p1  ---
demo_data/CMIP5_demo_timeseries/historical/atmos/day/pr/pr_day_GISS-E2-H_historical_r6i1p1_20[...]<jupyter_text>Results At a minimum, this driver will produce a JSON file containing the monsoon metrics in the `result_dir`. If the user requests the binary and plot outputs, those will also be present in the `result_dir`. Looking at the results from Ex2:<jupyter_code>! ls {demo_output_directory + "/monsoon_sperber/Ex2"}<jupyter_output>cmip5_GISS-E2-H_historical_r1i1p1_monsoon_sperber_2000-2005.nc
cmip5_GISS-E2-H_historical_r1i1p1_monsoon_sperber_2000-2005.png
cmip5_obs_historical_obs_monsoon_sperber_1998-1999.nc
cmip5_obs_historical_obs_monsoon_sperber_1998-1999.png
monsoon_sperber_stat_cmip5_historical_da_atm_2000-2005.json<jupyter_text>The monsoon metrics are found in the "RESULTS" object in the JSON file. Below we extract and display these metrics.<jupyter_code>import json
metrics_file = demo_output_directory + "/monsoon_sperber/Ex2/monsoon_sperber_stat_cmip5_historical_da_atm_2000-2005.json"
with open(metrics_file) as f:
    results = json.load(f)["RESULTS"]
print(json.dumps(results, indent = 2))<jupyter_output>{
  "GISS-E2-H": {
    "r1i1p1": {
      "AIR": {
        "decay_index": 53,
        "duration": 17,
        "onset_index": 37,
        "slope": 0.037490989405760906
      },
      "AUS": {
        "decay_index": 52,
        "duration": 22,
        "onset_index": 31,
        "slope": 0.028602770104420926
      },
      "GoG": {
        "decay_index": 49,
        "duration": 24,
        "onset_index": 26,
        "slope": 0.017398272573029495
      },
      "NAmo": {
        "decay_index": 64,
        "duration": 52,
        "onset_index": 13,
        "slope": 0.012011903431421198
      },
      "SAmo": {
        "decay_index": 56,
        "duration": 30,
        "onset_index": 27,
        "slope": 0.020883715095941786
      },
      "Sahel": {
        "decay_index": 47,
        "duration": 17,
        "onset_index": 31,
        "slope": 0.03490883309967567
      }
    }
  }
}<jupyter_text>For more help interpreting these values, please consult the following paper: <NAME>. and <NAME>, 2014:The use of fractional accumulated precipitation for the evaluation of theannual cycle of monsoons. Climate Dynamics, 43:3219-3244,doi: 10.1007/s00382-014-2099-3 If `plot = True`, the driver also outputs figures that compare the precipitation pentads between model and observations.<jupyter_code>Image(filename=demo_output_directory+"/monsoon_sperber/Ex2/cmip5_GISS-E2-H_historical_r1i1p1_monsoon_sperber_2000-2005.png")<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.11409164172231176, 'fraction_numerical': 0.07045820861155883, 'mean_word_length': 3.2835305719921104, 'pattern_counts': {'":': 32, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 18, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '9', 'dir': 'jupyter-structured-clean-dedup', 'id': '418231', 'license': 'BSD-3-Clause', 'n_tokens_mistral': 3613, 'n_tokens_neox': 3137, 'n_words': 706, 'path': 'doc/jupyter/Demo/Demo_2b_monsoon_sperber.ipynb', 'repo_name': 'jasonb5/pcmdi_metrics', 'size': '8696'}