functions for inspecting data

summary : describe files associated with a dataset

climaf.functions.summary(dat)[source]

Summary provides the informations on a CliMAF dataset or ensemble of datasets It displays the path and filenames, and the dictionary of pairs keyword-values associated with the dataset.

>>> dat= ds(....)   # some dataset, with whatever variable
>>> summary(dat) #

cshow : dump an object

climaf.driver.cshow(obj)[source]

Provide the in-memory value of a CliMAF object. For a figure object, this will lead to display it ( launch computation if needed. )

functions to create images, and to display datasets and images

ncview: display a dataset

iplot : Interactive version of cshow() for display in IPython Notebooks

climaf.functions.iplot(map)[source]

implot : Interactive version of plot() for display in IPython Notebooks

climaf.functions.implot(field, **kwargs)[source]

ts_plot : Shortcut for ensemble_ts_plot

climaf.functions.ts_plot(ts, **kwargs)[source]

A python-user-friendly interface for the climaf operator ensemble_ts_plot : plot time series.

It takes the same arguments, but you can pass python lists instead of comma-separared strings.

It can take as input:
  • a single CliMAF object dataset alone
  • a dictionary with a name and a single CliMAF object
  • a list of dictionaries or CliMAF objects
  • a CliMAF ensemble

It is also able to take ‘title’ and ‘title_fontsize ‘as argument (will use the right_string resource for this)

See the documentation of ensemble_ts_plot : plot time series for the details on all possible options.

Examples

>>> # some dataset, with whatever variable
>>> ds= ....
>>> # Compute the space average
>>> ts_ds = space_avarege(ds)
>>> # -- Simply provide the CliMAF object
>>> p1 = ts_plot(ts_ds)
>>> # -- Same as above but specify the name associated with the time series in the plot
>>> p2 = ts_plot({'my_dataset':ts_ds})
>>> p3 = ts_plot([ts_ds1,ts_ds2,ts_ds3])
>>> # -- provide multiple time series in a given order with names
>>> p4 = ts_plot([ {'ts_ds1':ts_ds1}, {'ts_ds2':ts_ds2}, {'ts_ds3':ts_ds3} ])
>>> # -- Same as above with lines colors and title
>>> p5 = ts_plot([ {'ts_ds1':ts_ds1}, {'ts_ds2':ts_ds2}, {'ts_ds3':ts_ds3} ], title='Three Time series',
...               colors=['black','blue','red'])
>>> ens_ts = cens({'ts_ds1':ts_ds1, 'ts_ds2':ts_ds2, 'ts_ds3':ts_ds3}, order=['ts_ds1','ts_ds2','ts_ds3'])
>>> ens_ts.set_order(['ts_ds1','ts_ds2','ts_ds3'])
>>> # -- Same result as p4 above but providing a CliMAF ensemble with specified order
>>> p4bis = ts_plot(ens_ts)

plot_params : get plot parameters for a variable and a context

climaf.plot.plot_params.plot_params(variable, context, custom_plot_params=None)[source]

Returns a dictionary of default plotting parameters (isolines, color palettes…) by variable and context, i.e. the full field (full_field), bias (bias), or model-model difference (model_model).

This type of dictionary is typically passed to plot with “**”.

plot_params first loads a set of default CliMAF plotting parameters for both ‘atmos’ and ‘ocean’.

Then, it updates with sets of parameters that are specific to the centers (for instance CNRM or IPSL).

Finally, it can take a custom dictionary as an argument; it will use it to update the dictionary (i.e. override matching entries). Such a dictionnary would be build such as the example at ../climaf/plot/atmos_plot_params.py

Parameters:
  • variable (string) – variable name; The name of the geophysical variable to plot
  • context (string) – among ‘full_field’, ‘bias’, ‘model_model’; The kind of plot
  • custom_plot_params – a user dictionnary that will override CliMAF default values

Returns : a python dictionary with plotting parameters to be used by plot()

Call example

