Merge branch 'master' into use_cftime

Author: ocefpaf

CONTRIBUTING.md renamed to .github/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 *.py[co]
 
 # Packages
-*.egg
+*.egg?
 *.egg-info
 dist
 build
@@ -15,10 +15,12 @@ develop-eggs
 
 # Installer logs
 pip-log.txt
+pip-cache
 
 # Unit test / coverage reports
 .coverage
 .tox
+.pytest_cache
 
 #Translations
 *.mo
@@ -32,6 +34,7 @@ lib/iris/std_names.py
 # Iris test result files
 lib/iris/tests/result_image_comparison/
 iris_image_test_output/
+*.ESMF_LogFile
 
 # Iris test lock file
 lib/iris/tests/results/imagerepo.lock
@@ -50,6 +53,7 @@ docs/iris/src/_static/random_image.js
 docs/iris/src/_templates/gallery.html
 docs/iris/src/examples/
 docs/iris/src/iris/
+docs/iris/src/matplotlibrc
 
 # Example test results
 docs/iris/iris_image_test_output/

.gitignore

@@ -13,7 +13,6 @@ sudo: false
 
 env:
   matrix:
-    - TEST_TARGET=coding
     - TEST_TARGET=default TEST_MINIMAL=true
     - TEST_TARGET=default
     - TEST_TARGET=example
@@ -76,13 +75,14 @@ install:
     CONDA_REQS_FILE=conda-requirements.txt;
     python requirements/gen_conda_requirements.py ${CONDA_REQS_FLAGS} --groups ${CONDA_REQS_GROUPS} > ${CONDA_REQS_FILE};
     cat ${CONDA_REQS_FILE};
-    conda install --quiet --file ${CONDA_REQS_FILE};
+    conda install --quiet -n $ENV_NAME --file ${CONDA_REQS_FILE};
 
   - PREFIX=$HOME/miniconda/envs/$ENV_NAME
 
   # Output debug info
   - >
-    conda list;
+    conda list -n $ENV_NAME;
+    conda list -n $ENV_NAME --explicit;
     conda info -a;
 
 # Pre-load Natural Earth data to avoid multiple, overlapping downloads.
@@ -111,13 +111,13 @@ install:
   # JUST FOR NOW : Install latest version of iris-grib.
   # TODO : remove when iris doesn't do an integration test requiring iris-grib.
   - if [[ "$TEST_MINIMAL" != true && ${TRAVIS_PYTHON_VERSION} == 2* ]]; then
-        conda install python-ecmwf_grib;
+        conda install --quiet -n $ENV_NAME python-ecmwf_grib;
         pip install git+https://github.com/SciTools/iris-grib.git@v0.11.0;
     fi
 
 script:
   - if [[ $TEST_TARGET == 'default' ]]; then
-      python -m iris.tests.runner --default-tests --system-tests --print-failed-images --num-processors=3;
+      python -m iris.tests.runner --default-tests --system-tests --coding-tests --print-failed-images --num-processors=3;
     fi
   - if [[ $TEST_TARGET == 'example' ]]; then
       python -m iris.tests.runner --example-tests --print-failed-images --num-processors=3;
@@ -160,9 +160,3 @@ script:
       cd $INSTALL_DIR/docs/iris/src/whatsnew;
       python aggregate_directory.py --checkonly;
     fi
-  - if [[ $TEST_TARGET == 'coding' ]]; then
-      cd $INSTALL_DIR;
-      python setup.py pyke_rules;
-      python setup.py std_names;
-      python setup.py test --coding-tests;
-    fi

.travis.yml

@@ -34,10 +34,10 @@ https://github.com/SciTools/iris.
 
 Iris makes use of a range of other libraries and python modules. These 
 dependencies must be in place before you can successfully install 
-Iris. Once you have satisfied the requirements detailed below, 
-extract the iris source package, cd to the new directory, and enter::
+Iris. Once you have satisfied the requirements detailed in the
+``requirements`` directory, go to the root of Iris' and run::
 
