README

IRIS EXAMPLE CODE GUIDELINES

Iris code examples are designed to present worked examples of common requests
from the Met Office science community. These are things then that are a little
out of the ordinary and/or a little complex but frequently used within Science.

Worked examples should be in the form of an IPython notebook, which should be
added to this repo and added to the index IPython notebook with a relevant link
title and under a relevant sub-heading (feel free to make a new heading if it
is necessary).

As an Iris developer supplying a new code example then, it is requested that
you observe the following guidelines.

The guidelines, then, are:
  1. Describe what is going on. Ideally there should be about as much prose
     describing code steps shown as there is code.
  2. Use sections. As much as possible, divide the worked example into sections
     that encapsulate one element of the example overall.
  3. Use pictures as appropriate. As is said, a picture paints a thousand
     words. If appropriate then, consider adding a picture to help describe a
     particularly complex point. If the worked example generates a plot,
     include it!
  4. As much as possible, use sample data. Doing so will keep this repo as trim
     as possible and means that common data in a known location is being used
     as standard.
     On occasions where the specifics of the example being demonstrated require
     a more targeted dataset, this may be included in the folder called
     "sample_data" in the root of this repo. This is not the preferred
     approach however, and the total size of added data should be limited as
     far as is possible.
  5. Code considerations. The code should:
     a) be able to run,
     b) be Python code, as opposed to iPython notebook code (so not using any
        shortcuts available in iPython notebooks), and
     c) print versions of any software used, especially for Iris and Cartopy.
  6. These should be worked examples, NOT teaching material. As such, the code
     supplied should entirely demonstrate the point being made and exercises
     for the reader should not be used.



DOCUMENTATION, EXAMPLE AND DATA LICENCE
 
British Crown copyright, 2014.

You may use and re-use the information featured in this repository (not
including logos) free of charge in any format or medium, under the terms of the 
UK's Open Government Licence http://reference.data.gov.uk/id/open-government-licence 
We encourage users to establish hypertext links to this website.

Any email enquiries regarding the use and re-use of this information resource
should be sent to: psi@nationalarchives.gsi.gov.uk.