Document using "kvp" to access the facets/keywords of a dataset

[jypeter]

The documentation does not explicitly explain how to access the components/facets of an existing dataset.

Sometimes you don't need these, because you have created the dataset from scratch with ds and you already know the components.

BUT in other cases, you don't know the values of the components/facets, because you are searching the archive and using wildcards. In that case, you can access some of the components/facets with explore("choices") if you are lucky because explore did not return an empty dictionary, or you have to use the kvp attribute of the dataset.

kvp does the job, but is not documented, except (briefly) in the a quick illustration of CMIP data access on Ciclad - CLIMERI notebook

This should probably be documented in the Functions for data definition and access
page

Also, I had to use Google to find out that kvp means Key Value Pairs. Probably talking about Search Facets would make things easier to explain and understand (#189)

The summary : describe files associated with a dataset function also gives access to the kvp (the dictionary of pairs keyword-values associated with the dataset), but the fact that it will give you an error/warning if there is still some ambiguity in the dataset means that you need to know about kvp

Some bits of examples below...

>>> summary(narrow_query)
Multiple available values for attribute "period" that is set to "*" in your ds() call:  [1600-1609, 1630-1659, 1670-1689, 1720-1759, 1790-1799, 1801-1810, 1871-1880, 1901-1910, 1921-1950, 1961-1970, 1991-2000, 2011-2070]
Specify one of them (within ds() or with cdef())
{'project': 'CMIP6', 'simulation': '', 'variable': 'hfls', 'period': '*', 'domain': 'global', 'root': '/bdd', 'model': 'NorESM2-LM', 'institute': '*', 'mip': '*', 'table': 'Amon', 'experiment': 'piControl', 'realization': 'r1i1p1f1', 'grid': 'gn', 'version': 'latest'}

>>> dat_cmip6 = ds(project = 'CMIP6',
               variable = 'tas',
                   # -- CMIP6 new features
                   realization = 'r1i1p1f1',
                   table= 'Amon',
                   grid = 'gr'
              )...                model = 'IPSL-CM6A-LR',
...                experiment = 'ssp585',
...                period = '2015-2100',
...                variable = 'tas',
...                    # -- CMIP6 new features
...                    realization = 'r1i1p1f1',
...                    table= 'Amon',
...                    grid = 'gr'
...               )
>>> dat_cmip6
ds('CMIP6%%tas%2015-2100%global%/bdd%IPSL-CM6A-LR%*%*%Amon%ssp585%r1i1p1f1%gr%latest')

>>> dat_cmip6.explore('choices')
{'institute': 'IPSL', 'mip': 'ScenarioMIP'}

>>> dat_cmip6.kvp
{'project': 'CMIP6', 'simulation': '', 'variable': 'tas', 'period': 2015-2100, 'domain': 'global', 'root': '/bdd', 'model': 'IPSL-CM6A-LR', 'institute': '*', 'mip': '*', 'table': 'Amon', 'experiment': 'ssp585', 'realization': 'r1i1p1f1', 'grid': 'gr', 'version': 'latest'}

>>> dat_cmip6.kvp['variable']
'tas'

>>> summary(dat_cmip6)
/bdd/CMIP6/ScenarioMIP/IPSL/IPSL-CM6A-LR/ssp585/r1i1p1f1/Amon/tas/gr/latest/tas_Amon_IPSL-CM6A-LR_ssp585_r1i1p1f1_gr_201501-210012.nc
{'project': 'CMIP6', 'simulation': '', 'variable': 'tas', 'period': 2015-2100, 'domain': 'global', 'root': '/bdd', 'model': 'IPSL-CM6A-LR', 'institute': '*', 'mip': '*', 'table': 'Amon', 'experiment': 'ssp585', 'realization': 'r1i1p1f1', 'grid': 'gr', 'version': 'latest'}