-  python setup.py install
+  pip install .
 
 
 In-place build - an alternative for developers
@@ -46,118 +46,18 @@ We are very keen to encourage contributions to Iris. For this type of
 development activity an in-place build can be useful. Once you've cloned 
 the Iris git repository you can perform an in-place build with::
 
-  python setup.py develop
-
-
-Build and runtime requirements
-==============================
-These are external packages which you will need to have installed before
-installing and running Iris. 
-
-Many of these packages are available in Linux package managers
-such as aptitude and yum. For example, it may be possible to install 
-Numpy using::
-
-  apt-get install python-numpy
-
-If you are installing dependencies with a package manager on Linux, 
-you may need to install the development packages (look for a "-dev" 
-postfix) in addition to the core packages.  
-
-
-python 2.7 or 3.5+ (http://www.python.org/)
-    Iris requires Python 2.7 or Python 3.5+.
-
-numpy (http://numpy.scipy.org/)
-    Python package for scientific computing including a powerful N-dimensional
-    array object.
-
-scipy (http://www.scipy.org/)
-    Python package for scientific computing.
-
-cartopy v0.11.0 or later (http://github.com/SciTools/cartopy/)
-    Python package which provides cartographic tools for python.
-
-dask v0.15.0 or later (https://dask.pydata.org/)
-    Python package for parallel computing.
-
-PyKE v1.1.1 or later (http://pyke.sourceforge.net/)
-    Python knowledge-based inference engine.
-
-netcdf4-python (http://netcdf4-python.googlecode.com/)
-    Python interface to the netCDF version 4 C library.
-    (It is strongly recommended to ensure your installation uses a
-    thread-safe build of HDF5 to avoid segmentation faults when using
-    lazy evaluation.)
-
-cf_units v2.0 or later (https://github.com/SciTools/cf_units)
-    CF data units handling, using udunits.
-
-setuptools v36.0 or later (http://pypi.python.org/pypi/setuptools/)
-    Python package for installing/removing python packages.
-
-
-The full list of packages may be found in the repository at
-``requirements/core.txt``.
-
-
-Optional
-''''''''
-These are optional packages which you may want to install to enable
-additonal Iris functionality such as plotting and
-loading/saving GRIB. These packages are required for the full Iris test
-suite to run.
-
-gdal (https://pypi.python.org/pypi/GDAL/)
-    Python package for the Geospatial Data Abstraction Library (GDAL).
-
-graphviz (http://www.graphviz.org/)
-    Graph visualisation software.
-
-iris-grib (https://github.com/scitools/iris-grib)
-    Iris interface to ECMWF's GRIB API
-
-matplotlib (https://matplotlib.org)
-    Python package for 2D plotting.  
-
-mock (http://pypi.python.org/pypi/mock/)
-    Python mocking and patching package for testing. Note that this package
-    is only required to support the Iris unit tests.
-
-nose (https://nose.readthedocs.io/en/latest/)
-    Python package for software testing. Iris is not compatible with nose2.
-
-pep8 (https://pypi.python.org/pypi/pep8)
-    Python package for software testing.
-
-pandas (http://pandas.pydata.org)
-    Python package providing high-performance, easy-to-use data structures and
-    data analysis tools.
-
-PythonImagingLibrary (http://effbot.org/zone/pil-index.htm)
-    Python package for image processing.
-
-pyugrid (https://github.com/pyugrid/pyugrid)
-    A Python API to utilize data written using the unstructured grid
-    UGRID conventions.
-
-shapely (https://github.com/Toblerity/Shapely)
-    Python package for the manipulation and analysis of planar geometric
-    objects.
-
-mo_pack (https://github.com/SciTools/mo_pack)
-    A Python wrapper to libmo_unpack, giving WGDOS packing and unpacking.
+  pip install -e .
 
 
 Generating conda requirements
 '''''''''''''''''''''''''''''
 
 Requirements for Iris are stored in the ``requirements`` directory in the root of the source repository.
-It is possible to generate a requirements file suitable for conda use with::
+It is possible to generate a requirements file suitable for use with conda::
 
     python requirements/gen_conda_requirements.py > conda_requirements.txt
 
-This may be installed with::
+This may then be installed with::
 
     conda create -n my_iris_env --file conda_requirements.txt
 

INSTALL

@@ -1,72 +1,102 @@
-Iris
-====
+<h1 align="center">
+  <a href="https://scitools.org.uk/iris/docs/latest/" style="display: block; margin: 0 auto;">
+   <img src="https://raw.githubusercontent.com/pelson/iris/markdown_readme/docs/iris/src/_static/logo_banner.png"
+        style="max-width: 40%;" alt="Iris"></a><br>
+</h1>
 
-[![Join the chat at https://gitter.im/SciTools/iris](https://badges.gitter.im/SciTools/iris.svg)](https://gitter.im/SciTools/iris?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[![Build Status](https://api.travis-ci.org/repositories/SciTools/iris.svg?branch=master)](https://travis-ci.org/SciTools/iris/branches)
-[![DOI](https://zenodo.org/badge/5312648.svg)](https://zenodo.org/badge/latestdoi/5312648)
-[![Documentation for master branch ](https://img.shields.io/badge/docs-master-blue.svg)](https://scitools-docs.github.io/iris/master/index.html)
+<h4 align="center">
+    Iris is a powerful, easy to use, and community-driven Python library for
+    analysing and visualising Earth science data
+</h4>
 
-(C) British Crown Copyright 2010 - 2018, Met Office
-
-Iris is a powerful, easy to use, community-driven Python library for
-analysing and visualising meteorological and oceanographic data sets.
+<p align="center">
+<!-- https://shields.io/ is a good source of these -->
+<a href="https://anaconda.org/conda-forge/iris">
+<img src="https://img.shields.io/conda/dn/conda-forge/iris.svg"
+     alt="conda-forge downloads" /></a>
+<a href="https://github.com/SciTools/iris/releases">
+<img src="https://img.shields.io/github/tag/SciTools/iris.svg"
+     alt="Latest version" /></a>
+<a href="https://github.com/SciTools/iris/commits/master">
+<img src="https://img.shields.io/github/commits-since/SciTools/iris/latest.svg"
+     alt="Commits since last release" /></a>
+<a href="https://github.com/SciTools/iris/graphs/contributors">
+<img src="https://img.shields.io/github/contributors/SciTools/iris.svg"
+     alt="# contributors" /></a>
+<a href="https://travis-ci.org/SciTools/iris/branches">
+<img src="https://api.travis-ci.org/repositories/SciTools/iris.svg?branch=master"
+     alt="Travis-CI" /></a>
+<a href="https://zenodo.org/badge/latestdoi/5312648">
+<img src="https://zenodo.org/badge/5312648.svg"
+     alt="zenodo" /></a>
+</p>
+<br>
 
+<!-- NOTE: toc auto-generated with https://github.com/frnmst/md-toc:
+   $ md_toc github README.md -i
+-->
 
-Installation
-------------
+<h1>Table of contents</h1>
 
-Provided all of the dependencies are satisfied, Iris can be installed
-using the following command:
+[](TOC)
 
-    python setup.py install
++ [Overview](#overview)
++ [Documentation](#documentation)
++ [Installation](#installation)
++ [Copyright and licence](#copyright-and-licence)
 
-For more detailed instructions, including details of the dependencies,
-please see INSTALL.
+[](TOC)
 
+# Overview
 
-What's new
-----------
+Iris implements a data model based on the [CF conventions](http://cfconventions.org/)
+giving you a powerful, format-agnostic, interface for working with your data.
+It excels when working with multi-dimensional Earth Science data, where tabular
+representations become unwieldy and inefficient.
 
-A discussion of recent changes is given by the
-"What's new" document:
+[CF Standard names](http://cfconventions.org/standard-names.html),
+[units](https://github.com/SciTools/cf_units), and coordinate metadata
+are built-in to Iris, giving you a rich and expressive interface for maintaining
+an accurate representation of your data. Its first-class treatment of data and
+associated metadata, includes:
 
-- http://scitools.org.uk/iris/docs/latest/whatsnew/index.html
+  * aggregations and reductions (min, max, (area-)weighted mean, etc.)
+  * interpolation and regridding (nearest-neighbor, linear, area-weighted, etc.)
+  * operator overloads (``+``, ``-``, ``*``, ``/``, etc.)
+  * merge and concatenate
+  * subsetting and extraction
+  * unit conversion
+  * a visualisation interface based on [matplotlib](https://matplotlib.org/) and
+    [cartopy](https://scitools.org.uk/cartopy/docs/latest/)
 
-If you need complete detail, then please refer to the commit history of
-the Iris project on GitHub:
+A number of file formats are recognised by Iris, including CF-compliant NetCDF, GRIB,
+and PP, and it has a plugin architecture to allow other formats to be added seamlessly.
 
-- https://github.com/SciTools/iris
+Building upon [numpy](http://www.numpy.org/) and [dask](https://dask.pydata.org/en/latest/),
+Iris scales from efficient single-machine workflows right through to multi-core clusters and HPC.
+Interoperability with packages from the wider scientific python ecosystem comes from Iris'
+use of standard numpy/dask arrays as its underlying data storage.
 
 
-Documentation
--------------
+# Documentation
 
-The full documentation for the current release of Iris, including a user guide, example
-code, and gallery, is online at:
-- http://scitools.org.uk/iris/
+The documentation for Iris is available at <https://scitools.org.uk/iris/docs/latest>,
+including a user guide, example code, and gallery.
 
-There is also a documentation build for the latest code in the main GitHub repository at:
-- https://scitools-docs.github.io/iris/master/index.html
-(also similarly for other branches)
+# Installation
 
+The easiest way to install Iris is with [conda](https://conda.io/miniconda.html):
 
-Copyright and licence
----------------------
+    conda install -c conda-forge iris
 
-(C) British Crown Copyright 2010 - 2018, Met Office
+Detailed instructions, including information on installing from source,
+are available in [INSTALL](INSTALL).
 
-This file is part of Iris.
 
-Iris is free software: you can redistribute it and/or modify it under
-the terms of the GNU Lesser General Public License as published by the
-Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
+# Copyright and licence
 
-Iris is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU Lesser General Public License for more details.
+Iris may be freely distributed, modified and used commercially under the terms
+of its [GNU LGPLv3 license](COPYING.LESSER).
 
-You should have received a copy of the GNU Lesser General Public License
-along with Iris.  If not, see <http://www.gnu.org/licenses/>.
 
+(C) British Crown Copyright 2010 - 2018, Met Office

README.md

@@ -104,8 +104,7 @@ def main():
         # Add the first subplot showing the E1 scenario
         plt.subplot(121)
         plt.title('HadGEM2 E1 Scenario',  fontsize=10)
-        iplt.contourf(delta_e1, levels, colors=colors, linewidth=0,
-                      extend='both')
+        iplt.contourf(delta_e1, levels, colors=colors, extend='both')
         plt.gca().coastlines()
         # get the current axes' subplot for use later on
         plt1_ax = plt.gca()
@@ -114,7 +113,7 @@ def main():
         plt.subplot(122)
         plt.title('HadGEM2 A1B-Image Scenario',  fontsize=10)
         contour_result = iplt.contourf(delta_a1b, levels, colors=colors,
-                                       linewidth=0, extend='both')
+                                       extend='both')
         plt.gca().coastlines()
         # get the current axes' subplot for use later on
         plt2_ax = plt.gca()