>>> var = 'pr'
>>> climato_dat = time_average(ds(variable=var, project='CMIP5', ...))
>>> # here, the annual mean climatology of a CMIP5 dataset for variable var
>>> climato_ref = time_average(ds(variable=var, project='ref_climatos',...))
>>> # the annual mean climatology of a reference dataset for variable var
>>> bias = diff_regrid(climato_dat,climato_ref)         # We compute the bias map with diff_regrid()
>>> niceplot_params=plot_params(var,'full_field')
>>> climato_plot = plot(climato_dat, **nice_plot_params)
>>> bias_plot = plot(bias, **plot_params(var,'bias'))
>>> my_custom_params = {'pr':{'bias':{'colors':'-10 -5 -2 -0.5 -0.2 -0.1 0 0.1 0.2 0.5 1 2 5 10'}}}
>>> bias_plot_custom_params = plot(bias, **plot_params(var,'bias',custom_plot_params=my_custom_params)
>>> # How to import custom params stored in a my_custom_plot_param_file.py file in the working directory
>>> from my_custom_plot_param_file import dict_plot_params as my_custom_params
>>> bias_plot_custom_params = plot(bias, **plot_params(var,'bias',custom_plot_params=my_custom_params)

hovm_params : provide some SST/climate boxes for plotting Hovmoller diagrams

climaf.plot.plot_params.hovm_params(SSTbox_name)[source]

Returns a dictionary with domain definition of SST/climate specified box for plotting Hovmoller diagrams

This type of dictionary is typically passed to ‘hovm’ operator with “**”.

Arg:
SSTbox_name (string) : SST/climate box name. The available boxes are: ‘NINO3-4’, ‘NINO1-2’, ‘NINO3’, ‘NINO4’, ‘GRL’, ‘NATL’, ‘SAT’ and ‘TPA’.

Returns : a python dictionary with domain parameters (‘latS’, ‘latN’, ‘lonW’, ‘lonE’) to be used by hovm()

Call example

>>> tas=ds(project='example', simulation='AMIPV6ALB2G', variable='tas', frequency='monthly', period='1980')
>>> # We plot a Hovmoller diagram (t,y) at longitude close to 10 for 'NINO1-2' domain
>>> hov_diag=hovm(tas, mean_axis='Point', xpoint=10., title='Temperature', **hovm_params('NINO1-2'))
>>> cfile(hov_diag)

cshow : display a figure using ‘display’

climaf.driver.cshow(obj)[source]

Provide the in-memory value of a CliMAF object. For a figure object, this will lead to display it ( launch computation if needed. )

functions for assembling figures in pages

For choosing between next two fuctnions, see the Note on figure pages

cpage : create an array of figures (output: ‘png’ or ‘pdf’ figure)

class climaf.classes.cpage(fig_lines=None, widths=None, heights=None, fig_trim=True, page_trim=True, format=u'png', orientation=None, page_width=1000.0, page_height=1500.0, title=u'', x=0, y=26, ybox=50, pt=24, font=u'Times-New-Roman', gravity=u'North', background=u'white', insert=u'', insert_width=0)[source]

Builds a CliMAF cpage object, which represents an array of figures (output: ‘png’ or ‘pdf’ figure)

Parameters:
  • fig_lines (a list of lists of figure objects or an ensemble of figure objects) – each sublist of ‘fig_lines’ represents a line of figures
  • widths (list, optional) –

    the list of figure widths, i.e. the width of each column. By default, if fig_lines is:

    • a list of lists: spacing is even
    • an ensemble: one column is used
  • heights (list, optional) – the list of figure heights, i.e. the height of each line. By default spacing is even
  • fig_trim (logical, optional) – to turn on/off triming for all figures. It removes all the surrounding extra space of figures in the page, either True (default) or False
  • page_trim (logical, optional) – to turn on/off triming for the page. It removes all the surrounding extra space of the page, either True (default) or False
  • format (str, optional) – graphic output format, either ‘png’ (default) or ‘pdf’(not recommended)
  • page_width (float, optional) – width resolution of resultant image; CLiMAF default: 1000.
  • page_height (float, optional) – height resolution of resultant image; CLiMAF default: 1500.
  • orientation (str,optional) – if set, it supersedes page_width and page_height with values 1000*1500 (for portrait) or 1500*1000 (for landscape)
  • title (str, optional) – append a label below or above (depending on optional argument ‘gravity’) figures in the page.
  • insert (str,optional) – the filename for an image to insert (centered at the bottom)
  • insert_width (int,optional) – the width at which the inserted image will be scaled (in pixels)

If title is activated:

  • x, y (int, optional): annotate the page with text. x is the offset towards the right from the upper left corner of the page, while y is the offset upward or the bottom according to the optional argument ‘gravity’ (i.e. ‘South’ or ‘North’ respectively); CLiMAF default: x=0, y=26. For more details, see: http://www.imagemagick.org/script/command-line-options.php?#annotate ; where x and y correspond respectively to tx and ty in -annotate {+-}tx{+-}ty text
  • ybox (int, optional): width of the assigned box for title; CLiMAF default: 50. For more details, see: http://www.imagemagick.org/script/command-line-options.php?#splice
  • pt (int, optional): font size of the title; CLiMAF default: 24
  • font (str, optional): set the font to use when creating title; CLiMAF default: ‘Times-New-Roman’. To print a complete list of fonts, use: ‘convert -list font’
  • gravity (str, optional): the choosen direction specifies where to position title; CLiMAF default: ‘North’. For more details, see: http://www.imagemagick.org/script/command-line-options.php?#gravity
  • background (str, optional): background color of the assigned box for title; default: ‘white’. To print a complete list of color names, use: ‘convert -list color’

Example

Using no default value, to create a page with 2 columns and 3 lines:

>>> tas_ds=ds(project='example',simulation='AMIPV6ALB2G', variable='tas', period='1980-1981')
>>> tas_avg=time_average(tas_ds)
>>> fig=plot(tas_avg,title='title')
>>> my_page=cpage([[None, fig],[fig, fig],[fig,fig]], widths=[0.2,0.8],
... heights=[0.33,0.33,0.33], fig_trim=False, page_trim=False,
... format='pdf', title='Page title', x=10, y=20, ybox=45,
... pt=20, font='Utopia', gravity='South', background='grey90',
... page_width=1600., page_height=2400.)

cpage_pdf : create an array of figures (output: ‘pdf’ figure)

class climaf.classes.cpage_pdf(fig_lines=None, widths=None, heights=None, orientation=None, page_width=1000.0, page_height=1500.0, scale=1.0, openright=False, title=u'', x=0, y=2, titlebox=False, pt=u'Huge', font=u'\familydefault', background=u'white')[source]

Builds a CliMAF cpage_pdf object, which represents an array of figures (output: ‘pdf’ figure). Figures are automatically centered in the page using ‘pdfjam’ tool; see http://www2.warwick.ac.uk/fac/sci/statistics/staff/academic-research/firth/software/pdfjam

Parameters:
  • fig_lines (a list of lists of figure objects or an ensemble of figure objects) – each sublist of ‘fig_lines’ represents a line of figures
  • widths (list, optional) –

    the list of figure widths, i.e. the width of each column. By default, if fig_lines is:

    • a list of lists: spacing is even
    • an ensemble: one column is used
  • heights (list, optional) – the list of figure heights, i.e. the height of each line. By default spacing is even
  • page_width (float, optional) – width resolution of resultant image; CLiMAF default: 1000.
  • page_height (float, optional) – height resolution of resultant image; CLiMAF default: 1500.
  • orientation (str,optional) – if set, it supersedes page_width and page_height with values 1000*1500 (for portrait) or 1500*1000 (for landscape)
  • scale (float, optional) – to scale all input pages; default:1.
  • openright (logical, optional) – this option puts an empty figure before the first figure; default: False. For more details, see: http://ftp.oleane.net/pub/CTAN/macros/latex/contrib/pdfpages/pdfpages.pdf
  • title (str, optional) – append a label in the page.

If title is activated, it is by default horizontally centered:

  • x (int, optional): title horizontal shift (in cm).
  • y (int, optional): vertical shift from the top of the page (in cm); only positive (down) values have an effect, default=2 cm
  • titlebox (logical, optional): set it to True to frame the text in a box, frame color is ‘black’
  • pt (str, optional): title font size; CLiMAF default: ‘Huge’ (corresponding to 24 pt). You can set or not a backslash before this argument.
  • font (str, optional): font abbreviation among available LaTex fonts; default: ‘\familydefault’.
  • background (str, optional): frame fill background color; among LaTex ‘fcolorbox’ colors; default: ‘white’.

Left and right margins are set to 2cm.

Example

Using no default value, to create a PDF page with 2 columns and 3 lines:

>>> tas_ds=ds(project='example',simulation='AMIPV6ALB2G', variable='tas', period='1980-1981')
>>> tas_avg=time_average(tas_ds)
>>> fig=plot(tas_avg,title='title',format='pdf')
>>> crop_fig=cpdfcrop(fig)
>>> my_pdfpage=cpage_pdf([[crop_fig,crop_fig],[crop_fig, crop_fig],[crop_fig,crop_fig]],
... widths=[0.2,0.8], heights=[0.33,0.33,0.33], page_width=800., page_height=1200.,
... scale=0.95, openright=True, title='Page title', x=-5, y=10, titlebox=True,
... pt='huge', font='ptm', background='yellow') # Font name is 'Times'