diff --git a/.readthedocs.yml b/.readthedocs.yml index 1306c3fc2cc..55c24eaddc1 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -17,3 +17,4 @@ python: formats: - htmlzip + - pdf diff --git a/.travis.yml b/.travis.yml index 1eb9e1285ab..604dbbb3538 100644 --- a/.travis.yml +++ b/.travis.yml @@ -122,25 +122,6 @@ script: python -m iris.tests.runner --gallery-tests; fi - # A call to check "whatsnew" contributions are valid, because the Iris test - # for it needs a *developer* install to be able to find the docs. - - > - if [[ "${TEST_TARGET}" == 'doctest' ]]; then - cd ${INSTALL_DIR}/docs/iris/src/whatsnew; - python aggregate_directory.py --checkonly; - fi - - # When pushing built docs, attempt to make a preliminary whatsnew by calling - # 'aggregate_directory.py', before the build. - - > - if [[ "${PUSH_BUILT_DOCS}" == 'true' ]]; then - cd ${INSTALL_DIR}/docs/iris/src/whatsnew; - WHATSNEW=$(ls -d contributions_* 2>/dev/null); - if [[ -n "${WHATSNEW}" ]]; then - python aggregate_directory.py --unreleased; - fi; - fi - # Build the docs. - > if [[ "${TEST_TARGET}" == 'doctest' ]]; then diff --git a/docs/iris/Makefile b/docs/iris/Makefile index a2205020287..4ab54b291ff 100644 --- a/docs/iris/Makefile +++ b/docs/iris/Makefile @@ -5,18 +5,10 @@ html: echo "make html in $$i..."; \ (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html); done -pdf: - @for i in $(SUBDIRS); do\ - echo "make latex in $$i.."; \ - (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) latex); done - echo "\def\sphinxdocclass{MO_report}" > build/latex/docs.tex - echo "\documentclass[letterpaper,10pt,english]{MO_report}" >> build/latex/docs.tex - tail -n +4 build/latex/Iris.tex >> build/latex/docs.tex - sed 's/\\tableofcontents/\\tableofcontents\n\\pagenumbering\{arabic\}/' build/latex/docs.tex > build/latex/docs2.tex - sed 's/subsection{/section{/' build/latex/docs2.tex > build/latex/documentation.tex - (cd build/latex; pdflatex -interaction=scrollmode documentation.tex) - # call latex again to get page numbers right... - (cd build/latex; pdflatex -interaction=scrollmode documentation.tex); +html-noplot: + @for i in $(SUBDIRS); do \ + echo "make html-noplot in $$i..."; \ + (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html-noplot); done all: @for i in $(SUBDIRS); do \ diff --git a/docs/iris/gallery_code/general/__init__.py b/docs/iris/gallery_code/general/__init__.py deleted file mode 100644 index f67741cf37e..00000000000 --- a/docs/iris/gallery_code/general/__init__.py +++ /dev/null @@ -1,4 +0,0 @@ -""" -General visualisation examples -============================== -""" diff --git a/docs/iris/gallery_code/general/plot_SOI_filtering.py b/docs/iris/gallery_code/general/plot_SOI_filtering.py index caf4810c65c..116e819af7a 100644 --- a/docs/iris/gallery_code/general/plot_SOI_filtering.py +++ b/docs/iris/gallery_code/general/plot_SOI_filtering.py @@ -20,8 +20,10 @@ Monthly Weather Review, Vol 112, pp 326-332 """ -import numpy as np + import matplotlib.pyplot as plt +import numpy as np + import iris import iris.plot as iplt diff --git a/docs/iris/gallery_code/general/plot_anomaly_log_colouring.py b/docs/iris/gallery_code/general/plot_anomaly_log_colouring.py index 28f7ce323b8..b0cee818de5 100644 --- a/docs/iris/gallery_code/general/plot_anomaly_log_colouring.py +++ b/docs/iris/gallery_code/general/plot_anomaly_log_colouring.py @@ -27,12 +27,14 @@ See also: http://en.wikipedia.org/wiki/False_color#Pseudocolor. """ + import cartopy.crs as ccrs +import matplotlib.pyplot as plt +import matplotlib.colors as mcols + import iris import iris.coord_categorisation import iris.plot as iplt -import matplotlib.pyplot as plt -import matplotlib.colors as mcols def main(): diff --git a/docs/iris/gallery_code/general/plot_coriolis.py b/docs/iris/gallery_code/general/plot_coriolis.py index 7999e5385f9..cc67d1267c3 100644 --- a/docs/iris/gallery_code/general/plot_coriolis.py +++ b/docs/iris/gallery_code/general/plot_coriolis.py @@ -9,11 +9,13 @@ """ import cartopy.crs as ccrs +import matplotlib.pyplot as plt +import numpy as np + + import iris from iris.coord_systems import GeogCS import iris.plot as iplt -import matplotlib.pyplot as plt -import numpy as np def main(): diff --git a/docs/iris/gallery_code/general/plot_custom_aggregation.py b/docs/iris/gallery_code/general/plot_custom_aggregation.py index 2e73aa277ad..9c847be7798 100644 --- a/docs/iris/gallery_code/general/plot_custom_aggregation.py +++ b/docs/iris/gallery_code/general/plot_custom_aggregation.py @@ -13,6 +13,7 @@ certain temperature over a spell of 5 years or more. """ + import matplotlib.pyplot as plt import numpy as np diff --git a/docs/iris/gallery_code/general/plot_custom_file_loading.py b/docs/iris/gallery_code/general/plot_custom_file_loading.py index 406995d94b0..0d130374a76 100644 --- a/docs/iris/gallery_code/general/plot_custom_file_loading.py +++ b/docs/iris/gallery_code/general/plot_custom_file_loading.py @@ -54,13 +54,13 @@ The cube returned from the load function is then used to produce a plot. """ + import datetime +from cf_units import Unit, CALENDAR_GREGORIAN import matplotlib.pyplot as plt import numpy as np -from cf_units import Unit, CALENDAR_GREGORIAN - import iris import iris.coords as icoords import iris.coord_systems as icoord_systems diff --git a/docs/iris/gallery_code/general/plot_global_map.py b/docs/iris/gallery_code/general/plot_global_map.py index 72e8f287433..41fd2269217 100644 --- a/docs/iris/gallery_code/general/plot_global_map.py +++ b/docs/iris/gallery_code/general/plot_global_map.py @@ -6,6 +6,7 @@ title and the labels for the axes are automatically derived from the metadata. """ + import cartopy.crs as ccrs import matplotlib.pyplot as plt diff --git a/docs/iris/gallery_code/general/plot_inset.py b/docs/iris/gallery_code/general/plot_inset.py index 4735706ef7c..46f5dc5d0f4 100644 --- a/docs/iris/gallery_code/general/plot_inset.py +++ b/docs/iris/gallery_code/general/plot_inset.py @@ -8,10 +8,11 @@ """ +import cartopy.crs as ccrs import matplotlib.pyplot as plt import numpy as np + import iris -import cartopy.crs as ccrs import iris.quickplot as qplt import iris.plot as iplt diff --git a/docs/iris/gallery_code/general/plot_lineplot_with_legend.py b/docs/iris/gallery_code/general/plot_lineplot_with_legend.py index aed636489eb..5641b9c4d00 100644 --- a/docs/iris/gallery_code/general/plot_lineplot_with_legend.py +++ b/docs/iris/gallery_code/general/plot_lineplot_with_legend.py @@ -3,6 +3,7 @@ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ """ + import matplotlib.pyplot as plt import iris diff --git a/docs/iris/gallery_code/general/plot_projections_and_annotations.py b/docs/iris/gallery_code/general/plot_projections_and_annotations.py index 4f85c438351..e59bb236d7a 100644 --- a/docs/iris/gallery_code/general/plot_projections_and_annotations.py +++ b/docs/iris/gallery_code/general/plot_projections_and_annotations.py @@ -13,11 +13,13 @@ We plot these over a specified region, in two different map projections. """ + import cartopy.crs as ccrs +import matplotlib.pyplot as plt +import numpy as np + import iris import iris.plot as iplt -import numpy as np -import matplotlib.pyplot as plt # Define a Cartopy 'ordinary' lat-lon coordinate reference system. diff --git a/docs/iris/gallery_code/general/plot_rotated_pole_mapping.py b/docs/iris/gallery_code/general/plot_rotated_pole_mapping.py index b6a18cac929..063fe93674a 100644 --- a/docs/iris/gallery_code/general/plot_rotated_pole_mapping.py +++ b/docs/iris/gallery_code/general/plot_rotated_pole_mapping.py @@ -11,13 +11,14 @@ * Non native projection and a Natural Earth shaded relief image underlay """ + import cartopy.crs as ccrs import matplotlib.pyplot as plt import iris +import iris.analysis.cartography import iris.plot as iplt import iris.quickplot as qplt -import iris.analysis.cartography def main(): diff --git a/docs/iris/gallery_code/meteorology/__init__.py b/docs/iris/gallery_code/meteorology/__init__.py deleted file mode 100644 index 39c05d08c68..00000000000 --- a/docs/iris/gallery_code/meteorology/__init__.py +++ /dev/null @@ -1,4 +0,0 @@ -""" -Meteorology visualisation examples -================================== -""" diff --git a/docs/iris/gallery_code/meteorology/plot_COP_1d.py b/docs/iris/gallery_code/meteorology/plot_COP_1d.py index 9b951923818..2f93627b77a 100644 --- a/docs/iris/gallery_code/meteorology/plot_COP_1d.py +++ b/docs/iris/gallery_code/meteorology/plot_COP_1d.py @@ -28,14 +28,15 @@ can be found in :ref:`cube-statistics`. """ -import numpy as np + import matplotlib.pyplot as plt +import numpy as np + import iris +import iris.analysis.cartography import iris.plot as iplt import iris.quickplot as qplt -import iris.analysis.cartography - def main(): # Load data into three Cubes, one for each set of NetCDF files. @@ -93,6 +94,7 @@ def main(): time=lambda cell: 1860 <= cell.point.year <= 1999 ) observed = a1b_mean.extract(constraint) + # Assert that this data set is the same as the e1 scenario: # they share data up to the 1999 cut off. assert np.all(np.isclose(observed.data, e1_mean.extract(constraint).data)) @@ -105,9 +107,7 @@ def main(): plt.title("North American mean air temperature", fontsize=18) plt.xlabel("Time / year") - plt.grid() - iplt.show() diff --git a/docs/iris/gallery_code/meteorology/plot_COP_maps.py b/docs/iris/gallery_code/meteorology/plot_COP_maps.py index 840c371c145..a8e6055a775 100644 --- a/docs/iris/gallery_code/meteorology/plot_COP_maps.py +++ b/docs/iris/gallery_code/meteorology/plot_COP_maps.py @@ -21,7 +21,9 @@ doi:10.1029/2009EO210001. """ + import os.path + import matplotlib.pyplot as plt import numpy as np diff --git a/docs/iris/gallery_code/meteorology/plot_TEC.py b/docs/iris/gallery_code/meteorology/plot_TEC.py index 8320af90e97..df2e29ef19c 100644 --- a/docs/iris/gallery_code/meteorology/plot_TEC.py +++ b/docs/iris/gallery_code/meteorology/plot_TEC.py @@ -34,6 +34,7 @@ def main(): plt.ylabel("latitude / degrees") plt.gca().stock_img() plt.gca().coastlines() + iplt.show() diff --git a/docs/iris/gallery_code/meteorology/plot_deriving_phenomena.py b/docs/iris/gallery_code/meteorology/plot_deriving_phenomena.py index 7b3f50a8a54..0bb1fa53a49 100644 --- a/docs/iris/gallery_code/meteorology/plot_deriving_phenomena.py +++ b/docs/iris/gallery_code/meteorology/plot_deriving_phenomena.py @@ -9,6 +9,7 @@ plot. """ + import matplotlib.pyplot as plt import matplotlib.ticker diff --git a/docs/iris/gallery_code/meteorology/plot_hovmoller.py b/docs/iris/gallery_code/meteorology/plot_hovmoller.py index d8954d775ff..9f18b8021e4 100644 --- a/docs/iris/gallery_code/meteorology/plot_hovmoller.py +++ b/docs/iris/gallery_code/meteorology/plot_hovmoller.py @@ -8,8 +8,9 @@ temperature. """ -import matplotlib.pyplot as plt + import matplotlib.dates as mdates +import matplotlib.pyplot as plt import iris import iris.plot as iplt diff --git a/docs/iris/gallery_code/meteorology/plot_lagged_ensemble.py b/docs/iris/gallery_code/meteorology/plot_lagged_ensemble.py index 298d178a1e8..5f2ab724b3f 100644 --- a/docs/iris/gallery_code/meteorology/plot_lagged_ensemble.py +++ b/docs/iris/gallery_code/meteorology/plot_lagged_ensemble.py @@ -17,6 +17,7 @@ model, from each ensemble member. """ + import matplotlib.pyplot as plt import numpy as np diff --git a/docs/iris/gallery_code/meteorology/plot_wind_speed.py b/docs/iris/gallery_code/meteorology/plot_wind_speed.py index 2d8081158ce..6844d3874cc 100644 --- a/docs/iris/gallery_code/meteorology/plot_wind_speed.py +++ b/docs/iris/gallery_code/meteorology/plot_wind_speed.py @@ -11,6 +11,8 @@ """ +import cartopy.crs as ccrs +import cartopy.feature as cfeat import matplotlib.pyplot as plt import numpy as np @@ -18,9 +20,6 @@ import iris.coord_categorisation import iris.quickplot as qplt -import cartopy.feature as cfeat -import cartopy.crs as ccrs - def main(): # Load the u and v components of wind from a pp file diff --git a/docs/iris/gallery_code/oceanography/__init__.py b/docs/iris/gallery_code/oceanography/__init__.py deleted file mode 100644 index afac828a052..00000000000 --- a/docs/iris/gallery_code/oceanography/__init__.py +++ /dev/null @@ -1,4 +0,0 @@ -""" -Oceanography visualisation examples -=================================== -""" diff --git a/docs/iris/gallery_code/oceanography/plot_atlantic_profiles.py b/docs/iris/gallery_code/oceanography/plot_atlantic_profiles.py index 8a541c11fae..a7e82c34f51 100644 --- a/docs/iris/gallery_code/oceanography/plot_atlantic_profiles.py +++ b/docs/iris/gallery_code/oceanography/plot_atlantic_profiles.py @@ -15,10 +15,12 @@ depth values intuitively increase downward on the y-axis. """ + +import matplotlib.pyplot as plt + import iris import iris.iterate import iris.plot as iplt -import matplotlib.pyplot as plt def main(): @@ -56,6 +58,7 @@ def main(): ax1.set_ylabel("Depth / m") for ticklabel in ax1.get_xticklabels(): ticklabel.set_color(temperature_color) + # To plot salinity in the same axes we use twiny(). We'll use a different # color to identify salinity. salinity_color = (0.6, 0.1, 0.15) diff --git a/docs/iris/gallery_code/oceanography/plot_load_nemo.py b/docs/iris/gallery_code/oceanography/plot_load_nemo.py index 645617f6006..5f2b72c956f 100644 --- a/docs/iris/gallery_code/oceanography/plot_load_nemo.py +++ b/docs/iris/gallery_code/oceanography/plot_load_nemo.py @@ -7,12 +7,14 @@ different time dimensions in these files can prevent Iris from concatenating them without the intervention shown here. """ + from __future__ import unicode_literals +import matplotlib.pyplot as plt + import iris import iris.plot as iplt import iris.quickplot as qplt -import matplotlib.pyplot as plt from iris.util import promote_aux_coord_to_dim_coord @@ -57,6 +59,7 @@ def main(): cube.long_name.capitalize(), lat_string, lon_string ) ) + iplt.show() diff --git a/docs/iris/gallery_code/oceanography/plot_orca_projection.py b/docs/iris/gallery_code/oceanography/plot_orca_projection.py index bf2498c2293..627be8591b1 100644 --- a/docs/iris/gallery_code/oceanography/plot_orca_projection.py +++ b/docs/iris/gallery_code/oceanography/plot_orca_projection.py @@ -12,9 +12,9 @@ """ +import cartopy.crs as ccrs import matplotlib.pyplot as plt -import cartopy.crs as ccrs import iris import iris.analysis.cartography import iris.plot as iplt diff --git a/docs/iris/src/conf.py b/docs/iris/src/conf.py index db54fff39bc..8fdce664dbb 100644 --- a/docs/iris/src/conf.py +++ b/docs/iris/src/conf.py @@ -36,6 +36,13 @@ def autolog(message): if on_rtd: autolog("Build running on READTHEDOCS server") + # list all the READTHEDOCS environment variables that may be of use + # at some point + autolog("Listing all environment variables on the READTHEDOCS server...") + + for item, value in os.environ.items(): + autolog("[READTHEDOCS] {} = {}".format(item, value)) + # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, @@ -62,8 +69,8 @@ def autolog(message): # define the copyright information for latex builds. Note, for html builds, # the copyright exists directly inside "_templates/layout.html" upper_copy_year = datetime.datetime.now().year -copyright = "Iris contributors" -_authors = "Iris developers" +copyright = "Iris Contributors" +author = "Iris Developers" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -258,54 +265,3 @@ def autolog(message): message="Matplotlib is currently using agg, which is a" " non-GUI backend, so cannot show the figure.", ) - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -# latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -# latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -# latex_documents = [ -# ( -# "contents", -# "Iris.tex", -# "Iris Documentation", -# " \\and ".join(_authors), -# "manual", -# ), -# ] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -# latex_preamble = '' - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True -# latex_elements = {} -# latex_elements["docclass"] = "MO_report" - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -# man_pages = [("index", "iris", "Iris Documentation", _authors, 1)] diff --git a/docs/iris/src/developers_guide/contributing_documentation.rst b/docs/iris/src/developers_guide/contributing_documentation.rst index f8e01ed927d..b7bc99b647c 100644 --- a/docs/iris/src/developers_guide/contributing_documentation.rst +++ b/docs/iris/src/developers_guide/contributing_documentation.rst @@ -25,6 +25,8 @@ The documentation uses specific packages that need to be present. Please see :ref:`installing_iris` for instructions. +.. _contributing.documentation.building: + Building -------- diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index ae4361b2ebe..811aeb59cc9 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -4,18 +4,14 @@ Contributing a "What's New" entry ================================= -Iris has an aggregator for building a draft what's new document for each -release. The draft what's new document is built from contributions by code authors. -This means contributions to the what's new document are written by the -developer most familiar with the change made. +Iris uses a file named ``latest.rst`` to keep a draft of upcoming changes +that will form the next release. Contributions to the :ref:`iris_whatsnew` +document are written by the developer most familiar with the change made. +The contribution should be included as part of the Iris Pull Request that +introduces the change. -A contribution provides an entry in the what's new document, which describes a -change that improved Iris in some way. This change may be a new feature in Iris -or the fix for a bug introduced in a previous release. The contribution should -be included as part of the Iris Pull Request that introduces the change. - -When a new release is prepared, the what's new contributions are combined into -a draft what's new document for the release. +The ``latest.rst`` and the past release notes are kept in +``docs/iris/src/whatsnew/``. Writing a contribution @@ -26,98 +22,54 @@ which improved Iris in some way. As such, a single Iris Pull Request may contain multiple changes that are worth highlighting as contributions to the what's new document. -Each contribution will ideally be written as a single concise bullet point. -The content of the bullet point should highlight the change that has been made -to Iris, targeting an Iris user as the audience. - -A contribution is a feature summary by the code author, which avoids the -release developer having to personally review the change in detail : -It is not in itself the final documentation content, -so it does not have to be perfect or complete in every respect. - - -Adding contribution files -========================= +Each contribution will ideally be written as a single concise bullet point +in a reStructuredText format with a trailing blank line. For example:: -Each release must have a directory called ``contributions_``, -which should be created following the release of the current version of Iris. Each -release directory must be placed in ``docs/iris/src/whatsnew/``. -Contributions to the what's new must be written in markdown and placed into this -directory in text files. The filename for each item should be structured as follows: + * Fixed :issue:`9999`. Lorem ipsum dolor sit amet, consectetur adipiscing + elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + -``__.txt`` - -Category --------- -The category must be one of the following: - -*newfeature* - Features that are new or changed to add functionality. -*bugfix* - A bugfix. -*incompatiblechange* - A change that causes an incompatibility with prior versions of Iris. -*deprecate* - Deprecations of functionality. -*docchange* - Changes to documentation. +Note that this example also cites the related issue, optionally you may also +include the pull request using the notation ``:pull:`9999```. Where possible +do not exceed **column 80** and ensure that any subsequent lines +of the same bullet point is aligned with the first. -Date ----- - -The date must be a hyphen-separated date in the format of: - - * a four digit year, - * a three character month name, and - * a two digit day. - -For example: - - * 2012-Jan-30 - * 2014-May-03 - * 2015-Feb-19 - -Summary -------- +The content of the bullet point should highlight the change that has been made +to Iris, targeting an Iris user as the audience. -The summary can be any remaining filename characters, and simply provides a -short identifying description of the change. +For inspiration that may include adding links to code please examine past +what's :ref:`iris_whatsnew` entries. -For example: +.. note:: The reStructuredText syntax will be checked as part of building + the documentation. Any warnings should be corrected. + `travis-ci`_ will automatically build the documention when + creating a pull request, however you can also manually + :ref:`build ` the documentation. - * whats-new-aggregator - * using_mo_pack - * correction-to-bilinear-regrid - * GRIB2_pdt11 +.. _travis-ci: https://travis-ci.org/github/SciTools/iris -Complete examples ------------------ +Contribution categories +======================= -Some sample what's new contribution filenames: +The structure of the what's new release note should be easy to read by +users. To achieve this several categories may be used. - * bugfix_2015-Aug-18_partial_pp_constraints.txt - * deprecate_2015-Nov-01_unit-module.txt - * incompatiblechange_2015-Oct-12_GRIB_optional_Python3_unavailable.txt - * newfeature_2015-Jul-03_pearsonr_rewrite.txt +*Features* + Features that are new or changed to add functionality. -.. note:: - A test in the standard test suite ensures that all the contents of the - latest contributions directory conform to this naming scheme. +*Bug Fixes* + A bug fix. +*Incompatible Changes* + A change that causes an incompatibility with prior versions of Iris. -Compiling a draft -================= +*Internal* + Changes to any internal or development related topics, such as testing, + environment dependencies etc -Compiling a draft from the supplied contributions should be done when preparing -a release. Running ``docs/iris/src/whatsnew/aggregate_directory.py`` with the -release number as the argument will create a draft what's new with the name -``.rst`` file for the specified release, by aggregating the individual -contributions from the relevant folder. -Omitting the release number will build the latest version for which a -contributions folder is present. -This command fails if a file with the relevant name already exists. +*Deprecations* + Deprecations of functionality. -The resulting draft document is only a starting point, which the release -developer will then edit to produce the final 'What's new in Iris x.x' -documentation. +*Documentation* + Changes to documentation. diff --git a/docs/iris/src/developers_guide/release.rst b/docs/iris/src/developers_guide/release.rst index 5d1a683d44c..c44a2483520 100644 --- a/docs/iris/src/developers_guide/release.rst +++ b/docs/iris/src/developers_guide/release.rst @@ -1,75 +1,165 @@ .. _iris_development_releases: Releases -******** +======== + +A release of Iris is a `tag on the SciTools/Iris`_ +Github repository. + +The summary below is of the main areas that constitute the release. The final +section details the :ref:`iris_development_releases_steps` to take. -A release of Iris is a tag on the SciTools/Iris Github repository. Release branch -============== +-------------- -Once the features intended for the release are on master, a release branch should be created, in the SciTools/Iris repository. This will have the name: +Once the features intended for the release are on master, a release branch +should be created, in the SciTools/Iris repository. This will have the name: - :literal:`{major release number}.{minor release number}.x` + :literal:`v{major release number}.{minor release number}.x` for example: :literal:`v1.9.x` -This branch shall be used to finalise the release details in preparation for the release candidate. +This branch shall be used to finalise the release details in preparation for +the release candidate. + Release candidate -================= +----------------- -Prior to a release, a release candidate tag may be created, marked as a pre-release in github, with a tag ending with :literal:`rc` followed by a number, e.g.: +Prior to a release, a release candidate tag may be created, marked as a +pre-release in github, with a tag ending with :literal:`rc` followed by a +number, e.g.: :literal:`v1.9.0rc1` -If created, the pre-release shall be available for at least one week prior to the release being cut. User groups should be notified of the existence of the pre-release and encouraged to test the functionality. +If created, the pre-release shall be available for a minimum of two weeks +prior to the release being cut. However a 4 week period should be the goal +to allow user groups to be notified of the existence of the pre-release and +encouraged to test the functionality. -A pre-release is expected for a minor release, but not normally provided for a point release. +A pre-release is expected for a minor release, but will not for a +point release. -If new features are required for a release after a release candidate has been cut, a new pre-release shall be issued first. +If new features are required for a release after a release candidate has been +cut, a new pre-release shall be issued first. -Documentation -============= -The documentation should include all of the what's new snippets, which must be compiled into a what's new. This content should be reviewed and adapted as required and the snippets removed from the branch to produce a coherent what's new page. +Documentation +------------- -Upon release, the documentation shall be added to the SciTools scitools.org.uk github project's gh-pages branch as the latest documentation. +The documentation should include all of the what's new entries for the release. +This content should be reviewed and adapted as required. -Testing the conda recipe -======================== +Steps to achieve this can be found in the :ref:`iris_development_releases_steps`. -Before a release is cut, the SciTools conda-recipes-scitools recipe for Iris shall be tested to build the release branch of Iris; this test recipe shall not be merged onto conda-recipes-scitools. The release -=========== +----------- + +The final steps are to change the version string in the source of +:literal:`Iris.__init__.py` and include the release date in the relevant what's +new page within the documentation. -The final steps are to change the version string in the source of :literal:`Iris.__init__.py` and include the release date in the relevant what's new page within the documentation. +Once all checks are complete, the release is cut by the creation of a new tag +in the SciTools Iris repository. -Once all checks are complete, the release is cut by the creation of a new tag in the SciTools Iris repository. Conda recipe -============ +------------ -Once a release is cut, the SciTools conda-recipes-scitools recipe for Iris shall be updated to build the latest release of Iris and push this artefact to anaconda.org. The build and push is all automated as part of the merge process. +Once a release is cut, the `Iris feedstock`_ for the conda recipe must be +updated to build the latest release of Iris and push this artefact to +`conda forge`_. + +.. _Iris feedstock: https://github.com/conda-forge/iris-feedstock/tree/master/recipe +.. _conda forge: https://anaconda.org/conda-forge/iris Merge back -========== +---------- + +After the release is cut, the changes shall be merged back onto the +Scitools/iris master branch. -After the release is cut, the changes shall be merged back onto the scitools master. +To achieve this, first cut a local branch from the release branch, +:literal:`{release}.x`. Next add a commit changing the release string to match +the release string on scitools/master. This branch can now be proposed as a +pull request to master. This work flow ensures that the commit identifiers are +consistent between the :literal:`.x` branch and :literal:`master`. -To achieve this, first cut a local branch from the release branch, :literal:`{release}.x`. Next add a commit changing the release string to match the release string on scitools/master. -This branch can now be proposed as a pull request to master. This work flow ensures that the commit identifiers are consistent between the :literal:`.x` branch and :literal:`master`. Point releases -============== +-------------- -Bug fixes may be implemented and targeted as the :literal:`.x` branch. These should lead to a new point release, another tag. -For example, a fix for a problem with 1.9.0 will be merged into 1.9.x, and then released by tagging 1.9.1. +Bug fixes may be implemented and targeted as the :literal:`.x` branch. These +should lead to a new point release, another tag. For example, a fix for a +problem with 1.9.0 will be merged into 1.9.x, and then released by tagging +1.9.1. New features shall not be included in a point release, these are for bug fixes. -A point release does not require a release candidate, but the rest of the release process is to be followed, including the merge back of changes into :literal:`master`. +A point release does not require a release candidate, but the rest of the +release process is to be followed, including the merge back of changes into +:literal:`master`. + + +.. _iris_development_releases_steps: + +Maintainer steps +---------------- + +These steps assume a release for ``v1.9`` is to be created + +Release steps +~~~~~~~~~~~~~ + +#. Create the branch ``1.9.x`` on the main repo, not in a forked repo, for the + release candidate or release. The only exception is for a point/bugfix + release as it should already exist +#. Update the what's new for the release: + + * Copy ``docs/iris/src/whatsnew/latest.rst`` to a file named + ``v1.9.rst`` + * Delete the ``docs/iris/src/whatsnew/latest.rst`` file so it will not + cause an issue in the build + * In ``v1.9.rst`` update the page title (first line of the file) to show + the date and version in the format of ``v1.9 (DD MMM YYYY)``. For + example ``v1.9 (03 Aug 2020)`` + * Review the file for correctness + * Add ``v1.9.rst`` to git and commit all changes, including removal of + ``latest.rst`` + +#. Update the what's new index ``docs/iris/src/whatsnew/index.rst`` + + * Temporarily remove reference to ``latest.rst`` + * Add a reference to ``v1.9.rst`` to the top of the list + +#. Update the ``Iris.__init__.py`` version string, to ``1.9.0`` +#. Check your changes by building the documentation and viewing the changes +#. Once all the above steps are complete, the release is cut, using + the :guilabel:`Draft a new release` button on the + `Iris release page `_ + + +Post release steps +~~~~~~~~~~~~~~~~~~ + +#. Check the documentation has built on `Read The Docs`_. The build is + triggered by any commit to master. Additionally check that the versions + available in the pop out menu in the bottom left corner include the new + release version. If it is not present you will need to configure the + versions avaiable in the **admin** dashboard in Read The Docs +#. Copy ``docs/iris/src/whatsnew/latest.rst.template`` to + ``docs/iris/src/whatsnew/latest.rst``. This will reset + the file with the ``unreleased`` heading and placeholders for the what's + new headings +#. Add back in the reference to ``latest.rst`` to the what's new index + ``docs/iris/src/whatsnew/index.rst`` +#. Update ``Iris.__init__.py`` version string to show as ``1.10.dev0`` +#. Merge back to master + +.. _Read The Docs: https://readthedocs.org/projects/scitools-iris/builds/ +.. _tag on the SciTools/Iris: https://github.com/SciTools/iris/releases diff --git a/docs/iris/src/index.rst b/docs/iris/src/index.rst index 035d0c07b57..759f2f0d7e9 100644 --- a/docs/iris/src/index.rst +++ b/docs/iris/src/index.rst @@ -1,6 +1,8 @@ Iris Documentation ================== +.. todolist:: + **A powerful, format-agnostic, community-driven Python library for analysing and visualising Earth science data.** diff --git a/docs/iris/src/whatsnew/1.0.rst b/docs/iris/src/whatsnew/1.0.rst index 6340d0495db..79afd8cf1ae 100644 --- a/docs/iris/src/whatsnew/1.0.rst +++ b/docs/iris/src/whatsnew/1.0.rst @@ -1,12 +1,15 @@ -What's new in Iris 1.0 -********************** +v1.0 (17 Oct 2012) +****************** -:Release: 1.0.0 -:Date: 15 Oct, 2012 - -This document explains the new/changed features of Iris in version 1.0. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) + +.. contents:: Skip to section: + :local: + :depth: 3 + + With the release of Iris 1.0, we have broadly completed the transition to the CF data model, and established a stable foundation for future work. Following this release we plan to deliver significant performance @@ -28,45 +31,41 @@ to formalise their data model reach maturity, they will be included in Iris where significant backwards-compatibility can be maintained. -Iris 1.0 features -================= +Features +======== A summary of the main features added with version 1.0: * Hybrid-pressure vertical coordinates, and the ability to load from GRIB. + * Initial support for CF-style coordinate systems. + * Use of Cartopy for mapping in matplotlib. + * Load data from NIMROD files. + * Availability of Cynthia Brewer colour palettes. + * Add a citation to a plot. + * Ensures netCDF files are properly closed. + * The ability to bypass merging when loading data. + * Save netCDF files with an unlimited dimension. + * A more explicit set of load functions, which also allow the automatic cube merging to be bypassed as a last resort. + * The ability to project a cube with a lat-lon or rotated lat-lon coordinate system into a range of map projections e.g. Polar Stereographic. - -Incompatible changes --------------------- -* The "source" and "history" metadata are now represented as Cube - attributes, where previously they used coordinates. -* :meth:`iris.cube.Cube.coord_dims()` now returns a tuple instead of a list. -* The ``iris.plot.gcm`` and ``iris.plot.map_setup`` functions are now removed. - See :ref:`whats-new-cartopy` for further details. - -Deprecations ------------- -* The methods :meth:`iris.coords.Coord.cos()` and - :meth:`iris.coords.Coord.sin()` have been deprecated. -* The :func:`iris.load_strict()` function has been deprecated. Code - should now use the :func:`iris.load_cube()` and - :func:`iris.load_cubes()` functions instead. +* Cube summaries are now more readable when the scalar coordinates + contain bounds. CF-netCDF coordinate systems -============================ +---------------------------- The coordinate systems in Iris are now defined by the CF-netCDF `grid mappings `_. @@ -96,7 +95,7 @@ coordinate system used by the British .. _whats-new-cartopy: Using Cartopy for mapping in matplotlib -======================================= +--------------------------------------- The underlying map drawing package has now been updated to use `Cartopy `_. Cartopy provides a @@ -143,7 +142,7 @@ For more examples of what can be done with Cartopy, see the Iris gallery and Hybrid-pressure -=============== +--------------- With the introduction of the :class:`~iris.aux_factory.HybridPressureFactory` class, it is now possible to represent data expressed on a @@ -163,7 +162,7 @@ the derived "pressure" coordinate for certain data [#f1]_ from the NetCDF -====== +------ When saving a Cube to a netCDF file, Iris will now define the outermost dimension as an unlimited/record dimension. In combination with the @@ -189,7 +188,7 @@ processes. Brewer colour palettes -====================== +---------------------- Iris includes a selection of carefully designed colour palettes produced by Cynthia Brewer. The :mod:`iris.palette` module registers the Brewer @@ -215,7 +214,7 @@ in the citation guidance provided by Cynthia Brewer. Metadata attributes -=================== +------------------- Iris now stores "source" and "history" metadata in Cube attributes. For example:: @@ -249,7 +248,7 @@ Where previously it would have appeared as:: New loading functions -===================== +--------------------- The main functions for loading cubes are now: - :func:`iris.load()` @@ -272,7 +271,7 @@ functions instead. Cube projection -=============== +--------------- Iris now has the ability to project a cube into a number of map projections. This functionality is provided by :func:`iris.analysis.cartography.project()`. @@ -309,7 +308,24 @@ preserved. This function currently assumes global data and will if necessary extrapolate beyond the geographical extent of the source cube. -Other changes -============= -* Cube summaries are now more readable when the scalar coordinates - contain bounds. +Incompatible changes +==================== + +* The "source" and "history" metadata are now represented as Cube + attributes, where previously they used coordinates. + +* :meth:`iris.cube.Cube.coord_dims()` now returns a tuple instead of a list. + +* The ``iris.plot.gcm`` and ``iris.plot.map_setup`` functions are now removed. + See :ref:`whats-new-cartopy` for further details. + + +Deprecations +============ + +* The methods :meth:`iris.coords.Coord.cos()` and + :meth:`iris.coords.Coord.sin()` have been deprecated. + +* The :func:`iris.load_strict()` function has been deprecated. Code + should now use the :func:`iris.load_cube()` and + :func:`iris.load_cubes()` functions instead. diff --git a/docs/iris/src/whatsnew/1.1.rst b/docs/iris/src/whatsnew/1.1.rst index 274ec65ff67..ea85dbc42c8 100644 --- a/docs/iris/src/whatsnew/1.1.rst +++ b/docs/iris/src/whatsnew/1.1.rst @@ -1,71 +1,64 @@ -What's new in Iris 1.1 -********************** +v1.1 (03 Jan 2013) +****************** -:Release: 1.1.0 -:Date: 7 Dec, 2012 - -This document explains the new/changed features of Iris in version 1.1. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -With the release of Iris 1.1, we are introducing support for Mac OS X. -Version 1.1 also sees the first batch of performance enhancements, with -some notable improvements to netCDF/PP import. + +.. contents:: Skip to section: + :local: + :depth: 3 -Iris 1.1 features -================= +Features +======== -A summary of the main features added with version 1.1: +With the release of Iris 1.1, we are introducing support for Mac OS X. +Version 1.1 also sees the first batch of performance enhancements, with +some notable improvements to netCDF/PP import. * Support for Mac OS X. + * GRIB1 import now supports time units of "3 hours". + * Fieldsfile import now supports unpacked and "CRAY" 32-bit packed data in 64-bit Fieldsfiles. + * PP file import now supports "CRAY" 32-bit packed data. + * Various performance improvements, particularly for netCDF import, PP import, and constraints. + * GRIB2 export now supports level types of altitude and height (codes 102 and 103). + * iris.analysis.cartography.area_weights now supports non-standard dimension orders. + * PP file import now adds the "forecast_reference_time" for fields where LBTIM is 11, 12, 13, 31, or 32. + * PP file import now supports LBTIM values of 1, 2, and 3. + * Fieldsfile import now has some support for ancillary files. + * Coordinate categorisation functions added for day-of-year and user-defined seasons. + * GRIB2 import now has partial support for probability data defined with product template 4.9. -Bugs fixed ----------- -* PP export no longer attempts to set/overwrite the STASH code based on - the standard_name. -* Cell comparisons now work consistently, which fixes a bug where - bounded_cell > point_cell compares the point to the bounds but, - point_cell < bounded_cell compares the points. -* Fieldsfile import now correctly recognises pre v3.1 and post v5.2 - versions, which fixes a bug where the two were interchanged. -* iris.analysis.trajectory.interpolate now handles hybrid-height. - -Incompatible changes --------------------- -* N/A - -Deprecations ------------- -* N/A - Coordinate categorisation -========================= +------------------------- An :func:`~iris.coord_categorisation.add_day_of_year` categorisation function has been added to the existing suite in :mod:`iris.coord_categorisation`. + Custom seasons --------------- +~~~~~~~~~~~~~~ The conventional seasonal categorisation functions have been complemented by two groups of functions which handle user-defined, @@ -97,3 +90,19 @@ The other custom season function is: This function adds a coordinate containing True/False values determined by membership of a single custom season. + + +Bugs fixed +========== + +* PP export no longer attempts to set/overwrite the STASH code based on + the standard_name. + +* Cell comparisons now work consistently, which fixes a bug where + bounded_cell > point_cell compares the point to the bounds but, + point_cell < bounded_cell compares the points. + +* Fieldsfile import now correctly recognises pre v3.1 and post v5.2 + versions, which fixes a bug where the two were interchanged. + +* iris.analysis.trajectory.interpolate now handles hybrid-height. diff --git a/docs/iris/src/whatsnew/1.10.rst b/docs/iris/src/whatsnew/1.10.rst index bc2b7528b29..64133232034 100644 --- a/docs/iris/src/whatsnew/1.10.rst +++ b/docs/iris/src/whatsnew/1.10.rst @@ -1,14 +1,18 @@ -What's new in Iris 1.10 -*********************** +v1.10 (05 Sep 2016) +********************* -:Release: 1.10 -:Date: 5th September 2016 - -This document explains the new/changed features of Iris in version 1.10 +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.10 features -================== + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + .. _iris_grib_added: * Support has now been added for the @@ -19,11 +23,11 @@ Iris 1.10 features iris module :mod:`iris.fileformats.grib`. * The capabilities of ``iris_grib`` are essentially the same as the existing - :mod:`iris.fileformats.grib` when used with ``iris.FUTURE.strict_grib_load=True``, - with only small detail differences. + :mod:`iris.fileformats.grib` when used with + ``iris.FUTURE.strict_grib_load=True``, with only small detail differences. - * The old :mod:`iris.fileformats.grib` module is now deprecated and may shortly be - removed. + * The old :mod:`iris.fileformats.grib` module is now deprecated and may + shortly be removed. * If you are already using the recommended :data:`iris.FUTURE` setting ``iris.FUTURE.strict_grib_load=True`` this should not cause problems, as @@ -44,79 +48,204 @@ Iris 1.10 features any problems you uncover, such as files that will no longer load with the new implementation. -* :meth:`iris.experimental.regrid.PointInCell.regridder` now works across coordinate systems, including non latlon systems. Additionally, the requirement that the source data X and Y coordinates be 2D has been removed. NB: some aspects of this change are backwards incompatible. -* Plotting non-Gregorian calendars is now supported. This adds `nc_time_axis `_ as a dependency. -* Promoting a scalar coordinate to a dimension coordinate with :func:`iris.util.new_axis` no longer loads deferred data. -* The parsing functionality for Cell Methods from netCDF files is available as part of the :mod:`iris.fileformats.netcdf` module as :func:`iris.fileformats.netcdf.parse_cell_methods`. -* Support for the NameIII Version 2 file format has been added. -* Loading netcdf data in Mercator and Stereographic projections now accepts optional extra projection parameter attributes (``false_easting``, ``false_northing`` and ``scale_factor_at_projection_origin``), if they match the default values. +* :meth:`iris.experimental.regrid.PointInCell.regridder` now works across + coordinate systems, including non latlon systems. Additionally, the + requirement that the source data X and Y coordinates be 2D has been removed. + NB: some aspects of this change are backwards incompatible. - * NetCDF files which define a Mercator projection where the ``false_easting``, ``false_northing`` and ``scale_factor_at_projection_origin`` match the defaults will have the projection loaded correctly. Otherwise, a warning will be issued for each parameter that does not match the default and the projection will not be loaded. - * NetCDF files which define a Steroegraphic projection where the ``scale_factor_at_projection_origin`` is equal to 1.0 will have the projection loaded correctly. Otherwise, a warning will be issued and the projection will not be loaded. +* Plotting non-Gregorian calendars is now supported. This adds + `nc_time_axis `_ as a dependency. -* The :mod:`iris.plot` routines :func:`~iris.plot.contour`, :func:`~iris.plot.contourf`, :func:`~iris.plot.outline`, :func:`~iris.plot.pcolor`, :func:`~iris.plot.pcolormesh` and :func:`~iris.plot.points` now support plotting cubes with anonymous dimensions by specifying the *numeric index* of the anonymous dimension within the ``coords`` keyword argument. +* Promoting a scalar coordinate to a dimension coordinate with + :func:`iris.util.new_axis` no longer loads deferred data. + +* The parsing functionality for Cell Methods from netCDF files is available + as part of the :mod:`iris.fileformats.netcdf` module as + :func:`iris.fileformats.netcdf.parse_cell_methods`. + +* Support for the NameIII Version 2 file format has been added. + +* Loading netcdf data in Mercator and Stereographic projections now accepts + optional extra projection parameter attributes (``false_easting``, + ``false_northing`` and ``scale_factor_at_projection_origin``), if they match + the default values. + + * NetCDF files which define a Mercator projection where the + ``false_easting``, ``false_northing`` and + ``scale_factor_at_projection_origin`` match the defaults will have the + projection loaded correctly. Otherwise, a warning will be issued for each + parameter that does not match the default and the projection will not be + loaded. + + * NetCDF files which define a Steroegraphic projection where the + ``scale_factor_at_projection_origin`` is equal to 1.0 will have the + projection loaded correctly. Otherwise, a warning will be issued and the + projection will not be loaded. + +* The :mod:`iris.plot` routines :func:`~iris.plot.contour`, + :func:`~iris.plot.contourf`, :func:`~iris.plot.outline`, + :func:`~iris.plot.pcolor`, :func:`~iris.plot.pcolormesh` and + :func:`~iris.plot.points` now support plotting cubes with anonymous + dimensions by specifying the *numeric index* of the anonymous dimension + within the ``coords`` keyword argument. Note that the axis of the anonymous dimension will be plotted in index space. -* NetCDF loading and saving now supports Cubes that use the LambertConformal coordinate system. -* The experimental structured Fieldsfile loader :func:`~iris.experimental.fieldsfile.load` has been extended to also load structured PP files. +* NetCDF loading and saving now supports Cubes that use the LambertConformal + coordinate system. - Structured loading is a streamlined operation, offering the benefit of a significantly faster loading alternative to the more generic :func:`iris.load` mechanism. +* The experimental structured Fieldsfile loader + :func:`~iris.experimental.fieldsfile.load` has been extended to also load + structured PP files. - Note that structured loading is not an optimised wholesale replacement of :func:`iris.load`. Structured loading is restricted to input containing contiguously ordered fields for each phenomenon that repeat regularly over the same vertical levels and times. For further details, see :func:`~iris.experimental.fieldsfile.load` + Structured loading is a streamlined operation, offering the benefit of a + significantly faster loading alternative to the more generic + :func:`iris.load` mechanism. + + Note that structured loading is not an optimised wholesale replacement of + :func:`iris.load`. Structured loading is restricted to input containing + contiguously ordered fields for each phenomenon that repeat regularly over + the same vertical levels and times. For further details, see + :func:`~iris.experimental.fieldsfile.load` * :mod:`iris.experimental.regrid_conservative` is now compatible with ESMPy v7. -* Saving zonal (i.e. longitudinal) means to PP files now sets the '64s' bit in LBPROC. + +* Saving zonal (i.e. longitudinal) means to PP files now sets the '64s' bit in + LBPROC. + * Loading of 'little-endian' PP files is now supported. -* All appropriate :mod:`iris.plot` functions now handle an ``axes`` keyword, allowing use of the object oriented matplotlib interface rather than pyplot. -* The ability to pass file format object lists into the rules based load pipeline, as used for GRIB, Fields Files and PP has been added. The :func:`iris.fileformats.pp.load_pairs_from_fields` and :func:`iris.fileformats.grib.load_pairs_from_fields` are provided to produce cubes from such lists. These lists may have been filtered or altered using the appropriate :mod:`iris.fileformats` modules. -* Cubes can now have an 'hour' coordinate added with :meth:`iris.coord_categorisation.add_hour`. -* Time coordinates from PP fields with an lbcode of the form 3xx23 are now correctly encoded with a 360-day calendar. -* The loading from and saving to netCDF of CF cell_measure variables is supported, along with their representation within a Cube as :attr:`~iris.cube.Cube.cell_measures`. -* Cubes with anonymous dimensions can now be concatenated. This can only occur along a dimension that is not anonymous. -* NetCDF saving of ``valid_range``, ``valid_min`` and ``valid_max`` cube attributes is now allowed. + +* All appropriate :mod:`iris.plot` functions now handle an ``axes`` keyword, + allowing use of the object oriented matplotlib interface rather than pyplot. + +* The ability to pass file format object lists into the rules based load + pipeline, as used for GRIB, Fields Files and PP has been added. The + :func:`iris.fileformats.pp.load_pairs_from_fields` and + :func:`iris.fileformats.grib.load_pairs_from_fields` are provided to produce + cubes from such lists. These lists may have been filtered or altered using + the appropriate :mod:`iris.fileformats` modules. + +* Cubes can now have an 'hour' coordinate added with + :meth:`iris.coord_categorisation.add_hour`. + +* Time coordinates from PP fields with an lbcode of the form 3xx23 are now + correctly encoded with a 360-day calendar. + +* The loading from and saving to netCDF of CF cell_measure variables is + supported, along with their representation within a Cube as + :attr:`~iris.cube.Cube.cell_measures`. + +* Cubes with anonymous dimensions can now be concatenated. This can only occur + along a dimension that is not anonymous. + +* NetCDF saving of ``valid_range``, ``valid_min`` and ``valid_max`` cube + attributes is now allowed. + Bugs fixed ========== -* Altered Cell Methods to display coordinate's standard_name rather than var_name where appropriate to avoid human confusion. -* Saving multiple cubes with netCDF4 protected attributes should now work as expected. -* Concatenating cubes with singleton dimensions (dimensions of size one) now works properly. -* Fixed the ``grid_mapping_name`` and ``secant_latitudes`` handling for the LambertConformal coordinate system. -* Fixed bug in :func:`iris.analysis.cartography.project` where the output projection coordinates didn't have units. -* Attempting to use :meth:`iris.sample_data_path` to access a file that isn't actually Iris sample data now raises a more descriptive error. A note about the appropriate use of `sample_data_path` has also been added to the documentation. -* Fixed a bug where regridding or interpolation with the :class:`~iris.analysis.Nearest` scheme returned floating-point results even when the source data was integer typed. It now always returns the same type as the source data. -* Fixed a bug where regridding circular data would ignore any source masking. This affected any regridding using the :class:`~iris.analysis.Linear` and :class:`~iris.analysis.Nearest` schemes, and also :func:`iris.analysis.interpolate.linear`. -* The ``coord_name`` parameter to :func:`~iris.fileformats.rules.scalar_cell_method` is now checked correctly. -* LBPROC is set correctly when a cube containing the minimum of a variable is saved to a PP file. The IA component of LBTIM is set correctly when saving maximum or minimum values. -* The performance of :meth:`iris.cube.Cube.extract` when a list of values is given to an instance of :class:`iris.Constraint` has been improved considerably. -* Fixed a bug with :meth:`iris.cube.Cube.data` where an :class:`numpy.ndarray` was not being returned for scalar cubes with lazy data. -* When saving in netcdf format, the units of 'latitude' and 'longitude' coordinates specified in 'degrees' are saved as 'degrees_north' and 'degrees_east' respectively, as defined in the CF conventions for netCDF files: sections 4.1 and 4.2. -* Fixed a bug with a class of pp files with lbyr == 0, where the date would cause errors when converting to a datetime object (e.g. when printing a cube). - - When processing a pp field with lbtim = 2x, lbyr == lbyrd == 0 and lbmon == lbmond, 'month' and 'month_number' coordinates are created instead of 'time'. - -* Fixed a bug in :meth:`~iris.analysis.calculus.curl` where the sign of the r-component for spherical coordinates was opposite to what was expected. + +* Altered Cell Methods to display coordinate's standard_name rather than + var_name where appropriate to avoid human confusion. + +* Saving multiple cubes with netCDF4 protected attributes should now work as + expected. + +* Concatenating cubes with singleton dimensions (dimensions of size one) now + works properly. + +* Fixed the ``grid_mapping_name`` and ``secant_latitudes`` handling for the + LambertConformal coordinate system. + +* Fixed bug in :func:`iris.analysis.cartography.project` where the output + projection coordinates didn't have units. + +* Attempting to use :meth:`iris.sample_data_path` to access a file that isn't + actually Iris sample data now raises a more descriptive error. A note about + the appropriate use of `sample_data_path` has also been added to the + documentation. + +* Fixed a bug where regridding or interpolation with the + :class:`~iris.analysis.Nearest` scheme returned floating-point results even + when the source data was integer typed. It now always returns the same type + as the source data. + +* Fixed a bug where regridding circular data would ignore any source masking. + This affected any regridding using the :class:`~iris.analysis.Linear` and + :class:`~iris.analysis.Nearest` schemes, and also + :func:`iris.analysis.interpolate.linear`. + +* The ``coord_name`` parameter to + :func:`~iris.fileformats.rules.scalar_cell_method` is now checked correctly. + +* LBPROC is set correctly when a cube containing the minimum of a variable is + saved to a PP file. The IA component of LBTIM is set correctly when saving + maximum or minimum values. + +* The performance of :meth:`iris.cube.Cube.extract` when a list of values is + given to an instance of :class:`iris.Constraint` has been improved + considerably. + +* Fixed a bug with :meth:`iris.cube.Cube.data` where an :class:`numpy.ndarray` + was not being returned for scalar cubes with lazy data. + +* When saving in netcdf format, the units of 'latitude' and 'longitude' + coordinates specified in 'degrees' are saved as 'degrees_north' and + 'degrees_east' respectively, as defined in the CF conventions for netCDF + files: sections 4.1 and 4.2. + +* Fixed a bug with a class of pp files with lbyr == 0, where the date would + cause errors when converting to a datetime object (e.g. when printing a cube). + + When processing a pp field with lbtim = 2x, lbyr == lbyrd == 0 and + lbmon == lbmond, 'month' and 'month_number' coordinates are created instead + of 'time'. + +* Fixed a bug in :meth:`~iris.analysis.calculus.curl` where the sign of the + r-component for spherical coordinates was opposite to what was expected. + * A bug that prevented cube printing in some cases has been fixed. -* Fixed a bug where a deepcopy of a :class:`~iris.coords.DimCoord` would have writable ``points`` and ``bounds`` arrays. These arrays can now no longer be modified in-place. -* Concatenation no longer occurs when the auxiliary coordinates of the cubes do not match. This check is not applied to AuxCoords that span the dimension the concatenation is occuring along. This behaviour can be switched off by setting the ``check_aux_coords`` kwarg in :meth:`iris.cube.CubeList.concatenate` to False. -* Fixed a bug in :meth:`iris.cube.Cube.subset` where an exception would be thrown while trying to subset over a non-dimensional scalar coordinate. + +* Fixed a bug where a deepcopy of a :class:`~iris.coords.DimCoord` would have + writable ``points`` and ``bounds`` arrays. These arrays can now no longer be + modified in-place. + +* Concatenation no longer occurs when the auxiliary coordinates of the cubes do + not match. This check is not applied to AuxCoords that span the dimension the + concatenation is occuring along. This behaviour can be switched off by + setting the ``check_aux_coords`` kwarg in + :meth:`iris.cube.CubeList.concatenate` to False. + +* Fixed a bug in :meth:`iris.cube.Cube.subset` where an exception would be + thrown while trying to subset over a non-dimensional scalar coordinate. + Incompatible changes ==================== -* The source and target for :meth:`iris.experimental.regrid.PointInCell.regridder` must now have defined coordinate systems (i.e. not ``None``). Additionally, the source data X and Y coordinates must have the same cube dimensions. + +* The source and target for + :meth:`iris.experimental.regrid.PointInCell.regridder` must now have defined + coordinate systems (i.e. not ``None``). Additionally, the source data X and Y + coordinates must have the same cube dimensions. + Deprecations ============ + * Deprecated the :class:`iris.Future` option ``iris.FUTURE.strict_grib_load``. This only affected the module :mod:`iris.fileformats.grib`, which is itself now deprecated. Please see :ref:`iris_grib package `, above. + * Deprecated the module :mod:`iris.fileformats.grib`. The new package `iris_grib `_ replaces this fuctionality, which will shortly be removed. Please see :ref:`iris_grib package `, above. -* The use of :data:`iris.config.SAMPLE_DATA_DIR` has been deprecated and replaced by the now importable `iris_sample_data `_ package. + +* The use of :data:`iris.config.SAMPLE_DATA_DIR` has been deprecated and + replaced by the now importable + `iris_sample_data `_ package. * Deprecated the module :mod:`iris.analysis.interpolate`. This contains the following public items, all of which are now deprecated and @@ -132,21 +261,38 @@ Deprecations Please use the replacement facilities individually noted in the module documentation for :mod:`iris.analysis.interpolate` + * The method :meth:`iris.cube.Cube.regridded` has been deprecated. Please use :meth:`iris.cube.Cube.regrid` instead (see :meth:`~iris.cube.Cube.regridded` for details). -* Deprecated :data:`iris.fileformats.grib.hindcast_workaround` and :class:`iris.fileformats.grib.GribWrapper`. The class :class:`iris.fileformats.grib.message.GribMessage` provides alternative means of working with GRIB message instances. + +* Deprecated :data:`iris.fileformats.grib.hindcast_workaround` and + :class:`iris.fileformats.grib.GribWrapper`. The class + :class:`iris.fileformats.grib.message.GribMessage` provides alternative means + of working with GRIB message instances. + * Deprecated the module :mod:`iris.fileformats.ff`. Please use the replacement facilities in module :mod:`iris.fileformats.um` : - * :func:`iris.fileformats.um.um_to_pp` replaces :class:`iris.fileformats.ff.FF2PP`. - * :func:`iris.fileformats.um.load_cubes` replaces :func:`iris.fileformats.ff.load_cubes`. - * :func:`iris.fileformats.um.load_cubes_32bit_ieee` replaces :func:`iris.fileformats.ff.load_cubes_32bit_ieee`. + * :func:`iris.fileformats.um.um_to_pp` replaces + :class:`iris.fileformats.ff.FF2PP`. + * :func:`iris.fileformats.um.load_cubes` replaces + :func:`iris.fileformats.ff.load_cubes`. + * :func:`iris.fileformats.um.load_cubes_32bit_ieee` replaces + :func:`iris.fileformats.ff.load_cubes_32bit_ieee`. + + All other public components are generally deprecated and will be removed in a + future release. + +* The :func:`iris.fileformats.pp.as_pairs` and + :func:`iris.fileformats.grib.as_pairs` are deprecated. These are replaced + with :func:`iris.fileformats.pp.save_pairs_from_cube` and + :func:`iris.fileformats.grib.save_pairs_from_cube`. - All other public components are generally deprecated and will be removed in a future release. +* ``iris.fileformats.pp_packing`` has been deprecated. Please install the + separate `mo_pack `_ package instead. + This provides the same functionality. -* The :func:`iris.fileformats.pp.as_pairs` and :func:`iris.fileformats.grib.as_pairs` are deprecated. These are replaced with :func:`iris.fileformats.pp.save_pairs_from_cube` and :func:`iris.fileformats.grib.save_pairs_from_cube`. -* ``iris.fileformats.pp_packing`` has been deprecated. Please install the separate `mo_pack `_ package instead. This provides the same functionality. * Deprecated logging functions (currently used only for rules logging): :data:`iris.config.iris.config.RULE_LOG_DIR`, :data:`iris.config.iris.config.RULE_LOG_IGNORE` and @@ -163,14 +309,37 @@ Deprecations :class:`iris.fileformats.rules.RulesContainer` and :func:`iris.fileformats.rules.calculate_forecast_period`. -* Deprecated the custom pp save rules mechanism implemented by the functions :func:`iris.fileformats.pp.add_save_rules` and :func:`iris.fileformats.pp.reset_save_rules`. The functions :func:`iris.fileformats.pp.as_fields`, :func:`iris.fileformats.pp.as_pairs` and :func:`iris.fileformats.pp.save_fields` provide alternative means of achieving the same ends. +* Deprecated the custom pp save rules mechanism implemented by the functions + :func:`iris.fileformats.pp.add_save_rules` and + :func:`iris.fileformats.pp.reset_save_rules`. The functions + :func:`iris.fileformats.pp.as_fields`, :func:`iris.fileformats.pp.as_pairs` + and :func:`iris.fileformats.pp.save_fields` provide alternative means of + achieving the same ends. + + +Documentation +============= + +* It is now clear that repeated values will form a group under + :meth:`iris.cube.Cube.aggregated_by` even if they aren't consecutive. Hence, + the documentation for :mod:`iris.cube` has been changed to reflect this. + +* The documentation for :meth:`iris.analysis.calculus.curl` has been updated + for clarity. + +* False claims about :meth:`iris.fileformats.pp.save`, + :meth:`iris.fileformats.pp.as_pairs`, and + :meth:`iris.fileformats.pp.as_fields` being able to take instances of + :class:`iris.cube.CubeList` as inputs have been removed. + +* A new code example + :ref:`sphx_glr_generated_gallery_meteorology_plot_wind_speed.py`, + demonstrating the use of a quiver plot to display wind speeds over Lake + Victoria, has been added. + +* The docstring for :data:`iris.analysis.SUM` has been updated to explicitly + state that weights passed to it aren't normalised internally. -Documentation Changes -===================== -* It is now clear that repeated values will form a group under :meth:`iris.cube.Cube.aggregated_by` even if they aren't consecutive. Hence, the documentation for :mod:`iris.cube` has been changed to reflect this. -* The documentation for :meth:`iris.analysis.calculus.curl` has been updated for clarity. -* False claims about :meth:`iris.fileformats.pp.save`, :meth:`iris.fileformats.pp.as_pairs`, and :meth:`iris.fileformats.pp.as_fields` being able to take instances of :class:`iris.cube.CubeList` as inputs have been removed. -* A new code example :ref:`sphx_glr_generated_gallery_meteorology_plot_wind_speed.py`, demonstrating the use of a quiver plot to display wind speeds over Lake Victoria, has been added. -* The docstring for :data:`iris.analysis.SUM` has been updated to explicitly state that weights passed to it aren't normalised internally. -* A note regarding the impossibility of partially collapsing multi-dimensional coordinates has been added to the user guide. +* A note regarding the impossibility of partially collapsing multi-dimensional + coordinates has been added to the user guide. diff --git a/docs/iris/src/whatsnew/1.11.rst b/docs/iris/src/whatsnew/1.11.rst index 560bb070327..d04355b800b 100644 --- a/docs/iris/src/whatsnew/1.11.rst +++ b/docs/iris/src/whatsnew/1.11.rst @@ -1,31 +1,45 @@ -What's new in Iris 1.11 -*********************** +v1.11 (29 Oct 2016) +********************* -:Release: 1.11 -:Date: 2016-11-28 - -This document explains the new/changed features of Iris in version 1.11 +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.11 features -================== -* If available, display the ``STASH`` code instead of ``unknown / (unknown)`` when printing cubes - with no ``standard_name`` and no ``units``. + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + +* If available, display the ``STASH`` code instead of ``unknown / (unknown)`` + when printing cubes with no ``standard_name`` and no ``units``. + * Support for saving to netCDF with data packing has been added. -* The coordinate system :class:`iris.coord_systems.LambertAzimuthalEqualArea` has been added with NetCDF saving support. + +* The coordinate system :class:`iris.coord_systems.LambertAzimuthalEqualArea` + has been added with NetCDF saving support. Bugs fixed ========== -* Fixed a floating point tolerance bug in :func:`iris.experimental.regrid.regrid_area_weighted_rectilinear_src_and_grid` + +* Fixed a floating point tolerance bug in + :func:`iris.experimental.regrid.regrid_area_weighted_rectilinear_src_and_grid` for wrapped longitudes. -* Allow :func:`iris.util.new_axis` to promote the nominated scalar coordinate of a cube - with a scalar masked constant data payload. -* Fixed a bug where :func:`iris.util._is_circular` would erroneously return false - when coordinate values are decreasing. -* When saving to NetCDF, the existing behaviour of writing string attributes as ASCII has been - maintained across known versions of netCDF4-python. - -Documentation changes -===================== + +* Allow :func:`iris.util.new_axis` to promote the nominated scalar coordinate + of a cube with a scalar masked constant data payload. + +* Fixed a bug where :func:`iris.util._is_circular` would erroneously return + false when coordinate values are decreasing. + +* When saving to NetCDF, the existing behaviour of writing string attributes + as ASCII has been maintained across known versions of netCDF4-python. + + +Documentation +============= + * Fuller doc-string detail added to :func:`iris.analysis.cartography.unrotate_pole` and :func:`iris.analysis.cartography.rotate_pole`. diff --git a/docs/iris/src/whatsnew/1.12.rst b/docs/iris/src/whatsnew/1.12.rst index bd02f0937ab..1d7fc8f9780 100644 --- a/docs/iris/src/whatsnew/1.12.rst +++ b/docs/iris/src/whatsnew/1.12.rst @@ -1,14 +1,18 @@ -What's new in Iris 1.12 -*********************** +v1.12 (31 Jan 2017) +********************* -:Release: 1.12 -:Date: 2017-01-30 - -This document explains the new/changed features of Iris in version 1.12 +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.12 features -================== + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + .. _showcase: .. admonition:: Showcase Feature: New regridding schemes @@ -121,11 +125,13 @@ Iris 1.12 features Deprecations ============ + * The module :mod:`iris.experimental.fieldsfile` has been deprecated, in favour of the new fast-loading mechanism provided by :meth:`iris.fileformats.um.structured_um_loading`. -Documentation changes -===================== +Documentation +============= + * Corrected documentation of :class:`iris.analysis.AreaWeighted` scheme to make the usage scope clearer. diff --git a/docs/iris/src/whatsnew/1.13.rst b/docs/iris/src/whatsnew/1.13.rst index 7435e5bb075..30b3731d967 100644 --- a/docs/iris/src/whatsnew/1.13.rst +++ b/docs/iris/src/whatsnew/1.13.rst @@ -1,37 +1,78 @@ -What's new in Iris 1.13 -*********************** +v1.13 (17 May 2017) +************************* -:Release: 1.13 -:Date: 2017-05-17 +This document explains the changes made to Iris for this release +(:doc:`View all changes `.) -This document explains the new/changed features of Iris in version 1.13 -(:doc:`View all changes `.) +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== -Iris 1.13 features -================== +* Allow the reading of NAME trajectories stored by time instead of by particle + number. -* Allow the reading of NAME trajectories stored by time instead of by particle number. * An experimental link to python-stratify via :mod:`iris.experimental.stratify`. -* Data arrays may be shared between cubes, and subsets of cubes, by using the :meth:`iris.cube.share_data` flag. + +* Data arrays may be shared between cubes, and subsets of cubes, by using the + :meth:`iris.cube.share_data` flag. Bug fixes ========= -* The bounds are now set correctly on the longitude coordinate if a zonal mean diagnostic has been loaded from a PP file as per the CF Standard. -* NetCDF loading will now determine whether there is a string-valued scalar label, i.e. a character variable that only has one dimension (the length of the string), and interpret this correctly. -* A line plot of geographic coordinates (e.g. drawing a trajectory) wraps around the edge of the map cleanly, rather than plotting a segment straight across the map. -* When saving to PP, lazy data is preserved when generating PP fields from cubes so that a list of cubes can be saved to PP without excessive memory requirements. -* An error is now correctly raised if a user tries to perform an arithmetic operation on two cubes with mismatching coordinates. Previously these cases were caught by the add and subtract operators, and now it is also caught by the multiply and divide operators. -* Limited area Rotated Pole datasets where the data range is ``0 <= lambda < 360``, for example as produced in New Zealand, are plotted over a sensible map extent by default. -* Removed the potential for a RuntimeWarning: overflow encountered in ``int_scalars`` which was missed during collapsed calculations. This could trip up unwary users of limited data types, such as int32 for very large numbers (e.g. seconds since 1970). -* The CF conventions state that certain ``formula_terms`` terms may be omitted and assumed to be zero (http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#dimensionless-v-coord) so Iris now allows factories to be constructed with missing terms. -* In the User Guide's contour plot example, clabel inline is set to be False so that it renders correctly, avoiding spurious horizontal lines across plots, although this does make labels a little harder to see. -* The computation of area weights has been changed to a more numerically stable form. The previous form converted latitude to colatitude and used difference of cosines in the cell area computation. This formulation uses latitude and difference of sines. The conversion from latitude to colatitude at lower precision causes errors when computing the cell areas. +* The bounds are now set correctly on the longitude coordinate if a zonal mean + diagnostic has been loaded from a PP file as per the CF Standard. + +* NetCDF loading will now determine whether there is a string-valued scalar + label, i.e. a character variable that only has one dimension (the length of + the string), and interpret this correctly. + +* A line plot of geographic coordinates (e.g. drawing a trajectory) wraps + around the edge of the map cleanly, rather than plotting a segment straight + across the map. + +* When saving to PP, lazy data is preserved when generating PP fields from + cubes so that a list of cubes can be saved to PP without excessive memory + requirements. + +* An error is now correctly raised if a user tries to perform an arithmetic + operation on two cubes with mismatching coordinates. Previously these cases + were caught by the add and subtract operators, and now it is also caught by + the multiply and divide operators. + +* Limited area Rotated Pole datasets where the data range is + ``0 <= lambda < 360``, for example as produced in New Zealand, are plotted + over a sensible map extent by default. + +* Removed the potential for a RuntimeWarning: overflow encountered in + ``int_scalars`` which was missed during collapsed calculations. This could + trip up unwary users of limited data types, such as int32 for very large + numbers (e.g. seconds since 1970). + +* The CF conventions state that certain ``formula_terms`` terms may be omitted + and assumed to be zero + (http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#dimensionless-v-coord) + so Iris now allows factories to be constructed with missing terms. + +* In the User Guide's contour plot example, clabel inline is set to be False + so that it renders correctly, avoiding spurious horizontal lines across + plots, although this does make labels a little harder to see. + +* The computation of area weights has been changed to a more numerically + stable form. The previous form converted latitude to colatitude and used + difference of cosines in the cell area computation. This formulation uses + latitude and difference of sines. The conversion from latitude to colatitude + at lower precision causes errors when computing the cell areas. + Testing ======= -* Iris has adopted conda-forge to provide environments for continuous integration testing. +* Iris has adopted conda-forge to provide environments for continuous + integration testing. diff --git a/docs/iris/src/whatsnew/1.2.rst b/docs/iris/src/whatsnew/1.2.rst index 720ae733763..982a68add66 100644 --- a/docs/iris/src/whatsnew/1.2.rst +++ b/docs/iris/src/whatsnew/1.2.rst @@ -1,16 +1,17 @@ -What's new in Iris 1.2 -********************** +v1.2 (28 Feb 2013) +****************** -:Release: 1.2.0 -:Date: 7th March 2013 - -This document explains the new/changed features of Iris in version 1.2. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.2 features -================= -A summary of the main features added with version 1.2: +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== * :meth:`iris.cube.Cube.convert_units()` and :meth:`iris.coords.Coord.convert_units()` have been added. This is @@ -18,6 +19,7 @@ A summary of the main features added with version 1.2: another. For example, to convert a cube in kelvin to celsius, one can now call cube.convert_units('celsius'). The operation is in-place and if the units are not convertible an exception will be raised. + * :attr:`iris.cube.Cube.var_name`, :attr:`iris.coords.Coord.var_name` and :attr:`iris.aux_factory.AuxCoordFactory.var_name` attributes have been added. This attribute represents the CF variable name of the object. It is populated @@ -25,42 +27,57 @@ A summary of the main features added with version 1.2: var_name keyword argument has also been added to the :meth:`iris.cube.Cube.coord()`, :meth:`iris.cube.Cube.coords()` and :meth:`iris.cube.Cube.aux_factory()` methods. + * :meth:`iris.coords.Coord.is_compatible()` has been added. This method is used to determine whether two coordinates are sufficiently alike to allow operations such as :meth:`iris.coords.Coord.intersect()` and :func:`iris.analysis.interpolate.regrid()` to take place. A corresponding method for cubes, :meth:`iris.cube.Cube.is_compatible()`, has also been added. + * Printing a :class:`~iris.cube.Cube` is now more user friendly with regards to dates and time. All *time* and *forecast_reference_time* scalar coordinates now display human readable date/time information. + * The units of a :class:`~iris.cube.Cube` are now shown when it is printed. + * The area weights calculated by :func:`iris.analysis.cartography.area_weights` may now be normalised relative to the total grid area. -* Weights may now be passed to :meth:`iris.cube.Cube.rolling_window` aggregations, - thus allowing arbitrary digital filters to be applied to a :class:`~iris.cube.Cube`. + +* Weights may now be passed to :meth:`iris.cube.Cube.rolling_window` + aggregations, thus allowing arbitrary digital filters to be applied to a + :class:`~iris.cube.Cube`. + Bugs fixed ----------- +========== + * The GRIB hindcast interpretation of negative forecast times can be enabled via the :data:`iris.fileformats.grib.hindcast_workaround` flag. + * The NIMROD file loader has been extended to cope with orography vertical coordinates. + Incompatible changes --------------------- +==================== + * The deprecated :attr:`iris.cube.Cube.unit` and :attr:`iris.coords.Coord.unit` attributes have been removed. + Deprecations ------------- +============ + * The :meth:`iris.coords.Coord.unit_converted()` method has been deprecated. Users should make a copy of the coordinate using :meth:`iris.coords.Coord.copy()` and then call the :meth:`iris.coords.Coord.convert_units()` method of the new coordinate. + * With the addition of the var_name attribute the signatures of DimCoord and AuxCoord have changed. This should have no impact if you are providing parameters as keyword arguments, but it may cause issues if you are relying on the position/order of the arguments. + * Iteration over a :class:`~iris.cube.Cube` has been deprecated. Instead, users should use :meth:`iris.cube.Cube.slices`. diff --git a/docs/iris/src/whatsnew/1.3.rst b/docs/iris/src/whatsnew/1.3.rst index dbea08ad039..9e898a2b232 100644 --- a/docs/iris/src/whatsnew/1.3.rst +++ b/docs/iris/src/whatsnew/1.3.rst @@ -1,65 +1,42 @@ -What's new in Iris 1.3 -********************** +v1.3 (27 Mar 2013) +****************** -:Release: 1.3.0 -:Date: 27 March 2013 - -This document explains the new/changed features of Iris in version 1.3. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.3 features -================= -A summary of the main features added with version 1.3: +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== * Experimental support for :ref:`loading ABF/ABL files`. + * Support in :func:`iris.analysis.interpolate.linear` for longitude ranges other than [-180, 180]. + * Support for :ref:`customised CF profiles` on export to netCDF. + * The documentation now includes guidance on :ref:`how to cite Iris`. + * The ability to calculate the exponential of a Cube, via :func:`iris.analysis.maths.exp()`. + * Experimental support for :ref:`concatenating Cubes` along existing dimensions via :func:`iris.experimental.concatenate.concatenate()`. -Bugs fixed ----------- -* Printing a Cube now supports Unicode attribute values. -* PP export now sets LBMIN correctly. -* Converting between reference times now works correctly for - units with non-Gregorian calendars. -* Slicing a :class:`~iris.cube.CubeList` now returns a - :class:`~iris.cube.CubeList` instead of a normal list. - -Incompatible changes --------------------- -* N/A - -Deprecations ------------- -* The boolean methods/properties on the :class:`~iris.unit.Unit` class - have been updated to `is_...()` methods, in line with the project's - naming conventions. - - ====================================== =========================================== - Deprecated property/method New method - ====================================== =========================================== - :meth:`~iris.unit.Unit.convertible()` :meth:`~iris.unit.Unit.is_convertible()` - :attr:`~iris.unit.Unit.dimensionless` :meth:`~iris.unit.Unit.is_dimensionless()` - :attr:`~iris.unit.Unit.no_unit` :meth:`~iris.unit.Unit.is_no_unit()` - :attr:`~iris.unit.Unit.time_reference` :meth:`~iris.unit.Unit.is_time_reference()` - :attr:`~iris.unit.Unit.unknown` :meth:`~iris.unit.Unit.is_unknown()` - ====================================== =========================================== - .. _whats-new-abf: Loading ABF/ABL files -===================== +--------------------- Support for the ABF and ABL file formats (as `defined `_ by the @@ -80,7 +57,7 @@ For example:: .. _whats-new-cf-profile: Customised CF profiles -====================== +---------------------- Iris now provides hooks in the CF-netCDF export process to allow user-defined routines to check and/or modify the representation in the @@ -89,10 +66,13 @@ netCDF file. The following keys within the ``iris.site_configuration`` dictionary have been **reserved** as hooks to *external* user-defined CF profile functions: - * ``cf_profile`` injests a :class:`iris.cube.Cube` for analysis and returns a profile result - * ``cf_patch`` modifies the CF-netCDF file associated with export of the :class:`iris.cube.Cube` + * ``cf_profile`` injests a :class:`iris.cube.Cube` for analysis and returns a + profile result + * ``cf_patch`` modifies the CF-netCDF file associated with export of the + :class:`iris.cube.Cube` -The ``iris.site_configuration`` dictionary should be configured via the ``iris/site_config.py`` file. +The ``iris.site_configuration`` dictionary should be configured via the +``iris/site_config.py`` file. For further implementation details see ``iris/fileformats/netcdf.py``. @@ -100,7 +80,7 @@ For further implementation details see ``iris/fileformats/netcdf.py``. .. _whats-new-concat: Cube concatenation -================== +------------------ Iris now provides initial support for concatenating Cubes along one or more existing dimensions. Currently this will force the data to be @@ -126,3 +106,33 @@ combine these into a single Cube as follows:: As this is an experimental feature, your feedback is especially welcome. +Bugs fixed +========== + +* Printing a Cube now supports Unicode attribute values. + +* PP export now sets LBMIN correctly. + +* Converting between reference times now works correctly for + units with non-Gregorian calendars. + +* Slicing a :class:`~iris.cube.CubeList` now returns a + :class:`~iris.cube.CubeList` instead of a normal list. + + +Deprecations +============ + +* The boolean methods/properties on the :class:`~iris.unit.Unit` class + have been updated to `is_...()` methods, in line with the project's + naming conventions. + + ====================================== =========================================== + Deprecated property/method New method + ====================================== =========================================== + :meth:`~iris.unit.Unit.convertible()` :meth:`~iris.unit.Unit.is_convertible()` + :attr:`~iris.unit.Unit.dimensionless` :meth:`~iris.unit.Unit.is_dimensionless()` + :attr:`~iris.unit.Unit.no_unit` :meth:`~iris.unit.Unit.is_no_unit()` + :attr:`~iris.unit.Unit.time_reference` :meth:`~iris.unit.Unit.is_time_reference()` + :attr:`~iris.unit.Unit.unknown` :meth:`~iris.unit.Unit.is_unknown()` + ====================================== =========================================== diff --git a/docs/iris/src/whatsnew/1.4.rst b/docs/iris/src/whatsnew/1.4.rst index 3586b05a5cc..23b70b10c97 100644 --- a/docs/iris/src/whatsnew/1.4.rst +++ b/docs/iris/src/whatsnew/1.4.rst @@ -1,96 +1,114 @@ -What's new in Iris 1.4 -********************** +v1.4 (14 Jun 2013) +****************** -:Release: 1.4.0 -:Date: 14 June 2013 - -This document explains the new/changed features of Iris in version 1.4. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.4 features -================= -A summary of the main features added with version 1.4: +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== * Multiple cubes can now be exported to a NetCDF file. + * Correct nearest-neighbour calculation with circular coords. + * :ref:`Experimental regridding enhancements`. + * :ref:`Iris-Pandas interoperability`. + * NIMROD level type 12 (levels below ground) can now be loaded. + * :ref:`Load cubes from the internet via OPeNDAP`. + * :ref:`GeoTiff export (experimental)`. + * :ref:`Cube merge update`. + * :ref:`Unambiguous season year naming`. + * NIMROD files with multiple fields and period of interest can now be loaded. + * Missing values are now handled when loading GRIB messages. + * PP export rule to calculate forecast period. + * :func:`~iris.cube.Cube.aggregated_by` now maintains array masking. + * IEEE 32bit fieldsfiles can now be loaded. + * NetCDF transverse mercator and climatology data can now be loaded. + * Polar stereographic GRIB data can now be loaded. + * :ref:`Cubes with no vertical coord can now be exported to GRIB`. + * :ref:`Simplified resource configuration`. + * :ref:`Extended GRIB parameter translation`. + * Added an optimisation for single-valued coordinate constraints. + * :ref:`One dimensional linear interpolation fix`. -* :ref:`Fix for iris.analysis.calculus.differentiate`. -* Fixed pickling of cubes with 2D aux coords from NetCDF. -* Fixed bug which ignored the "coords" keyword for certain plots. -* Use the latest release of Cartopy, v0.8.0. +* :ref:`Fix for iris.analysis.calculus.differentiate`. -Incompatible changes --------------------- -* As part of simplifying the mechanism for accessing test data, - :func:`iris.io.select_data_path`, :data:`iris.config.DATA_REPOSITORY`, - :data:`iris.config.MASTER_DATA_REPOSITORY` and - :data:`iris.config.RESOURCE_DIR` have been removed. +* Fixed pickling of cubes with 2D aux coords from NetCDF. -Deprecations ------------- -* The *add_custom_season_** functions from :mod:`~iris.coord_categorisation` have been deprecated in favour of adding their functionality to the *add_season_** functions +* Fixed bug which ignored the "coords" keyword for certain plots. +* Use the latest release of Cartopy, v0.8.0. .. _OPeNDAP: http://www.opendap.org/about - - .. _exp-regrid: Experimental regridding enhancements -==================================== +------------------------------------ + +Bilinear, area-weighted and area-conservative regridding functions are now +available in :mod:`iris.experimental`. These functions support masked data and +handle derived coordinates such as hybrid height. The final API is still in +development. -Bilinear, area-weighted and area-conservative regridding functions are now available in -:mod:`iris.experimental`. These functions support masked data and handle -derived coordinates such as hybrid height. The final API is still in development. In the meantime: + Bilinear rectilinear regridding ------------------------------- + :func:`~iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid` -can be used to regrid a cube onto a horizontal grid defined in a different coordinate system. -The data values are calculated using bilinear interpolation. +can be used to regrid a cube onto a horizontal grid defined in a differentiate +coordinate system. The data values are calculated using bilinear interpolation. For example:: from iris.experimental.regrid import regrid_bilinear_rectilinear_src_and_grid regridded_cube = regrid_bilinear_rectilinear_src_and_grid(source_cube, target_grid_cube) + Area-weighted regridding ------------------------ -:func:`~iris.experimental.regrid.regrid_area_weighted_rectilinear_src_and_grid` can be used to regrid a cube -such that the data values of the resulting cube are calculated using the -area-weighted mean. + +:func:`~iris.experimental.regrid.regrid_area_weighted_rectilinear_src_and_grid` +can be used to regrid a cube such that the data values of the resulting cube +are calculated using the area-weighted mean. For example:: from iris.experimental.regrid import regrid_area_weighted_rectilinear_src_and_grid as regrid_area_weighted regridded_cube = regrid_area_weighted(source_cube, target_grid_cube) + Area-conservative regridding ---------------------------- + :func:`~iris.experimental.regrid_conservative.regrid_conservative_via_esmpy` -can be used for area-conservative regridding between geographical coordinate systems. -This uses the ESMF library functions, via the ESMPy interface. +can be used for area-conservative regridding between geographical coordinate +systems. This uses the ESMF library functions, via the ESMPy interface. For example:: @@ -101,7 +119,8 @@ For example:: .. _iris-pandas: Iris-Pandas interoperablilty -============================ +---------------------------- + Conversion to and from Pandas Series_ and DataFrames_ is now available. See :mod:`iris.pandas` for more details. @@ -112,7 +131,8 @@ See :mod:`iris.pandas` for more details. .. _load-opendap: Load cubes from the internet via OPeNDAP -======================================== +---------------------------------------- + Cubes can now be loaded directly from the internet, via OPeNDAP_. For example:: @@ -123,8 +143,10 @@ For example:: .. _geotiff_export: GeoTiff export -============== -With this experimental feature, two dimensional cubes can now be exported to GeoTiff files. +-------------- + +With this experimental feature, two dimensional cubes can now be exported to +GeoTiff files. For example:: @@ -139,17 +161,20 @@ For example:: .. _cube-merge-update: Cube merge update -================= +----------------- + Cube merging now favours numerical coordinates over string coordinates to describe a dimension, and :class:`~iris.coords.DimCoord` over :class:`~iris.coords.AuxCoord`. These modifications prevent the error: -*"No functional relationship between separable and inseparable candidate dimensions"*. +*"No functional relationship between separable and inseparable candidate +dimensions"*. .. _season-year-name: Unambiguous season year naming -============================== +------------------------------ + The default names of categorisation coordinates are now less ambiguous. For example, :func:`~iris.coord_categorisation.add_month_number` and :func:`~iris.coord_categorisation.add_month_fullname` now create @@ -159,15 +184,18 @@ For example, :func:`~iris.coord_categorisation.add_month_number` and .. _grib-novert: Cubes with no vertical coord can now be exported to GRIB -======================================================== +-------------------------------------------------------- + Iris can now export cubes with no vertical coord to GRIB. -The solution is still under discussion: See https://github.com/SciTools/iris/issues/519. +The solution is still under discussion: See +https://github.com/SciTools/iris/issues/519. .. _simple_cfg: Simplified resource configuration -================================= +--------------------------------- + A new configuration variable called :data:`iris.config.TEST_DATA_DIR` has been added, replacing the previous combination of :data:`iris.config.MASTER_DATA_REPOSITORY` and @@ -180,7 +208,8 @@ be set by adding a ``test_data_dir`` entry to the ``Resources`` section of .. _grib_params: Extended GRIB parameter translation -=================================== +----------------------------------- + - More GRIB2 params are recognised on input. - Now translates some codes on GRIB2 output. - Some GRIB2 params may load with a different standard_name. @@ -190,16 +219,37 @@ Extended GRIB parameter translation .. _one-d-linear: One dimensional linear interpolation fix -======================================== -:func:`~iris.analysis.interpolate.linear` can now extrapolate from a single point -assuming a gradient of zero. This prevents an issue when loading cross sections -with a hybrid height coordinate, on a staggered grid and only a single orography field. +---------------------------------------- + +:func:`~iris.analysis.interpolate.linear` can now extrapolate from a single +point assuming a gradient of zero. This prevents an issue when loading cross +sections with a hybrid height coordinate, on a staggered grid and only a single +orography field. .. _calc-diff-fix: Fix for iris.analysis.calculus.differentiate -============================================= -A bug in :func:`~iris.analysis.calculus.differentiate` that had the potential to cause -the loss of coordinate metadata when calculating the curl or the derivative of a cube has been fixed. +-------------------------------------------- + +A bug in :func:`~iris.analysis.calculus.differentiate` that had the potential +to cause the loss of coordinate metadata when calculating the curl or the +derivative of a cube has been fixed. + + +Incompatible changes +==================== + +* As part of simplifying the mechanism for accessing test data, + :func:`iris.io.select_data_path`, :data:`iris.config.DATA_REPOSITORY`, + :data:`iris.config.MASTER_DATA_REPOSITORY` and + :data:`iris.config.RESOURCE_DIR` have been removed. + +Deprecations +============ + +* The *add_custom_season_** functions from :mod:`~iris.coord_categorisation` + have been deprecated in favour of adding their functionality to the + *add_season_** functions + diff --git a/docs/iris/src/whatsnew/1.5.rst b/docs/iris/src/whatsnew/1.5.rst index 6a4f418259d..c891e6c7efb 100644 --- a/docs/iris/src/whatsnew/1.5.rst +++ b/docs/iris/src/whatsnew/1.5.rst @@ -1,16 +1,21 @@ -What's new in Iris 1.5 -********************** +v1.5 (13 Sep 2013) +****************** -:Release: 1.5.0 -:Date: 12 September 2013 - -This document explains the new/changed features of Iris in version 1.5. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.5 features -================= + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + * Scatter plots can now be produced using :func:`iris.plot.scatter` and :func:`iris.quickplot.scatter`. + * The functions :func:`iris.plot.plot` and :func:`iris.quickplot.plot` now take up to two arguments, which may be cubes or coordinates, allowing the user to have full control over what is plotted on each axis. The coords keyword @@ -25,7 +30,9 @@ Iris 1.5 features * :class:`iris.analysis.SUM` is now a weighted aggregator, allowing it to take a weights keyword argument. + * GRIB2 translations added for standard_name 'soil_temperature'. + * :meth:`iris.cube.Cube.slices` can now handle passing dimension index as well as the currently supported types (string, coordinate), in order to slice in cases where there is no coordinate associated with a dimension (a mix of @@ -48,6 +55,7 @@ Iris 1.5 features plt.show() * Support for UM ancillary files truncated with the UM utility ieee + * Complete support for Transverse Mercator with saving to NetCDF also. .. code-block:: python @@ -70,18 +78,26 @@ Iris 1.5 features .. image:: images/transverse_merc.png * Support for loading NAME files (gridded and trajectory data). + * Multi-dimensional coordinate support added for :func:`iris.analysis.cartography.cosine_latitude_weights` + * Added limited packaged GRIB support (bulletin headers). + * In-place keyword added to :func:`iris.analysis.maths.divide` and :func:`iris.analysis.maths.multiply`. + * Performance gains for PP loading of the order of 40%. + * :mod:`iris.quickplot` now has a :func:`~iris.quickplot.show` function to provide convenient access to matplotlib.pyplot.show(). + * :meth:`iris.coords.DimCoord.from_regular` now implemented which creates a :class:`~iris.coords.DimCoord` with regularly spaced points, and optionally bounds. + * Iris can now cope with a missing bounds variable from NetCDF files. + * Added support for bool array indexing on a cube. .. code-block:: python @@ -95,8 +111,10 @@ Iris 1.5 features * Added support for loading fields defined on regular Gaussian grids from GRIB files. + * :func:`iris.analysis.interpolate.extract_nearest_neighbour` now works without needing to load the data (especially relevant to large datasets). + * When using plotting routines from :mod:`iris.plot` or :mod:`iris.quickplot`, the direction of vertical axes will be reversed if the corresponding coordinate has a "positive" attribute set to "down". @@ -105,63 +123,83 @@ Iris 1.5 features * New PP stashcode translations added including 'dewpoint' and 'relative_humidity'. + * Added implied heights for several common PP STASH codes. + * GeoTIFF export capability enhanced for supporting various data types, coord systems and mapping 0 to 360 longitudes to the -180 to 180 range. Bugs fixed ----------- +========== + * NetCDF error handling on save has been extended to capture file path and permission errors. + * Shape of the Earth scale factors are now correctly interpreted by the GRIB loader. They were previously used as a multiplier for the given value but should have been used as a decimal shift. + * OSGB definition corrected. + * Transverse Mercator on load now accepts the following interchangeably due to inconsistencies in CF documentation: - * +scale_factor_at_central_meridian <-> scale_factor_at_projection_origin - * +longitude_of_central_meridian <-> longitude_of_projection_origin - (+recommended encoding) + + * +scale_factor_at_central_meridian <-> scale_factor_at_projection_origin + + * +longitude_of_central_meridian <-> longitude_of_projection_origin + (+recommended encoding) + * Ellipse description now maintained when converting GeogCS to cartopy. + * GeoTIFF export bug fixes. + * Polar axis now set to the North Pole, when a cube with no coordinate system is saved to the PP file-format. + * :meth:`iris.coords.DimCoord.from_coord` and :meth:`iris.coords.AuxCoord.from_coord` now correctly returns a copy of the source coordinate's coordinate system. + * Units part of the axis label is now omitted when the coordinate it represents is given as a time reference (:mod:`iris.quickplot`). + * CF dimension coordinate is now maintained in the resulting cube when a cube with CF dimension coordinate is being aggregated over. + * Units for Lambert conformal and polar stereographic coordinates now defined as meters. + * Various fieldsfile load bugs including failing to read the coordinates from the file have been fixed. + * Coding of maximum and minimum time-stats in GRIB2 saving has been fixed. + * Example code in section 4.1 of the userguide updated so it uses a sample data file that exists. + * Zorder of contour lines drawn by :func:`~iris.plot.contourf` has been changed to address issue of objects appearing in-between line and filled contours. + * Coord comparisons now function correctly when comparing to numpy scalars. + * Cube loading constraints and :meth:`iris.cube.Cube.extract` correctly implement cell equality methods. -Incompatible changes --------------------- -* N/A - Deprecations ------------- +============ + * The coords keyword argument for :func:`iris.plot.plot` and :func:`iris.quickplot.plot` has been deprecated due to the new API which accepts multiple cubes or coordinates. + * :meth:`iris.fileformats.pp.PPField.regular_points` and :meth:`iris.fileformats.pp.PPField.regular_bounds` have now been deprecated in favour of a new factory method :meth:`iris.coords.DimCoord.from_regular()`. + * :func:`iris.fileformats.pp.add_load_rules` and :func:`iris.fileformats.grib.add_load_rules` are now deprecated. diff --git a/docs/iris/src/whatsnew/1.6.rst b/docs/iris/src/whatsnew/1.6.rst index 4b540c6cc99..068311db5f6 100644 --- a/docs/iris/src/whatsnew/1.6.rst +++ b/docs/iris/src/whatsnew/1.6.rst @@ -1,14 +1,17 @@ -What's new in Iris 1.6 -********************** +v1.6 (26 Jan 2014) +****************** -:Release: 1.6.1 -:Date: 18th February 2014 - -This document explains the new/changed features of Iris in version 1.6. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.6 features -================= + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== .. _showcase: @@ -29,9 +32,9 @@ Iris 1.6 features >>> print([str(cell) for cell in coord.cells()]) ['1970-01-01 01:00:00', '1970-01-01 02:00:00', '1970-01-01 03:00:00'] - Note that, either a :class:`datetime.datetime` or :class:`netcdftime.datetime` - object instance will be returned, depending on the calendar of the time - reference coordinate. + Note that, either a :class:`datetime.datetime` or + :class:`netcdftime.datetime` object instance will be returned, depending on + the calendar of the time reference coordinate. This capability permits the ability to express time constraints more naturally when the cell represents a *datetime-like* object. @@ -41,8 +44,10 @@ Iris 1.6 features # Ignore the 1st of January. iris.Constraint(time=lambda cell: cell.point.month != 1 and cell.point.day != 1) - Note that, :class:`iris.Future` also supports a `context manager `_ - which allows multiple sections of code to execute with different run-time behaviour. + Note that, :class:`iris.Future` also supports a + `context manager `_ + which allows multiple sections of code to execute with different run-time + behaviour. .. code-block:: python @@ -63,12 +68,12 @@ Iris 1.6 features :class:`datetime.datetime` or :class:`netcdftime.datetime`. The *year, month, day, hour, minute, second* and *microsecond* attributes of - a :class:`iris.time.PartialDateTime` object may be fully or partially specified - for any given comparison. + a :class:`iris.time.PartialDateTime` object may be fully or partially + specified for any given comparison. This is particularly useful for time based constraints, whilst enabling the - :data:`iris.FUTURE.cell_datetime_objects`, see :ref:`here ` for further - details on this new release feature. + :data:`iris.FUTURE.cell_datetime_objects`, see :ref:`here ` for + further details on this new release feature. .. code-block:: python @@ -85,139 +90,64 @@ Iris 1.6 features * GRIB loading supports latitude/longitude or Gaussian reduced grids for version 1 and version 2. + * :ref:`A new utility function to assist with caching`. + * :ref:`The RMS aggregator supports weights`. + * :ref:`A new experimental function to equalise cube attributes`. + * :ref:`Collapsing a cube provides a tolerance level for missing-data`. + * NAME loading supports vertical coordinates. + * UM land/sea mask de-compression for Fieldsfiles and PP files. + * Lateral boundary condition Fieldsfile support. + * Staggered grid support for Fieldsfiles extended to type 6 (Arakawa C grid with v at poles). + * Extend support for Fieldsfiles with grid codes 11, 26, 27, 28 and 29. + * :ref:`Promoting a scalar coordinate to new leading cube dimension`. + * Interpreting cell methods from NAME. + * GRIB2 export without forecast_period, enabling NAME to GRIB2. + * Loading height levels from GRIB2. + * :func:`iris.coord_categorisation.add_categorised_coord` now supports multi-dimensional coordinate categorisation. -* Fieldsfiles and PP support for loading and saving of air potential temperature. + +* Fieldsfiles and PP support for loading and saving of air potential + temperature. + * :func:`iris.experimental.regrid.regrid_weighted_curvilinear_to_rectilinear` regrids curvilinear point data to a target rectilinear grid using associated area weights. -* Extended capability of the NetCDF saver :meth:`iris.fileformats.netcdf.Saver.write` - for fine-tune control of a :mod:`netCDF4.Variable`. Also allows multiple dimensions - to be nominated as *unlimited*. -* :ref:`A new PEAK aggregator providing spline interpolation`. -* A new utility function :func:`iris.util.broadcast_to_shape`. -* A new utility function :func:`iris.util.as_compatible_shape`. -* Iris tests can now be run on systems where directory write permissions - previously did not allow it. This is achieved by writing to the current working - directory in such cases. -* Support for 365 day calendar PP fields. -* Added phenomenon translation between cf and grib2 for wind (from) direction. -* PP files now retain lbfc value on save, derived from the stash attribute. -Bugs fixed -========== -* :meth:`iris.cube.Cube.rolling_window` has been extended to support masked arrays. -* :meth:`iris.cube.Cube.collapsed` now handles string coordinates. -* Default LBUSER(2) to -99 for Fieldsfile and PP saving. -* :func:`iris.util.monotonic` returns the correct direction. -* File loaders correctly parse filenames containing colons. -* ABF loader now correctly loads the ABF data payload once. -* Support for 1D array :data:`iris.cube.cube.attributes`. -* GRIB bounded level saving fix. -* :func:`iris.analysis.cartography.project` now associates a coordinate system - with the resulting target cube, where applicable. -* :func:`iris.util.array_equal` now correctly ignores any mask if present, - matching the behaviour of :func:`numpy.array_equal` except with string array - support. -* :func:`iris.analysis.interpolate.linear` now retains a mask in the resulting - cube. -* :meth:`iris.coords.DimCoord.from_regular` now correctly returns a coordinate - which will always be regular as indicated by :func:`~iris.util.is_regular`. -* :func:`iris.util.rolling_window` handling of masked arrays (degenerate - masks) fixed. -* Exception no longer raised for any ellipsoid definition in nimrod loading. +* Extended capability of the NetCDF saver + :meth:`iris.fileformats.netcdf.Saver.write` for fine-tune control of a + :mod:`netCDF4.Variable`. Also allows multiple dimensions to be nominated as + *unlimited*. -Incompatible changes -==================== -* The experimental 'concatenate' function is now a method of a - :class:`iris.cube.CubeList`, see :meth:`iris.cube.CubeList.concatenate`. The - functionality is unchanged. -* :meth:`iris.cube.Cube.extract_by_trajectory()` has been removed. - Instead, use :func:`iris.analysis.trajectory.interpolate()`. -* :func:`iris.load_strict()` has been removed. - Instead, use :func:`iris.load_cube()` and :func:`iris.load_cubes()`. -* :meth:`iris.coords.Coord.cos()` and :meth:`iris.coords.Coord.sin()` - have been removed. -* :meth:`iris.coords.Coord.unit_converted()` has been removed. - Instead, make a copy of the coordinate using - :meth:`iris.coords.Coord.copy()` and then call the - :meth:`iris.coords.Coord.convert_units()` method of the new - coordinate. -* Iteration over a :class:`~iris.cube.Cube` has been removed. Instead, - use :meth:`iris.cube.Cube.slices()`. -* The following :class:`~iris.unit.Unit` deprecated methods/properties have been removed. - - ====================================== =========================================== - Removed property/method New method - ====================================== =========================================== - :meth:`~iris.unit.Unit.convertible()` :meth:`~iris.unit.Unit.is_convertible()` - :attr:`~iris.unit.Unit.dimensionless` :meth:`~iris.unit.Unit.is_dimensionless()` - :attr:`~iris.unit.Unit.no_unit` :meth:`~iris.unit.Unit.is_no_unit()` - :attr:`~iris.unit.Unit.time_reference` :meth:`~iris.unit.Unit.is_time_reference()` - :attr:`~iris.unit.Unit.unknown` :meth:`~iris.unit.Unit.is_unknown()` - ====================================== =========================================== -* As a result of deprecating :meth:`iris.cube.Cube.add_history` and removing the - automatic appending of history by operations such as cube arithmetic, - collapsing, and aggregating, the signatures of a number of functions within - :mod:`iris.analysis.maths` have been modified along with that of - :class:`iris.analysis.Aggregator` and :class:`iris.analysis.WeightedAggregator`. -* The experimental ABF and ABL functionality has now been promoted to - core functionality in :mod:`iris.fileformats.abf`. -* The following :mod:`iris.coord_categorisation` deprecated functions have been - removed. +* :ref:`A new PEAK aggregator providing spline interpolation`. - =============================================================== ======================================================= - Removed function New function - =============================================================== ======================================================= - :func:`~iris.coord_categorisation.add_custom_season` :func:`~iris.coord_categorisation.add_season` - :func:`~iris.coord_categorisation.add_custom_season_number` :func:`~iris.coord_categorisation.add_season_number` - :func:`~iris.coord_categorisation.add_custom_season_year` :func:`~iris.coord_categorisation.add_season_year` - :func:`~iris.coord_categorisation.add_custom_season_membership` :func:`~iris.coord_categorisation.add_season_membership` - :func:`~iris.coord_categorisation.add_month_shortname` :func:`~iris.coord_categorisation.add_month` - :func:`~iris.coord_categorisation.add_weekday_shortname` :func:`~iris.coord_categorisation.add_weekday` - :func:`~iris.coord_categorisation.add_season_month_initials` :func:`~iris.coord_categorisation.add_season` - =============================================================== ======================================================= -* When a cube is loaded from PP or GRIB and it has both time and forecast period - coordinates, and the time coordinate has bounds, the forecast period coordinate - will now also have bounds. These bounds will be aligned with the bounds of the - time coordinate taking into account the forecast reference time. Also, - the forecast period point will now be aligned with the time point. +* A new utility function :func:`iris.util.broadcast_to_shape`. -Deprecations -============ -* :meth:`iris.cube.Cube.add_history` has been deprecated in favour - of users modifying/creating the history metadata directly. This is - because the automatic behaviour did not deliver a sufficiently complete, - auditable history and often prevented the merging of cubes. -* :func:`iris.util.broadcast_weights` has been deprecated and replaced - by the new utility function :func:`iris.util.broadcast_to_shape`. -* Callback mechanism `iris.run_callback` has had its deprecation of return - values revoked. The callback can now return cube instances as well as - inplace changes to the cube. +* A new utility function :func:`iris.util.as_compatible_shape`. -New Contributors -================ -Congratulations and thank you to `felicityguest `_, `jkettleb `_, -`kwilliams-mo `_ and `shoyer `_ who all made their first contribution -to Iris! +* Iris tests can now be run on systems where directory write permissions + previously did not allow it. This is achieved by writing to the current + working directory in such cases. +* Support for 365 day calendar PP fields. ----- +* Added phenomenon translation between cf and grib2 for wind (from) direction. +* PP files now retain lbfc value on save, derived from the stash attribute. .. _caching: @@ -249,7 +179,8 @@ consuming processing, or to reap the benefit of fast-loading a pickled cube. .. _rms: The RMS aggregator supports weights -=================================== +----------------------------------- + The :data:`iris.analysis.RMS` aggregator has been extended to allow the use of weights using the new keyword argument :data:`weights`. @@ -264,7 +195,8 @@ For example, an RMS weighted cube collapse is performed as follows: .. _equalise: Equalise cube attributes -======================== +------------------------ + To assist with :class:`iris.cube.Cube` merging, the new experimental in-place function :func:`iris.experimental.equalise_cubes.equalise_attributes` ensures that a sequence of cubes contains a common set of :data:`iris.cube.Cube.attributes`. @@ -276,7 +208,8 @@ have the same attributes. .. _tolerance: Masking a collapsed result by missing-data tolerance -==================================================== +---------------------------------------------------- + The result from collapsing masked cube data may now be completely masked by providing a :data:`mdtol` missing-data tolerance keyword to :meth:`iris.cube.Cube.collapsed`. @@ -289,7 +222,8 @@ less than or equal to the provided tolerance. .. _promote: Promote a scalar coordinate -=========================== +--------------------------- + The new utility function :func:`iris.util.new_axis` creates a new cube with a new leading dimension of size unity. If a scalar coordinate is provided, then the scalar coordinate is promoted to be the dimension coordinate for the new @@ -301,7 +235,8 @@ Note that, this function will load the data payload of the cube. .. _peak: A new PEAK aggregator providing spline interpolation -==================================================== +---------------------------------------------------- + The new :data:`iris.analysis.PEAK` aggregator calculates the global peak value from a spline interpolation of the :class:`iris.cube.Cube` data payload along a nominated coordinate axis. @@ -312,3 +247,138 @@ For example, to calculate the peak time: from iris.analysis import PEAK collapsed_cube = cube.collapsed('time', PEAK) + + +Bugs fixed +========== + +* :meth:`iris.cube.Cube.rolling_window` has been extended to support masked + arrays. + +* :meth:`iris.cube.Cube.collapsed` now handles string coordinates. + +* Default LBUSER(2) to -99 for Fieldsfile and PP saving. + +* :func:`iris.util.monotonic` returns the correct direction. + +* File loaders correctly parse filenames containing colons. + +* ABF loader now correctly loads the ABF data payload once. + +* Support for 1D array :data:`iris.cube.cube.attributes`. + +* GRIB bounded level saving fix. + +* :func:`iris.analysis.cartography.project` now associates a coordinate system + with the resulting target cube, where applicable. + +* :func:`iris.util.array_equal` now correctly ignores any mask if present, + matching the behaviour of :func:`numpy.array_equal` except with string array + support. + +* :func:`iris.analysis.interpolate.linear` now retains a mask in the resulting + cube. + +* :meth:`iris.coords.DimCoord.from_regular` now correctly returns a coordinate + which will always be regular as indicated by :func:`~iris.util.is_regular`. + +* :func:`iris.util.rolling_window` handling of masked arrays (degenerate + masks) fixed. + +* Exception no longer raised for any ellipsoid definition in nimrod loading. + + +Incompatible changes +==================== + +* The experimental 'concatenate' function is now a method of a + :class:`iris.cube.CubeList`, see :meth:`iris.cube.CubeList.concatenate`. The + functionality is unchanged. + +* :meth:`iris.cube.Cube.extract_by_trajectory()` has been removed. + Instead, use :func:`iris.analysis.trajectory.interpolate()`. + +* :func:`iris.load_strict()` has been removed. + Instead, use :func:`iris.load_cube()` and :func:`iris.load_cubes()`. + +* :meth:`iris.coords.Coord.cos()` and :meth:`iris.coords.Coord.sin()` + have been removed. + +* :meth:`iris.coords.Coord.unit_converted()` has been removed. + Instead, make a copy of the coordinate using + :meth:`iris.coords.Coord.copy()` and then call the + :meth:`iris.coords.Coord.convert_units()` method of the new + coordinate. + +* Iteration over a :class:`~iris.cube.Cube` has been removed. Instead, + use :meth:`iris.cube.Cube.slices()`. + +* The following :class:`~iris.unit.Unit` deprecated methods/properties have + been removed. + + ====================================== =========================================== + Removed property/method New method + ====================================== =========================================== + :meth:`~iris.unit.Unit.convertible()` :meth:`~iris.unit.Unit.is_convertible()` + :attr:`~iris.unit.Unit.dimensionless` :meth:`~iris.unit.Unit.is_dimensionless()` + :attr:`~iris.unit.Unit.no_unit` :meth:`~iris.unit.Unit.is_no_unit()` + :attr:`~iris.unit.Unit.time_reference` :meth:`~iris.unit.Unit.is_time_reference()` + :attr:`~iris.unit.Unit.unknown` :meth:`~iris.unit.Unit.is_unknown()` + ====================================== =========================================== + +* As a result of deprecating :meth:`iris.cube.Cube.add_history` and removing the + automatic appending of history by operations such as cube arithmetic, + collapsing, and aggregating, the signatures of a number of functions within + :mod:`iris.analysis.maths` have been modified along with that of + :class:`iris.analysis.Aggregator` and + :class:`iris.analysis.WeightedAggregator`. + +* The experimental ABF and ABL functionality has now been promoted to + core functionality in :mod:`iris.fileformats.abf`. + +* The following :mod:`iris.coord_categorisation` deprecated functions have been + removed. + + =============================================================== ======================================================= + Removed function New function + =============================================================== ======================================================= + :func:`~iris.coord_categorisation.add_custom_season` :func:`~iris.coord_categorisation.add_season` + :func:`~iris.coord_categorisation.add_custom_season_number` :func:`~iris.coord_categorisation.add_season_number` + :func:`~iris.coord_categorisation.add_custom_season_year` :func:`~iris.coord_categorisation.add_season_year` + :func:`~iris.coord_categorisation.add_custom_season_membership` :func:`~iris.coord_categorisation.add_season_membership` + :func:`~iris.coord_categorisation.add_month_shortname` :func:`~iris.coord_categorisation.add_month` + :func:`~iris.coord_categorisation.add_weekday_shortname` :func:`~iris.coord_categorisation.add_weekday` + :func:`~iris.coord_categorisation.add_season_month_initials` :func:`~iris.coord_categorisation.add_season` + =============================================================== ======================================================= + +* When a cube is loaded from PP or GRIB and it has both time and forecast period + coordinates, and the time coordinate has bounds, the forecast period + coordinate will now also have bounds. These bounds will be aligned with the + bounds of the time coordinate taking into account the forecast reference + time. Also, the forecast period point will now be aligned with the time point. + + +Deprecations +============ + +* :meth:`iris.cube.Cube.add_history` has been deprecated in favour + of users modifying/creating the history metadata directly. This is + because the automatic behaviour did not deliver a sufficiently complete, + auditable history and often prevented the merging of cubes. + +* :func:`iris.util.broadcast_weights` has been deprecated and replaced + by the new utility function :func:`iris.util.broadcast_to_shape`. + +* Callback mechanism `iris.run_callback` has had its deprecation of return + values revoked. The callback can now return cube instances as well as + inplace changes to the cube. + + +New Contributors +================ +Congratulations and thank you to +`felicityguest `_, +`jkettleb `_, +`kwilliams-mo `_ and +`shoyer `_ who all made their first contribution +to Iris! diff --git a/docs/iris/src/whatsnew/1.7.rst b/docs/iris/src/whatsnew/1.7.rst index 757d407684f..22d9b05257a 100644 --- a/docs/iris/src/whatsnew/1.7.rst +++ b/docs/iris/src/whatsnew/1.7.rst @@ -1,22 +1,26 @@ -What's new in Iris 1.7 -********************** +v1.7 (04 Jul 2014) +******************** -This document explains the new/changed features of Iris in version 1.7. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -:Release: 1.7.4 -:Date: 15th April 2015 -Iris 1.7 features -================= +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== .. _showcase: .. admonition:: Showcase: Iris is making use of Biggus - Iris is now making extensive use of `Biggus `_ - for virtual arrays and lazy array evaluation. In practice this means that analyses - of cubes with data bigger than the available system memory are now possible. + Iris is now making extensive use of + `Biggus `_ for virtual arrays and lazy + array evaluation. In practice this means that analyses of cubes with data + bigger than the available system memory are now possible. Other than the improved functionality the changes are mostly transparent; for example, before the introduction of biggus, MemoryErrors @@ -33,20 +37,20 @@ Iris 1.7 features >>> print(type(result)) - Memory is still a limiting factor if ever the data is desired as a NumPy array - (e.g. via :data:`cube.data `), but additional methods have - been added to the Cube to support querying and subsequently accessing the "lazy" - data form (see :meth:`~iris.cube.Cube.has_lazy_data` and - :meth:`~iris.cube.Cube.lazy_data`). + Memory is still a limiting factor if ever the data is desired as a NumPy + array (e.g. via :data:`cube.data `), but additional + methods have been added to the Cube to support querying and subsequently + accessing the "lazy" data form (see :meth:`~iris.cube.Cube.has_lazy_data` + and :meth:`~iris.cube.Cube.lazy_data`). .. admonition:: Showcase: New interpolation and regridding API - New interpolation and regridding interfaces have been added which simplify and - extend the existing functionality. + New interpolation and regridding interfaces have been added which simplify + and extend the existing functionality. The interfaces are exposed on the cube in the form of the - :meth:`~iris.cube.Cube.interpolate` and :meth:`~iris.cube.Cube.regrid` methods. - Conceptually the signatures of the methods are:: + :meth:`~iris.cube.Cube.interpolate` and :meth:`~iris.cube.Cube.regrid` + methods. Conceptually the signatures of the methods are:: interpolated_cube = cube.interpolate(interpolation_points, interpolation_scheme) @@ -55,16 +59,17 @@ Iris 1.7 features regridded_cube = cube.regrid(target_grid_cube, regridding_scheme) Whilst not all schemes have been migrated to the new interface, - :class:`iris.analysis.Linear` defines both linear interpolation and regridding, - and :class:`iris.analysis.AreaWeighted` defines an area weighted regridding - scheme. + :class:`iris.analysis.Linear` defines both linear interpolation and + regridding, and :class:`iris.analysis.AreaWeighted` defines an area weighted + regridding scheme. .. admonition:: Showcase: Merge and concatenate reporting Merge reporting is designed as an aid to the merge processes. Should merging - a :class:`~iris.cube.CubeList` fail, merge reporting means that a descriptive - error will be raised that details the differences between the cubes in the - :class:`~iris.cube.CubeList` that prevented the merge from being successful. + a :class:`~iris.cube.CubeList` fail, merge reporting means that a + descriptive error will be raised that details the differences between the + cubes in the :class:`~iris.cube.CubeList` that prevented the merge from + being successful. A new :class:`~iris.cube.CubeList` method, called :meth:`~iris.cube.CubeList.merge_cube`, has been introduced. Calling it on a @@ -83,8 +88,8 @@ Iris 1.7 features iris.exceptions.MergeError: failed to merge into a single cube. cube.attributes keys differ: 'foo' - The naming of this new method mirrors that of Iris load functions, where - one would always expect a :class:`~iris.cube.CubeList` from :func:`iris.load` + The naming of this new method mirrors that of Iris load functions, where one + would always expect a :class:`~iris.cube.CubeList` from :func:`iris.load` and a :class:`~iris.cube.Cube` from :func:`iris.load_cube`. Concatenate reporting is the equivalent process for concatenating a @@ -101,10 +106,10 @@ Iris 1.7 features However, the additional richness of Iris coordinate meta-data provides an enhanced capability beyond the basic broadcasting behaviour of NumPy. - This means that when performing cube arithmetic, the dimensionality and shape of - cubes no longer need to match. For example, if the dimensionality of a cube is - reduced by collapsing, then the result can be used to subtract from the original - cube to calculate an anomaly:: + This means that when performing cube arithmetic, the dimensionality and + shape of cubes no longer need to match. For example, if the dimensionality + of a cube is reduced by collapsing, then the result can be used to subtract + from the original cube to calculate an anomaly:: >>> time_mean = original_cube.collapsed('time', iris.analysis.MEAN) >>> mean_anomaly = original_cube - time_mean @@ -117,131 +122,218 @@ Iris 1.7 features >>> zero_cube = original_cube - similar_cube * Merge reporting that raises a descriptive error if the merge process fails. -* Linear interpolation and regridding now make use of SciPy's RegularGridInterpolator - for much faster linear interpolation. + +* Linear interpolation and regridding now make use of SciPy's + RegularGridInterpolator for much faster linear interpolation. + * NAME file loading now handles the "no time averaging" column and translates - height/altitude above ground/sea-level columns into appropriate coordinate metadata. -* The NetCDF saver has been extended to allow saving of cubes with hybrid pressure - auxiliary factories. -* PP/FF loading supports LBLEV of 9999. -* Extended GRIB1 loading to support data on hybrid pressure levels. -* :func:`iris.coord_categorisation.add_day_of_year` can be used to add categorised - day of year coordinates based on time coordinates with non-Gregorian calendars. + height/altitude above ground/sea-level columns into appropriate coordinate + metadata. + +* The NetCDF saver has been extended to allow saving of cubes with hybrid + pressure auxiliary factories. + +* PP/FF loading supports LBLEV of 9999. + +* Extended GRIB1 loading to support data on hybrid pressure levels. + +* :func:`iris.coord_categorisation.add_day_of_year` can be used to add + categorised day of year coordinates based on time coordinates with + non-Gregorian calendars. + * Support for loading data on reduced grids from GRIB files in raw form without automatically interpolating to a regular grid. + * The coordinate systems :class:`iris.coord_systems.Orthographic` and - :class:`iris.coord_systems.VerticalPerspective` (for imagery from geostationary - satellites) have been added. -* Extended NetCDF loading to support the "ocean sigma over z" auxiliary coordinate + :class:`iris.coord_systems.VerticalPerspective` (for imagery from + geostationary satellites) have been added. + +* Extended NetCDF loading to support the "ocean sigma over z" auxiliary + coordinate factory. + * Support added for loading CF-NetCDF data with bounds arrays that are missing a vertex dimension. + * :meth:`iris.cube.Cube.rolling_window` can now be used with string-based :class:`iris.coords.AuxCoord` instances. + * Loading of PP and FF files has been optimised through deferring creation of PPField attributes. + * Automatic association of a coordinate's CF formula terms variable with the data variable associated with that coordinate. -* PP loading translates cross-section height into a dimensional auxiliary coordinate. -* String auxiliary coordinates can now be plotted with the Iris plotting wrappers. -* :func:`iris.analysis.geometry.geometry_area_weights` now allows for the calculation of - normalized cell weights. -* Many new translations between the CF spec and STASH codes or GRIB2 parameter codes. -* PP save rules add the data's UM Version to the attributes of the saved file - when appropriate. + +* PP loading translates cross-section height into a dimensional auxiliary + coordinate. + +* String auxiliary coordinates can now be plotted with the Iris + plotting wrappers. + +* :func:`iris.analysis.geometry.geometry_area_weights` now + allows for the calculation of normalized cell weights. + +* Many new translations between the CF spec and STASH codes or GRIB2 parameter + codes. + +* PP save rules add the data's UM Version to the attributes of the saved + file when appropriate. + * NetCDF reference surface variable promotion available through the :class:`iris.FUTURE` mechanism. -* A speed improvement in calculation of :func:`iris.analysis.geometry.geometry_area_weights`. -* The mdtol keyword was added to area-weighted regridding to allow control of the - tolerance for missing data. For a further description of this concept, see + +* A speed improvement in calculation of + :func:`iris.analysis.geometry.geometry_area_weights`. + +* The mdtol keyword was added to area-weighted regridding to allow control of + the tolerance for missing data. For a further description of this concept, see :class:`iris.analysis.AreaWeighted`. + * Handling for patching of the CF conventions global attribute via a defined cf_patch_conventions function. -* Deferred GRIB data loading has been introduced for reduced memory consumption when - loading GRIB files. + +* Deferred GRIB data loading has been introduced for reduced memory consumption + when loading GRIB files. + * Concatenate reporting that raises a descriptive error if the concatenation process fails. + * A speed improvement when loading PP or FF data and constraining on STASH code. + Bugs fixed ========== + * Data containing more than one reference cube for constructing hybrid height coordinates can now be loaded. + * Removed cause of increased margin of error when interpolating. + * Changed floating-point precision used when wrapping points for interpolation. + * Mappables that can be used to generate colorbars are now returned by Iris plotting wrappers. -* NetCDF load ignores over-specified formula terms on bounded dimensionless vertical - coordinates. + +* NetCDF load ignores over-specified formula terms on bounded dimensionless + vertical coordinates. + * Auxiliary coordinate factory loading now correctly interprets formula term varibles for "atmosphere hybrid sigma pressure" coordinate data. + * Corrected comparison of NumPy NaN values in cube merge process. -* Fixes for :meth:`iris.cube.Cube.intersection` to correct calculating the intersection - of a cube with split bounds, handling of circular coordinates, handling of - monotonically descending bounded coordinats and for finding a wrapped two-point - result and longitude tolerances. -* A bug affecting :meth:`iris.cube.Cube.extract` and :meth:`iris.cube.CubeList.extract` - that led to unexpected behaviour when operating on scalar cubes has been fixed. -* Aggregate_by may now be passed single-value coordinates. -* Making a copy of a :class:`iris.coords.DimCoord` no longer results in the writeable - flag on the copied points and bounds arrays being set to True. -* Can now save to PP a cube that has vertical levels but no orography. + +* Fixes for :meth:`iris.cube.Cube.intersection` to correct calculating the + intersection of a cube with split bounds, handling of circular coordinates, + handling of monotonically descending bounded coordinats and for finding a + wrapped two-point result and longitude tolerances. + +* A bug affecting :meth:`iris.cube.Cube.extract` and + :meth:`iris.cube.CubeList.extract` that led to unexpected behaviour when + operating on scalar cubes has been fixed. + +* Aggregate_by may now be passed single-value coordinates. + +* Making a copy of a :class:`iris.coords.DimCoord` no longer results in the + writeable flag on the copied points and bounds arrays being set to True. + +* Can now save to PP a cube that has vertical levels but no orography. + * Fix a bug causing surface altitude and surface pressure fields to not appear in cubes loaded with a STASH constraint. -* Fixed support for :class:`iris.fileformats.pp.STASH` objects in STASH constraints. -* A fix to avoid a problem where cube attribute names clash with NetCDF reserved attribute names. -* A fix to allow :meth:`iris.cube.CubeList.concatenate` to deal with descending coordinate order. -* Add missing NetCDF attribute `varname` when constructing a new :class:`iris.coords.AuxCoord`. -* The datatype of time arrays converted with :func:`iris.util.unify_time_units` is now preserved. -Bugs fixed in v1.7.3 +* Fixed support for :class:`iris.fileformats.pp.STASH` objects in STASH + constraints. + +* A fix to avoid a problem where cube attribute names clash with + NetCDF reserved attribute names. + +* A fix to allow :meth:`iris.cube.CubeList.concatenate` to deal with descending + coordinate order. + +* Add missing NetCDF attribute `varname` when constructing a new + :class:`iris.coords.AuxCoord`. * The datatype of time arrays converted with + :func:`iris.util.unify_time_units` is now preserved. + + +v1.7.3 (16 Dec 2014) ^^^^^^^^^^^^^^^^^^^^ -* Scalar dimension coordinates can now be concatenated with :meth:`iris.cube.CubeList.concatenate`. -* Arbitrary names can no longer be set for elements of a :class:`iris.fileformats.pp.SplittableInt`. -* Cubes that contain a pseudo-level coordinate can now be saved to PP. -* Fixed a bug in the FieldsFile loader that prevented it always loading all available fields. -Bugs fixed in v1.7.4 +* Scalar dimension coordinates can now be concatenated with + :meth:`iris.cube.CubeList.concatenate`. + +* Arbitrary names can no longer be set + for elements of a :class:`iris.fileformats.pp.SplittableInt`. + +* Cubes that contain a pseudo-level coordinate can now be saved to PP. + +* Fixed a bug in the FieldsFile loader that prevented it always loading all + available fields. + + +v1.7.4 (15 Apr 2015) ^^^^^^^^^^^^^^^^^^^^ + * :meth:`Coord.guess_bounds` can now deal with circular coordinates. + * :meth:`Coord.nearest_neighbour_index` can now work with descending bounds. + * Passing `weights` to :meth:`Cube.rolling_window` no longer prevents other keyword arguments from being passed to the aggregator. + * Several minor fixes to allow use of Iris on Windows. + * Made use of the new standard_parallels keyword in Cartopy's LambertConformal projection (Cartopy v0.12). Older versions of Iris will not be able to create LambertConformal coordinate systems with Cartopy >= 0.12. + Incompatible changes ==================== + * Saving a cube with a STASH attribute to NetCDF now produces a variable with an attribute of "um_stash_source" rather than "ukmo__um_stash_source". -* Cubes saved to NetCDF with a coordinate system referencing a spherical ellipsoid - now result in the grid mapping variable containing only the "earth_radius" attribute, - rather than the "semi_major_axis" and "semi_minor_axis". -* Collapsing a cube over all of its dimensions now results in a scalar cube rather - than a 1d cube. + +* Cubes saved to NetCDF with a coordinate system referencing a spherical + ellipsoid now result in the grid mapping variable containing only the + "earth_radius" attribute, rather than the "semi_major_axis" and + "semi_minor_axis". + +* Collapsing a cube over all of its dimensions now results in a scalar cube + rather than a 1d cube. + Deprecations ============ + * :func:`iris.util.ensure_array` has been deprecated. + * Deprecated the :func:`iris.fileformats.pp.reset_load_rules` and :func:`iris.fileformats.grib.reset_load_rules` functions. + * Matplotlib is no longer a core Iris dependency. -Documentation changes -===================== + +Documentation +============= + * New sections on :ref:`cube broadcasting ` and :doc:`regridding and interpolation ` have been added to the :doc:`user guide `. + * An example demonstrating custom log-scale colouring has been added. See :ref:`sphx_glr_generated_gallery_general_plot_anomaly_log_colouring.py`. + * An example demonstrating the creation of a custom :class:`iris.analysis.Aggregator` has been added. See :ref:`sphx_glr_generated_gallery_general_plot_custom_aggregation.py`. + * An example of reprojecting data from 2D auxiliary spatial coordinates - (such as that from the ORCA grid) has been added. See :ref:`sphx_glr_generated_gallery_oceanography_plot_orca_projection.py`. -* A clarification of the behaviour of :func:`iris.analysis.calculus.differentiate`. -* A new :doc:`"Technical Papers" ` section has been added to the documentation along - with the addition of a paper providing an :doc:`overview of the load process for UM-like - fileformats (e.g. PP and Fieldsfile) `. + (such as that from the ORCA grid) has been added. See + :ref:`sphx_glr_generated_gallery_oceanography_plot_orca_projection.py`. + +* A clarification of the behaviour of + :func:`iris.analysis.calculus.differentiate`. + +* A new :doc:`"Technical Papers" ` section has been added to + the documentation along with the addition of a paper providing an + :doc:`overview of the load process for UM-like fileformats (e.g. PP and Fieldsfile) `. diff --git a/docs/iris/src/whatsnew/1.8.rst b/docs/iris/src/whatsnew/1.8.rst index 54763a194ba..17432d72678 100644 --- a/docs/iris/src/whatsnew/1.8.rst +++ b/docs/iris/src/whatsnew/1.8.rst @@ -1,14 +1,17 @@ -What's new in Iris 1.8 -********************** +v1.8 (14 Apr 2015) +******************** -:Release: 1.8.1 -:Date: 3rd June 2015 - -This document explains the new/changed features of Iris in version 1.8. +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.8 features -================= + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== .. _showcase: @@ -38,14 +41,17 @@ Iris 1.8 features .. admonition:: Showcase: Slices over a coordinate - You can slice over one or more dimensions of a cube using :meth:`iris.cube.Cube.slices_over`. - This provides similar functionality to :meth:`~iris.cube.Cube.slices` but with - almost the opposite outcome. + You can slice over one or more dimensions of a cube using + :meth:`iris.cube.Cube.slices_over`. + This provides similar functionality to :meth:`~iris.cube.Cube.slices` + but with almost the opposite outcome. - Using :meth:`~iris.cube.Cube.slices` to slice a cube on a selected dimension returns - all possible slices of the cube with the selected dimension retaining its dimensionality. - Using :meth:`~iris.cube.Cube.slices_over` to slice a cube on a selected - dimension returns all possible slices of the cube over the selected dimension. + Using :meth:`~iris.cube.Cube.slices` to slice a cube on a selected + dimension returns all possible slices of the cube with the selected + dimension retaining its dimensionality. Using + :meth:`~iris.cube.Cube.slices_over` to slice a cube on a selected + dimension returns all possible slices of the cube over the selected + dimension. To demonstrate this:: @@ -60,42 +66,65 @@ Iris 1.8 features air_potential_temperature / (K) (model_level_number: 10; grid_latitude: 83; grid_longitude: 83) -* :func:`iris.cube.CubeList.concatenate` now works with `biggus `_ arrays and so +* :func:`iris.cube.CubeList.concatenate` now works with + `biggus `_ arrays and so now supports concatenation of cubes with deferred data. + * Improvements to NetCDF saving through using biggus: * A cube's lazy data payload will still be lazy after saving; the data will not be loaded into memory by the save operation. + * Cubes with data payloads larger than system memory can now be saved to NetCDF through biggus streaming the data to disk. -* :func:`iris.util.demote_dim_coord_to_aux_coord` and :func:`iris.util.promote_aux_coord_to_dim_coord` +* :func:`iris.util.demote_dim_coord_to_aux_coord` and + :func:`iris.util.promote_aux_coord_to_dim_coord` allow a coordinate to be easily demoted or promoted within a cube. -* :func:`iris.util.squeeze` removes all length 1 dimensions from a cube, and demotes - any associated squeeze dimension :class:`~iris.coords.DimCoord` to be a scalar coordinate. -* :meth:`iris.cube.Cube.slices_over`, which returns an iterator of all sub-cubes along a given - coordinate or dimension index. + +* :func:`iris.util.squeeze` removes all length 1 dimensions from a cube, and + demotes any associated squeeze dimension :class:`~iris.coords.DimCoord` to be + a scalar coordinate. + +* :meth:`iris.cube.Cube.slices_over`, which returns an iterator of all + sub-cubes along a given coordinate or dimension index. + * :meth:`iris.cube.Cube.interpolate` now accepts datetime.datetime and netcdftime.datetime instances for date or time coordinates. -* Many new and updated translations between CF spec and STASH codes or GRIB2 parameter - codes. -* PP/FF loader creates a height coordinate at 1.5m or 10m for certain relevant stash codes. -* Lazy aggregator support for the :class:`standard deviation ` - aggregator has been added. -* A speed improvement in calculation of :func:`iris.analysis.cartography.area_weights`. -* Experimental support for unstructured grids has been added with :func:`iris.experimental.ugrid`. - This has been implemented using `UGRID `_. -* :meth:`iris.cube.CubeList.extract_overlapping` supports extraction of cubes over - regions where common coordinates overlap, over multiple coordinates. + +* Many new and updated translations between CF spec and STASH codes or GRIB2 + parameter codes. + +* PP/FF loader creates a height coordinate at 1.5m or 10m for certain relevant + stash codes. + +* Lazy aggregator support for the + :class:`standard deviation ` aggregator has been added. + +* A speed improvement in calculation of + :func:`iris.analysis.cartography.area_weights`. + +* Experimental support for unstructured grids has been added with + :func:`iris.experimental.ugrid`. This has been implemented using + `UGRID `_. + +* :meth:`iris.cube.CubeList.extract_overlapping` supports extraction of cubes + over regions where common coordinates overlap, over multiple coordinates. + * Warnings raised due to invalid units in loaded data have been suppressed. -* Experimental low-level read and write access for FieldsFile variants is now supported - via :class:`iris.experimental.um.FieldsFileVariant`. + +* Experimental low-level read and write access for FieldsFile variants is now + supported via :class:`iris.experimental.um.FieldsFileVariant`. + * PP loader will return cubes for all fields prior to a field with a problematic header before raising an exception. -* NetCDF loader skips invalid global attributes, raising a warning rather than raising an - exception. + +* NetCDF loader skips invalid global attributes, raising a warning rather than + raising an exception. + * A warning is now raised rather than an exception when constructing an :class:`~iris.aux_factory.AuxCoordFactory` fails. + * Supported :class:`aux coordinate factories ` have been extended to include: @@ -104,78 +133,104 @@ Iris 1.8 features * ``ocean s coordinate, generic form 1``, and * ``ocean s coordinate, generic form 2``. -* :meth:`iris.cube.Cube.intersection` now supports taking a points-only intersection. - Any bounds on intersected coordinates are ignored but retained. +* :meth:`iris.cube.Cube.intersection` now supports taking a points-only + intersection. Any bounds on intersected coordinates are ignored but retained. + * The FF loader's known handled grids now includes ``Grid 21``. -* A :class:`nearest neighbour ` scheme is now provided for - :meth:`iris.cube.Cube.interpolate` and :meth:`iris.cube.Cube.regrid`. -* :func:`iris.analysis.cartography.rotate_winds` supports transformation of wind vectors - to a different coordinate system. + +* A :class:`nearest neighbour ` scheme is now provided + for :meth:`iris.cube.Cube.interpolate` and :meth:`iris.cube.Cube.regrid`. + +* :func:`iris.analysis.cartography.rotate_winds` supports transformation of + wind vectors to a different coordinate system. + * NumPy universal functions can now be applied to cubes using :func:`iris.analysis.maths.apply_ufunc`. + * Generic functions can be applied to :class:`~iris.cube.Cube` instances using :class:`iris.analysis.maths.IFunc`. -* The :class:`iris.analysis.Linear` scheme now supports regridding as well as interpolation. - This enables :meth:`iris.cube.Cube.regrid` to perform bilinear regridding, which now - replaces the experimental routine "iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid". + +* The :class:`iris.analysis.Linear` scheme now supports regridding as well as + interpolation. This enables :meth:`iris.cube.Cube.regrid` to perform bilinear + regridding, which now replaces the experimental routine + "iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid". + Bugs fixed ========== -1.8.0 ------- * Fix in netCDF loader to correctly determine whether the longitude coordinate (including scalar coordinates) is circular. -* :meth:`iris.cube.Cube.intersection` now supports bounds that extend slightly beyond 360 - degrees. -* Lateral Boundary Condition (LBC) type FieldFiles are now handled correctly by the FF loader. -* Making a copy of a scalar cube with no data now correctly copies the data array. -* Height coordinates in NAME trajectory output files have been changed to match other - NAME output file formats. + +* :meth:`iris.cube.Cube.intersection` now supports bounds that extend slightly + beyond 360 degrees. + +* Lateral Boundary Condition (LBC) type FieldFiles are now handled correctly by + the FF loader. + +* Making a copy of a scalar cube with no data now correctly copies the data + array. + +* Height coordinates in NAME trajectory output files have been changed to match + other NAME output file formats. + * Fixed datatype when loading an ``integer_constants`` array from a FieldsFile. + * FF/PP loader adds appropriate cell methods for ``lbtim.ib = 3`` intervals. + * An exception is raised if the units of the latitude and longitude coordinates of the cube passed into :func:`iris.analysis.cartography.area_weights` are not convertible to radians. + * GRIB1 loader now creates a time coordinate for a time range indicator of 2. + * NetCDF loader now loads units that are empty strings as dimensionless. -1.8.1 ------- -* The PP loader now carefully handles floating point errors in date time conversions to hours. -* The handling fill values for lazy data loaded from NetCDF files is altered, such that the - _FillValue set in the file is preserved through lazy operations. -* The risk that cube intersections could return incorrect results due to floating point - tolerances is reduced. -* The new GRIB2 loading code is altered to enable the loading of various data representation - templates; the data value unpacking is handled by the GRIB API. -* Saving cube collections to NetCDF, where multiple similar aux-factories exist within the cubes, - is now carefully handled such that extra file variables are created where required in some cases. - -1.8.2 ------ -* A fix to prevent the error: *AttributeError: 'module' object has no attribute 'date2num'*. - This was caused by the function :func:`netcdftime.date2num` being removed from the netCDF4 - package in recent versions. + +v1.8.1 (03 Jun 2015) +-------------------- + +* The PP loader now carefully handles floating point errors in date time + conversions to hours. + +* The handling fill values for lazy data loaded from NetCDF files is altered, + such that the _FillValue set in the file is preserved through lazy operations. + +* The risk that cube intersections could return incorrect results due to + floating point tolerances is reduced. + +* The new GRIB2 loading code is altered to enable the loading of various data + representation templates; the data value unpacking is handled by the GRIB API. + +* Saving cube collections to NetCDF, where multiple similar aux-factories exist + within the cubes, is now carefully handled such that extra file variables are + created where required in some cases. + Deprecations ============ + * The original GRIB loader has been deprecated and replaced with a new template-based GRIB loader. + * Deprecated default NetCDF save behaviour of assigning the outermost dimension to be unlimited. Switch to the new behaviour with no auto assignment by setting :data:`iris.FUTURE.netcdf_no_unlimited` to True. + * The former experimental method - "iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid" has been removed, as - :class:`iris.analysis.Linear` now includes this functionality. - -Documentation changes -===================== -* A chapter on :doc:`merge and concatenate ` has been - added to the :doc:`user guide `. -* A section on installing Iris using `conda `_ has been - added to the :doc:`install guide `. + "iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid" has been + removed, as :class:`iris.analysis.Linear` now includes this functionality. + + +Documentation +============= + +* A chapter on :doc:`merge and concatenate ` has + been added to the :doc:`user guide `. + +* A section on installing Iris using `conda `_ has + been added to the :doc:`install guide `. + * Updates to the chapter on :doc:`regridding and interpolation ` have been added to the :doc:`user guide `. - diff --git a/docs/iris/src/whatsnew/1.9.rst b/docs/iris/src/whatsnew/1.9.rst index 7fda661ebc8..da3fabe6135 100644 --- a/docs/iris/src/whatsnew/1.9.rst +++ b/docs/iris/src/whatsnew/1.9.rst @@ -1,32 +1,48 @@ -What's new in Iris 1.9 -********************** +v1.9 (10 Dec 2015) +******************** -:Release: 1.9.2 -:Date: 28th January 2016 - -This document explains the new/changed features of Iris in version 1.9 +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 1.9 features -================= -* Support for running on Python 3.4 has been added to the whole code base. Some features which - depend on external libraries will not be available until they also support Python 3, namely: + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + +* Support for running on Python 3.4 has been added to the whole code base. + Some features which depend on external libraries will not be available until + they also support Python 3, namely: * gribapi does not yet provide a Python 3 interface -* Added the UM pseudo level type to the information made available in the STASH_TRANS table in :mod:`iris.fileformats.um._ff_cross_references` -* When reading "cell_methods" attributes from NetCDF files, allow optional whitespace before the colon. - This is not strictly in the CF spec, but is a common occurrence. -* Basic cube arithemetic (plus, minus, times, divide) now supports lazy evaluation. -* :meth:`iris.analysis.cartography.rotate_winds` can now operate much faster on multi-layer (i.e. > 2-dimensional) cubes, - as it calculates rotation coefficients only once and reuses them for additional layers. +* Added the UM pseudo level type to the information made available in the + STASH_TRANS table in :mod:`iris.fileformats.um._ff_cross_references` + +* When reading "cell_methods" attributes from NetCDF files, allow optional + whitespace before the colon. This is not strictly in the CF spec, but is a + common occurrence. -* Linear regridding of a multi-layer (i.e. > 2-dimensional) cube is now much faster, - as it calculates transform coefficients just once and reuses them for additional layers. -* Ensemble statistics can now be saved to GRIB2, using Product Definition Template 4.11. +* Basic cube arithemetic (plus, minus, times, divide) now supports lazy + evaluation. -* Loading of NetCDF data with ocean vertical coordinates now returns a 'depth' in addition to an 'eta' cube. - This operates on specific defined dimensionless coordinates : see CF spec version 1.6, Appendix D. +* :meth:`iris.analysis.cartography.rotate_winds` can now operate much faster + on multi-layer (i.e. > 2-dimensional) cubes, as it calculates rotation + coefficients only once and reuses them for additional layers. + +* Linear regridding of a multi-layer (i.e. > 2-dimensional) cube is now much + faster, as it calculates transform coefficients just once and reuses them for + additional layers. + +* Ensemble statistics can now be saved to GRIB2, using Product Definition + Template 4.11. + +* Loading of NetCDF data with ocean vertical coordinates now returns a 'depth' + in addition to an 'eta' cube. This operates on specific defined + dimensionless coordinates : see CF spec version 1.6, Appendix D. * :func:`iris.analysis.stats.pearsonr` updates: @@ -37,14 +53,21 @@ Iris 1.9 features * Accepts common_mask keyword for restricting calculation to unmasked pairs of cells. -* Added a new point-in-cell regridding scheme, :class:`iris.experimental.regrid.PointInCell`. -* Added :meth:`iris.analysis.WPERCENTILE` - a new weighted aggregator for calculating - percentiles. -* Added cell-method translations for LBPROC=64 and 192 in UM files, encoding 'zonal mean' and 'zonal+time mean'. +* Added a new point-in-cell regridding scheme, + :class:`iris.experimental.regrid.PointInCell`. + +* Added :meth:`iris.analysis.WPERCENTILE` - a new weighted aggregator for + calculating percentiles. + +* Added cell-method translations for LBPROC=64 and 192 in UM files, encoding + 'zonal mean' and 'zonal+time mean'. + +* Support for loading GRIB2 messages defined on a Lambert conformal grid has + been added to the GRIB2 loader. + +* Data on potential-temperature (theta) levels can now be saved to GRIB2, with + a fixed surface type of 107. -* Support for loading GRIB2 messages defined on a Lambert conformal grid has been added to - the GRIB2 loader. -* Data on potential-temperature (theta) levels can now be saved to GRIB2, with a fixed surface type of 107. * Added several new helper functions for file-save customisation, (see also : :doc:`Saving Iris Cubes `): @@ -54,76 +77,130 @@ Iris 1.9 features * :meth:`iris.fileformats.pp.as_pairs` * :meth:`iris.fileformats.pp.as_fields` * :meth:`iris.fileformats.pp.save_fields` -* Loading data from GRIB2 now supports most of the currently defined 'data representation templates' : - code numbers 0, 1, 2, 3, 4, 40, 41, 50, 51 and 61. -* When a Fieldsfile is opened for update as a :class:`iris.experimental.um.FieldsFileVariant`, - unmodified packed data in the file can now be retained in the original form. - Previously it could only be stored in an unpacked form. + +* Loading data from GRIB2 now supports most of the currently defined 'data + representation templates' : code numbers 0, 1, 2, 3, 4, 40, 41, 50, 51 and 61. + +* When a Fieldsfile is opened for update as a + :class:`iris.experimental.um.FieldsFileVariant`, unmodified packed data in + the file can now be retained in the original form. Previously it could only + be stored in an unpacked form. + * When reading and writing NetCDF data, the CF 'flag' attributes, - "flag_masks", "flag_meanings" and "flag_values" are now preserved through Iris load and save. -* `mo_pack `_ was added as an optional dependency. + "flag_masks", "flag_meanings" and "flag_values" are now preserved through + Iris load and save. + +* `mo_pack `_ was added as an optional + dependency. It is used to encode and decode data in WGDOS packed form. -* The :meth:`iris.experimental.um.Field.get_data` method can now be used to read Fieldsfile data - after the original :class:`iris.experimental.um.FieldsFileVariant` has been closed. + +* The :meth:`iris.experimental.um.Field.get_data` method can now be used to + read Fieldsfile data after the original + :class:`iris.experimental.um.FieldsFileVariant` has been closed. Bugs fixed ========== + * Fixed a bug in :meth:`iris.unit.Unit.convert` (and the equivalent in `cf_units `_) - so that it now converts data to the native endianness, without which udunits could not read it correctly. + so that it now converts data to the native endianness, without which udunits + could not read it correctly. + * Fixed a bug with loading WGDOS packed data in :mod:`iris.experimental.um`, which could occasionally crash, with some data. -* Ignore non-numeric suffices in the numpy version string, which would otherwise crash some regridding routines. + +* Ignore non-numeric suffices in the numpy version string, which would + otherwise crash some regridding routines. + * fixed a bug in :mod:`iris.fileformats.um_cf_map` where the standard name - for the stash code m01s12i187 was incorrectly set, such that it is inconsistent - with the stated unit of measure, 'm s-1'. The different name, a long_name - of 'change_over_time_in_upward_air_velocity_due_to_advection' with + for the stash code m01s12i187 was incorrectly set, such that it is + inconsistent with the stated unit of measure, 'm s-1'. The different name, + a long_name of 'change_over_time_in_upward_air_velocity_due_to_advection' with units of 'm s-1' is now used instead. + * Fixed a bug in :meth:`iris.cube.Cube.intersection`. - When edge points were at (base + period), intersection would unnecessarily wrap the data. + When edge points were at (base + period), intersection would unnecessarily + wrap the data. + * Fixed a bug in :mod:`iris.fileformats.pp`. - A previous release removed the ability to pass a partial constraint on STASH attribute. -* :meth:`iris.plot.default_projection_extent` now correctly raises an exception if a cube has X bounds but no Y bounds, or vice versa. - Previously it never failed this, as the test was wrong. -* When loading NetCDF data, a "units" attribute containing unicode characters is now transformed by backslash-replacement. - Previously this caused a crash. Note: unicode units are *not supported in the CF conventions*. -* When saving to NetCDF, factory-derived auxiliary coordinates are now correctly saved with different names when they are not identical. - Previously, such coordinates could be saved with the same name, leading to errors. + A previous release removed the ability to pass a partial constraint on STASH + attribute. + +* :meth:`iris.plot.default_projection_extent` now correctly raises an exception + if a cube has X bounds but no Y bounds, or vice versa. Previously it never + failed this, as the test was wrong. + +* When loading NetCDF data, a "units" attribute containing unicode characters + is now transformed by backslash-replacement. Previously this caused a crash. + Note: unicode units are *not supported in the CF conventions*. + +* When saving to NetCDF, factory-derived auxiliary coordinates are now correctly + saved with different names when they are not identical. Previously, such + coordinates could be saved with the same name, leading to errors. + * Fixed a bug in :meth:`iris.experimental.um.FieldsFileVariant.close`, which now correctly allocates extra blocks for larger lookups when saving. - Previously, when larger files open for update were closed, they could be written out with data overlapping the lookup table. + Previously, when larger files open for update were closed, they could be + written out with data overlapping the lookup table. + * Fixed a bug in :class:`iris.aux_factory.OceanSigmaZFactory` - which sometimes caused crashes when fetching the points of an "ocean sigma z" coordinate. + which sometimes caused crashes when fetching the points of an "ocean sigma z" + coordinate. + -Version 1.9.1 -------------- -* Fixed a unicode bug preventing standard names from being built cleanly when installing in Python3 +v1.9.1 (05 Jan 2016) +-------------------- + +* Fixed a unicode bug preventing standard names from being built cleanly when + installing in Python3 + + +v1.9.2 (28 Jan 2016) +-------------------- + +* New warning regarding data loss if writing to an open file which is also + open to read, with lazy data. -Version 1.9.2 -------------- -* New warning regarding data loss if writing to an open file which is also open to read, with lazy data. * Removal of a warning about data payload loading from concatenate. + * Updates to concatenate documentation. + * Fixed a bug with a name change in the netcdf4-python package. + * Fixed a bug building the documentation examples. -* Fixed a bug avoiding sorting classes directly when :meth:`iris.cube.Cube.coord_system` is used in Python3. + +* Fixed a bug avoiding sorting classes directly when + :meth:`iris.cube.Cube.coord_system` is used in Python3. + * Fixed a bug regarding unsuccessful dot import. + Incompatible changes ==================== -* GRIB message/file reading and writing may not be available for Python 3 due to GRIB API limitations. + +* GRIB message/file reading and writing may not be available for Python 3 due + to GRIB API limitations. + Deprecations ============ -* Deprecated :mod:`iris.unit`, with unit functionality provided by `cf_units `_ instead. -* When loading from NetCDF, a deprecation warning is emitted if there is vertical coordinate information - that *would* produce extra result cubes if :data:`iris.FUTURE.netcdf_promote` were set, - but it is *not* set. + +* Deprecated :mod:`iris.unit`, with unit functionality provided by + `cf_units `_ instead. + +* When loading from NetCDF, a deprecation warning is emitted if there is + vertical coordinate information that *would* produce extra result cubes if + :data:`iris.FUTURE.netcdf_promote` were set, but it is *not* set. + * Deprecated :class:`iris.aux_factory.LazyArray` -Documentation changes -===================== + +Documentation +============= + * A chapter on :doc:`saving iris cubes ` has been added to the :doc:`user guide `. -* Added script and documentation for building a what's new page from developer-submitted contributions. - See :doc:`Contributing a "What's New" entry `. + +* Added script and documentation for building a what's new page from + developer-submitted contributions. See + :doc:`Contributing a "What's New" entry `. diff --git a/docs/iris/src/whatsnew/2.0.rst b/docs/iris/src/whatsnew/2.0.rst index 61568d3a8e2..577e8fea22d 100644 --- a/docs/iris/src/whatsnew/2.0.rst +++ b/docs/iris/src/whatsnew/2.0.rst @@ -1,16 +1,18 @@ -What's new in Iris 2.0.0 -************************ +v2.0 (14 Feb 2018) +****************** -:Release: 2.0.0rc1 -:Date: 2018-01-11 +This document explains the changes made to Iris for this release +(:doc:`View all changes `.) -This document explains the new/changed features of Iris in version 2.0.0 -(:doc:`View all changes `). +.. contents:: Skip to section: + :local: + :depth: 3 -Iris 2.0.0 features -=================== +Features +======== + .. _showcase: .. admonition:: Dask Integration @@ -209,8 +211,8 @@ Incompatible Changes printed as ``m.s-1``. -Deprecation removals --------------------- +Deprecation +=========== All deprecated functionality that was announced for removal in Iris 2.0 has been removed. In particular: @@ -289,8 +291,8 @@ been removed. In particular: removed from the :class:`iris.fileformats.rules.Loader` constructor. -Documentation changes -===================== +Documentation +============= * A new UserGuide chapter on :doc:`Real and Lazy Data ` has been added, and referenced from key diff --git a/docs/iris/src/whatsnew/2.1.rst b/docs/iris/src/whatsnew/2.1.rst index a82d3b8470f..311e8c251b5 100644 --- a/docs/iris/src/whatsnew/2.1.rst +++ b/docs/iris/src/whatsnew/2.1.rst @@ -1,37 +1,17 @@ -What's new in Iris 2.1 -********************** +v2.1 (06 Jun 2018) +****************** -:Release: 2.1 -:Date: 2018-06-06 +This document explains the changes made to Iris for this release +(:doc:`View all changes `.) -This document explains the new/changed features of Iris in version 2.1 -(:doc:`older "What's New" release notes can be found here`.) +.. contents:: Skip to section: + :local: + :depth: 3 -Iris 2.1 dependency updates -=========================== -* The `cf_units `_ dependency - was updated to cf_units ``v2.0``. - cf_units v2 is almost entirely backwards compatible with v1. - However the ability to preserve some aliased calendars has been removed. - For this reason, it is possible that NetCDF load of a variable with a - "standard" calendar will result in a saved NetCDF of a "gregorian" - calendar. -* Iris updated its time-handling functionality from the - `netcdf4-python `_ - ``netcdftime`` implementation to the standalone module - `cftime `_. - cftime is entirely compatible with netcdftime, but some issues may - occur where users are constructing their own datetime objects. - In this situation, simply replacing ``netcdftime.datetime`` with - ``cftime.datetime`` should be sufficient. -* Iris now requires version 2 of Matplotlib, and ``>=1.14`` of NumPy. - Full requirements can be seen in the `requirements `_ - directory of the Iris' the source. - -Iris 2.1 features -================= +Features +======== * Added ``repr_html`` functionality to the :class:`~iris.cube.Cube` to provide a rich html representation of cubes in Jupyter notebooks. Existing functionality @@ -42,42 +22,81 @@ Iris 2.1 features * Updated :func:`iris.cube.Cube.name` to return a STASH code if the cube has one and no other valid names are present. This is now consistent with the summary information from :func:`iris.cube.Cube.summary`. + * The partial collapse of multi-dimensional auxiliary coordinates is now supported. Collapsed bounds span the range of the collapsed dimension(s). + * Added new function :func:`iris.cube.CubeList.realise_data` to compute multiple lazy values in a single operation, avoiding repeated re-loading of data or re-calculation of expressions. + * The methods :meth:`iris.cube.Cube.convert_units` and :meth:`iris.coords.Coord.convert_units` no longer forcibly realise the cube data or coordinate points/bounds. The converted values are now lazy arrays if the originals were. + * Added :meth:`iris.analysis.trajectory.interpolate` that allows you to interpolate to find values along a trajectory. + * It is now possible to add an attribute of ``missing_value`` to a cube (:issue:`1588`). + * Iris can now represent data on the Albers Equal Area Projection, and the NetCDF loader and saver were updated to handle this. (:issue:`2943`) + * The :class:`~iris.coord_systems.Mercator` projection has been updated to accept the ``standard_parallel`` keyword argument (:pull:`3041`). + Bugs fixed ========== * All var names being written to NetCDF are now CF compliant. Non alpha-numeric characters are replaced with '_', and var names now always have a leading letter (:pull:`2930`). + * A cube resulting from a regrid operation using the `iris.analysis.AreaWeighted` regridding scheme will now have the smallest floating point data type to which the source cube's data type can be safely converted using NumPy's type promotion rules. + * :mod:`iris.quickplot` labels now honour the axes being drawn to when using the ``axes`` keyword (:pull:`3010`). + Incompatible changes ==================== + * The deprecated :mod:`iris.experimental.um` was removed. Please use consider using `mule `_ as an alternative. + * This release of Iris contains a number of updated metadata translations. - See [this changelist](https://github.com/SciTools/iris/commit/69597eb3d8501ff16ee3d56aef1f7b8f1c2bb316#diff-1680206bdc5cfaa83e14428f5ba0f848) + See this + `changelist `_ for further information. + + +Internal +======== + +* The `cf_units `_ dependency + was updated to cf_units ``v2.0``. + cf_units v2 is almost entirely backwards compatible with v1. + However the ability to preserve some aliased calendars has been removed. + For this reason, it is possible that NetCDF load of a variable with a + "standard" calendar will result in a saved NetCDF of a "gregorian" + calendar. + +* Iris updated its time-handling functionality from the + `netcdf4-python `_ + ``netcdftime`` implementation to the standalone module + `cftime `_. + cftime is entirely compatible with netcdftime, but some issues may + occur where users are constructing their own datetime objects. + In this situation, simply replacing ``netcdftime.datetime`` with + ``cftime.datetime`` should be sufficient. + +* Iris now requires version 2 of Matplotlib, and ``>=1.14`` of NumPy. + Full requirements can be seen in the `requirements `_ + directory of the Iris' the source. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/2.2.rst b/docs/iris/src/whatsnew/2.2.rst index 75be5460b34..314f84355f6 100644 --- a/docs/iris/src/whatsnew/2.2.rst +++ b/docs/iris/src/whatsnew/2.2.rst @@ -1,17 +1,18 @@ -What's new in Iris 2.2 -************************ +v2.2 (11 Oct 2018) +****************** -:Release: 2.2.0 -:Date: +This document explains the changes made to Iris for this release +(:doc:`View all changes `.) -This document explains the new/changed features of Iris in the release -of version 2.2 -(:doc:`View all changes `). +.. contents:: Skip to section: + :local: + :depth: 3 -Iris 2.2 features -=================== +Features +======== + .. _showcase: .. admonition:: 2-Dimensional Coordinate Plotting @@ -70,18 +71,6 @@ Iris 2.2 features a NaN-tolerant array comparison. -Iris 2.2 dependency updates -============================= - -* Iris is now using the latest version release of dask (currently 0.19.3) - -* Proj4 has been temporarily pinned to version < 5 while problems with the - Mollweide projection are addressed. - -* Matplotlib has been pinned to version < 3 temporarily while we account for - its changes in all SciTools libraries. - - Bugs fixed ========== @@ -93,7 +82,7 @@ Bugs fixed bound data is actually masked. -Bugs fixed in v2.2.1 +v2.2.1 (28 May 2019) -------------------- * Iris can now correctly unpack a column of header objects when saving a @@ -108,9 +97,20 @@ Bugs fixed in v2.2.1 floating-point arithmetic. +Internal +======== + +* Iris is now using the latest version release of dask (currently 0.19.3) + +* Proj4 has been temporarily pinned to version < 5 while problems with the + Mollweide projection are addressed. + +* Matplotlib has been pinned to version < 3 temporarily while we account for + its changes in all SciTools libraries. + -Documentation changes -===================== +Documentation +============= * Iris' `INSTALL` document has been updated to include guidance for running tests. diff --git a/docs/iris/src/whatsnew/2.3.rst b/docs/iris/src/whatsnew/2.3.rst index 6fb70883398..a515f6daad7 100644 --- a/docs/iris/src/whatsnew/2.3.rst +++ b/docs/iris/src/whatsnew/2.3.rst @@ -1,14 +1,18 @@ -What's new in Iris 2.3.0 -************************ +v2.3 (19 Dec 2019) +****************** -:Release: 2.3.0 -:Date: 2019-12-19 - -This document explains the new/changed features of Iris in version 2.3.0 +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 2.3.0 features -=================== + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + .. _showcase: .. admonition:: Support for CF 1.7 @@ -112,53 +116,67 @@ Iris 2.3.0 features * Added support to render HTML for :class:`~iris.cube.CubeList` in Jupyter Notebooks and JupyterLab. + * Loading CellMeasures with integer values is now supported. + * New coordinate system: :class:`iris.coord_systems.Geostationary`, including load and save support, based on the `CF Geostationary projection definition `_. + * :class:`iris.coord_systems.VerticalPerspective` can now be saved to and loaded from NetCDF files. + * :class:`iris.experimental.regrid.PointInCell` moved to :class:`iris.analysis.PointInCell` to make this regridding scheme public -* Iris now supports standard name modifiers. See `Appendix C, Standard Name Modifiers `_ for more information. + +* Iris now supports standard name modifiers. See + `Appendix C, Standard Name Modifiers `_ + for more information. + * :meth:`iris.cube.Cube.remove_cell_measure` now also allows removal of a cell measure by its name (previously only accepted a CellMeasure object). + * The :data:`iris.analysis.RMS` aggregator now supports a lazy calculation. However, the "weights" keyword is not currently supported by this, so a *weighted* calculation will still return a realised result, *and* force realisation of the original cube data. -* Iris now supports NetCDF Climate and Forecast (CF) Metadata Conventions 1.7 (see `CF 1.7 Conventions Document `_ for more information) + +* Iris now supports NetCDF Climate and Forecast (CF) Metadata Conventions 1.7 + (see `CF 1.7 Conventions Document `_ for more information) + * Updated standard name support to `CF standard name table version 70, 2019-12-10 `_ + * Updated UM STASH translations to `metarelate/metOcean commit 448f2ef, 2019-11-29 `_ -Iris 2.3.0 dependency updates -============================= -* Iris now supports Proj4 up to version 5, but not yet 6 or beyond, pending - `fixes to some cartopy tests `_. -* Iris now requires Dask >= 1.2 to allow for improved coordinate equality - checks. - - Bugs fixed ========== + * Cube equality of boolean data is now handled correctly. + * Fixed a bug where cell measures were incorrect after a cube :meth:`~iris.cube.Cube.transpose` operation. Previously, this resulted in cell-measures that were no longer correctly mapped to the cube dimensions. -* The :class:`~iris.coords.AuxCoord` disregarded masked points and bounds, as did the :class:`~iris.coords.DimCoord`. - Fix permits an :class:`~iris.coords.AuxCoord` to contain masked points/bounds, and a TypeError exception is now - raised when attempting to create or set the points/bounds of a - :class:`~iris.coords.DimCoord` with arrays with missing points. + +* The :class:`~iris.coords.AuxCoord` disregarded masked points and bounds, as + did the :class:`~iris.coords.DimCoord`. Fix permits an + :class:`~iris.coords.AuxCoord` to contain masked points/bounds, and a + TypeError exception is now raised when attempting to create or set the + points/bounds of a :class:`~iris.coords.DimCoord` with arrays with missing + points. + * :class:`iris.coord_systems.VerticalPerspective` coordinate system now uses the `CF Vertical perspective definition `_; had been erroneously using Geostationary. -* :class:`~iris.coords.CellMethod` will now only use valid `NetCDF name tokens`_ to reference the coordinates involved in the statistical operation. + +* :class:`~iris.coords.CellMethod` will now only use valid + `NetCDF name tokens`_ to reference the coordinates involved in the + statistical operation. + * The following var_name properties will now only allow valid `NetCDF name tokens`_ to reference the said NetCDF variable name. Note that names with a leading @@ -174,48 +192,73 @@ Bugs fixed * Rendering a cube in Jupyter will no longer crash for a cube with attributes containing ``\n``. + * NetCDF variables which reference themselves in their ``cell_measures`` attribute can now be read. + * :func:`~iris.plot.quiver` now handles circular coordinates. + * The names of cubes loaded from abf/abl files have been corrected. + * Fixed a bug in UM file loading, where any landsea-mask-compressed fields (i.e. with LBPACK=x2x) would cause an error later, when realising the data. + * :meth:`iris.cube.Cube.collapsed` now handles partial collapsing of multidimensional coordinates that have bounds. + * Fixed a bug in the :data:`~iris.analysis.PROPORTION` aggregator, where cube data in the form of a masked array with ``array.mask=False`` would cause an error, but possibly only later when the values are actually realised. ( Note: since netCDF4 version 1.4.0, this is now a common form for data loaded from netCDF files ). + * Fixed a bug where plotting a cube with a :class:`iris.coord_systems.LambertConformal` coordinate system would result in an error. This would happen if the coordinate system was defined with one standard parallel, rather than two. In these cases, a call to :meth:`~iris.coord_systems.LambertConformal.as_cartopy_crs` would fail. + * :meth:`iris.cube.Cube.aggregated_by` now gives correct values in points and bounds when handling multidimensional coordinates. + * Fixed a bug in the :meth:`iris.cube.Cube.collapsed` operation, which caused the unexpected realization of any attached auxiliary coordinates that were *bounded*. It now correctly produces a lazy result and does not realise the original attached AuxCoords. -Documentation changes -===================== +Internal +======== + +* Iris now supports Proj4 up to version 5, but not yet 6 or beyond, pending + `fixes to some cartopy tests `_. + +* Iris now requires Dask >= 1.2 to allow for improved coordinate equality + checks. + + +Documentation +============= + * Adopted a `new colour logo for Iris <../_static/Iris7_1_trim_full.png>`_ + * Added a gallery example showing how to concatenate NEMO ocean model data, see :ref:`sphx_glr_generated_gallery_oceanography_plot_load_nemo.py`. + * Added an example in the `Loading Iris Cubes: Constraining on Time <../userguide/loading_iris_cubes .html#constraining-on-time>`_ Userguide section, demonstrating how to load data within a specified date range. + * Added notes to the :func:`iris.load` documentation, and the userguide `Loading Iris Cubes <../userguide/loading_iris_cubes.html>`_ chapter, emphasizing that the *order* of the cubes returned by an iris load operation is effectively random and unstable, and should not be relied on. + * Fixed references in the documentation of :func:`iris.util.find_discontiguities` to a nonexistent "mask_discontiguities" routine : these now refer to diff --git a/docs/iris/src/whatsnew/2.4.rst b/docs/iris/src/whatsnew/2.4.rst index 776cc8aa695..0df2a909ff9 100644 --- a/docs/iris/src/whatsnew/2.4.rst +++ b/docs/iris/src/whatsnew/2.4.rst @@ -1,23 +1,25 @@ -What's new in Iris 2.4.0 -************************ +v2.4 (20 Feb 2020) +****************** -:Release: 2.4.0 -:Date: 2020-02-20 - -This document explains the new/changed features of Iris in version 2.4.0 +This document explains the changes made to Iris for this release (:doc:`View all changes `.) -Iris 2.4.0 features -=================== +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== .. admonition:: Last python 2 version of Iris - Iris 2.4 is a final extra release of Iris 2, which back-ports specific desired features from - Iris 3 (not yet released). + Iris 2.4 is a final extra release of Iris 2, which back-ports specific + desired features from Iris 3 (not yet released). - The purpose of this is both to support early adoption of certain newer features, - and to provide a final release for Python 2. + The purpose of this is both to support early adoption of certain newer + features, and to provide a final release for Python 2. The next release of Iris will be version 3.0 : a major-version release which introduces breaking API and behavioural changes, and only supports Python 3. @@ -25,35 +27,42 @@ Iris 2.4.0 features * :class:`iris.coord_systems.Geostationary` can now accept creation arguments of `false_easting=None` or `false_northing=None`, equivalent to values of 0. Previously these kwargs could be omitted, but could not be set to `None`. - This also enables loading of netcdf data on a Geostationary grid, where either of these - keys is not present as a grid-mapping variable property : Previously, loading any - such data caused an exception. -* The area weights used when performing area weighted regridding with :class:`iris.analysis.AreaWeighted` - are now cached. - This allows a significant speedup when regridding multiple similar cubes, by repeatedly using - a `'regridder' object <../iris/iris/analysis.html?highlight=regridder#iris.analysis.AreaWeighted.regridder>`_ + This also enables loading of netcdf data on a Geostationary grid, where + either of these keys is not present as a grid-mapping variable + property : Previously, loading any such data caused an exception. + +* The area weights used when performing area weighted regridding with + :class:`iris.analysis.AreaWeighted` are now cached. This allows a + significant speedup when regridding multiple similar cubes, by repeatedly + using a :func:`iris.analysis.AreaWeighted.regridder` objects which you created first. -* Name constraint matching against cubes during loading or extracting has been relaxed from strictly matching - against the :meth:`~iris.cube.Cube.name`, to matching against either the - ``standard_name``, ``long_name``, NetCDF ``var_name``, or ``STASH`` attributes metadata of a cube. -* Cubes and coordinates now have a new ``names`` property that contains a tuple of the - ``standard_name``, ``long_name``, NetCDF ``var_name``, and ``STASH`` attributes metadata. -* The :class:`~iris.NameConstraint` provides richer name constraint matching when loading or extracting - against cubes, by supporting a constraint against any combination of - ``standard_name``, ``long_name``, NetCDF ``var_name`` and ``STASH`` - from the attributes dictionary of a :class:`~iris.cube.Cube`. - - -Iris 2.4.0 dependency updates -============================= -* Iris is now able to use the latest version of matplotlib. + +* Name constraint matching against cubes during loading or extracting has been + relaxed from strictly matching against the :meth:`~iris.cube.Cube.name`, to + matching against either the ``standard_name``, ``long_name``, NetCDF + ``var_name``, or ``STASH`` attributes metadata of a cube. + +* Cubes and coordinates now have a new ``names`` property that contains a tuple + of the ``standard_name``, ``long_name``, NetCDF ``var_name``, and ``STASH`` + attributes metadata. + +* The :class:`~iris.NameConstraint` provides richer name constraint matching + when loading or extracting against cubes, by supporting a constraint against + any combination of ``standard_name``, ``long_name``, NetCDF ``var_name`` and + ``STASH`` from the attributes dictionary of a :class:`~iris.cube.Cube`. Bugs fixed ========== + * Fixed a problem which was causing file loads to fetch *all* field data whenever UM files (PP or Fieldsfiles) were loaded. With large sourcefiles, initial file loads are slow, with large memory usage before any cube data is even fetched. Large enough files will cause a crash. The problem occurs only with Dask versions >= 2.0. + +Internal +======== + +* Iris is now able to use the latest version of matplotlib. diff --git a/docs/iris/src/whatsnew/aggregate_directory.py b/docs/iris/src/whatsnew/aggregate_directory.py deleted file mode 100644 index 6fe92f6764a..00000000000 --- a/docs/iris/src/whatsnew/aggregate_directory.py +++ /dev/null @@ -1,337 +0,0 @@ -# Copyright Iris contributors -# -# This file is part of Iris and is released under the LGPL license. -# See COPYING and COPYING.LESSER in the root of the repository for full -# licensing details. -""" -Build a release file from files in a contributions directory. - -Looks for directories "<...whatsnew>/contributions_". -Takes specified "xx.xx" as version, or latest found (alphabetic). -Writes a file "<...whatsnew>/.rst". - -Valid contributions filenames are of the form: - __summary.txt -Where can be any valid chars, and - is one of : - "newfeature" "bugfix" "incompatiblechange" "deprecate" "docchange", and - is in the style "2001-Jan-23". - -""" - -import datetime -from glob import glob -import os -import re -import argparse -import warnings -from operator import itemgetter -from distutils import version - -# Regular expressions: CONTRIBUTION_REGEX matches the filenames of -# contribution snippets. It is split into three sections separated by _ -# 0. String for the category. 1. ISO8601 date. 2. String for the feature name. -# RELEASE_REGEX matches the directory names, returning the release. -CONTRIBUTION_REGEX_STRING = r"(?P.*)" -CONTRIBUTION_REGEX_STRING += r"_(?P\d{4}-\w{3}-\d{2})" -CONTRIBUTION_REGEX_STRING += r"_(?P.*)\.txt$" -CONTRIBUTION_REGEX = re.compile(CONTRIBUTION_REGEX_STRING) -RELEASEDIR_PREFIX = r"contributions_" -_RELEASEDIR_REGEX_STRING = RELEASEDIR_PREFIX + r"(?P.*)$" -RELEASE_REGEX = re.compile(_RELEASEDIR_REGEX_STRING) -SOFTWARE_NAME = "Iris" -EXTENSION = ".rst" -VALID_CATEGORIES = [ - {"Prefix": "newfeature", "Title": "features"}, - {"Prefix": "bugfix", "Title": "Bugs Fixed"}, - {"Prefix": "incompatiblechange", "Title": "Incompatible Changes"}, - {"Prefix": "deprecate", "Title": "Deprecations"}, - {"Prefix": "docchange", "Title": "Documentation Changes"}, -] -VALID_CATEGORY_PREFIXES = [cat["Prefix"] for cat in VALID_CATEGORIES] - - -def _self_root_directory(): - return os.path.abspath(os.path.dirname(__file__)) - - -def _decode_contribution_filename(file_name): - file_name_elements = CONTRIBUTION_REGEX.match(file_name) - category = file_name_elements.group("category") - if category not in VALID_CATEGORY_PREFIXES: - # This is an error - raise ValueError("Unknown category in contribution filename.") - isodate = file_name_elements.group("isodate") - date_of_item = datetime.datetime.strptime(isodate, "%Y-%b-%d").date() - return category, isodate, date_of_item - - -def is_release_directory(directory_name, release): - """Returns True if a given directory name matches the requested release.""" - result = False - directory_elements = RELEASE_REGEX.match(directory_name) - try: - release_string = directory_elements.group("release") - directory_release = version.StrictVersion(release_string) - except (AttributeError, ValueError): - pass - else: - if directory_release == release: - result = True - return result - - -def is_compiled_release(root_directory, release): - """Returns True if the requested release.rst file exists.""" - result = False - compiled_filename = "{!s}{}".format(release, EXTENSION) - compiled_filepath = os.path.join(root_directory, compiled_filename) - if os.path.exists(compiled_filepath) and os.path.isfile(compiled_filepath): - result = True - return result - - -def get_latest_release(root_directory=None): - """ - Implement default=latest release identification. - - Returns a valid release code. - - """ - if root_directory is None: - root_directory = _self_root_directory() - directory_contents = os.listdir(root_directory) - # Default release to latest visible dir. - possible_release_dirs = [ - releasedir_name - for releasedir_name in directory_contents - if RELEASE_REGEX.match(releasedir_name) - ] - if len(possible_release_dirs) == 0: - dirspec = os.path.join(root_directory, RELEASEDIR_PREFIX + "*") - msg = "No valid release directories found, i.e. {!r}." - raise ValueError(msg.format(dirspec)) - release_dirname = sorted(possible_release_dirs)[-1] - release = RELEASE_REGEX.match(release_dirname).group("release") - return release - - -def find_release_directory( - root_directory, release=None, fail_on_existing=True -): - """ - Returns the matching contribution directory or raises an exception. - - Defaults to latest-found release (from release directory names). - Optionally, fail if the matching release file already exists. - *Always* fail if no release directory exists. - - """ - if release is None: - # Default to latest release. - release = get_latest_release(root_directory) - - if fail_on_existing: - compiled_release = is_compiled_release(root_directory, release) - if compiled_release: - msg = ( - "Specified release {!r} is already compiled : " - "{!r} already exists." - ) - compiled_filename = str(release) + EXTENSION - raise ValueError(msg.format(release, compiled_filename)) - - directory_contents = os.listdir(root_directory) - result = None - for inode in directory_contents: - node_path = os.path.join(root_directory, inode) - if os.path.isdir(node_path): - release_directory = is_release_directory(inode, release) - if release_directory: - result = os.path.join(root_directory, inode) - break - if not result: - msg = "Contribution folder for release {!s} does not exist : no {!r}." - release_dirname = RELEASEDIR_PREFIX + str(release) + "/" - release_dirpath = os.path.join(root_directory, release_dirname) - raise ValueError(msg.format(release, release_dirpath)) - return result - - -def generate_header(release, unreleased=False): - """Return a list of text lines that make up a header for the document.""" - if unreleased: - isodatestamp = "" - else: - isodatestamp = datetime.date.today().strftime("%Y-%m-%d") - header_text = [] - title_template = "What's new in {} {!s}\n" - title_line = title_template.format(SOFTWARE_NAME, release) - title_underline = ("*" * (len(title_line) - 1)) + "\n" - header_text.append(title_line) - header_text.append(title_underline) - header_text.append("\n") - header_text.append(":Release: {!s}\n".format(release)) - header_text.append(":Date: {}\n".format(isodatestamp)) - header_text.append("\n") - description_template = ( - "This document explains the new/changed features " - "of {} in version {!s}\n" - ) - header_text.append(description_template.format(SOFTWARE_NAME, release)) - header_text.append("(:doc:`View all changes `.)") - header_text.append("\n") - return header_text - - -def read_directory(directory_path): - """Parse the items in a specified directory and return their metadata.""" - directory_contents = os.listdir(directory_path) - compilable_files_unsorted = [] - misnamed_files = [] - for file_name in directory_contents: - try: - category, isodate, date_of_item = _decode_contribution_filename( - file_name - ) - except (AttributeError, ValueError): - misnamed_files.append(file_name) - continue - compilable_files_unsorted.append( - {"Category": category, "Date": date_of_item, "FileName": file_name} - ) - compilable_files = sorted( - compilable_files_unsorted, key=itemgetter("Date"), reverse=True - ) - if misnamed_files: - msg = "Found contribution file(s) with unexpected names :" - for filename in misnamed_files: - full_path = os.path.join(directory_path, filename) - msg += "\n {}".format(full_path) - warnings.warn(msg, UserWarning) - - return compilable_files - - -def compile_directory(directory, release, unreleased=False): - """Read in source files in date order and compile the text into a list.""" - if unreleased: - release = "" - source_text = read_directory(directory) - compiled_text = [] - header_text = generate_header(release, unreleased) - compiled_text.extend(header_text) - for count, category in enumerate(VALID_CATEGORIES): - category_text = [] - subtitle_line = "" - if count == 0: - subtitle_line += "{} {!s} ".format(SOFTWARE_NAME, release) - subtitle_line += category["Title"] + "\n" - subtitle_underline = ("=" * (len(subtitle_line) - 1)) + "\n" - category_text.append("\n") - category_text.append(subtitle_line) - category_text.append(subtitle_underline) - category_items = [ - item - for item in source_text - if item["Category"] == category["Prefix"] - ] - if not category_items: - continue - for file_description in category_items: - entry_path = os.path.join(directory, file_description["FileName"]) - with open(entry_path, "r") as content_object: - text = content_object.readlines() - if not text[-1].endswith("\n"): - text[-1] += "\n" - category_text.extend(text) - category_text.append("\n----\n\n") - compiled_text.extend(category_text) - return compiled_text - - -def check_all_contributions_valid(release=None, quiet=False, unreleased=False): - """"Scan the contributions directory for badly-named files.""" - root_directory = _self_root_directory() - # Check there are *some* contributions directory(s), else silently pass. - contribs_spec = os.path.join(root_directory, RELEASEDIR_PREFIX + "*") - if len(glob(contribs_spec)) > 0: - # There are some contributions directories: check latest / specified. - if release is None: - release = get_latest_release() - if not quiet: - msg = 'Checking whatsnew contributions for release "{!s}".' - print(msg.format(release)) - release_directory = find_release_directory( - root_directory, release, fail_on_existing=False - ) - # Run the directory scan, but convert any warning into an error. - with warnings.catch_warnings(): - warnings.simplefilter("error") - compile_directory(release_directory, release, unreleased) - if not quiet: - print("done.") - - -def run_compilation(release=None, quiet=False, unreleased=False): - """Write a draft release.rst file given a specified uncompiled release.""" - if release is None: - # This must exist ! - release = get_latest_release() - if not quiet: - msg = 'Building release document for release "{!s}".' - print(msg.format(release)) - root_directory = _self_root_directory() - release_directory = find_release_directory(root_directory, release) - compiled_text = compile_directory(release_directory, release, unreleased) - if unreleased: - compiled_filename = "latest" + EXTENSION - else: - compiled_filename = str(release) + EXTENSION - compiled_filepath = os.path.join(root_directory, compiled_filename) - with open(compiled_filepath, "w") as output_object: - for string_line in compiled_text: - output_object.write(string_line) - if not quiet: - print("done.") - - -if __name__ == "__main__": - PARSER = argparse.ArgumentParser() - PARSER.add_argument( - "release", - help="Release number to be compiled", - nargs="?", - type=version.StrictVersion, - ) - PARSER.add_argument( - "-c", - "--checkonly", - action="store_true", - help="Check contribution file names, do not build.", - ) - PARSER.add_argument( - "-u", - "--unreleased", - action="store_true", - help=( - "Label the release version as '', " - "and its date as ''." - ), - ) - PARSER.add_argument( - "-q", - "--quiet", - action="store_true", - help="Do not print progress messages.", - ) - ARGUMENTS = PARSER.parse_args() - release = ARGUMENTS.release - unreleased = ARGUMENTS.unreleased - quiet = ARGUMENTS.quiet - if ARGUMENTS.checkonly: - check_all_contributions_valid( - release, quiet=quiet, unreleased=unreleased - ) - else: - run_compilation(release, quiet=quiet, unreleased=unreleased) diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Dec-02_cell_measure_concatenate.txt b/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Dec-02_cell_measure_concatenate.txt deleted file mode 100644 index 151341d9aff..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Dec-02_cell_measure_concatenate.txt +++ /dev/null @@ -1,2 +0,0 @@ -* Concatenating cubes along an axis shared by cell measures would cause concatenation to inappropriately fail. - These cell measures are now concatenated together in the resulting cube. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Nov-14_cell_measure_positional_argument.txt b/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Nov-14_cell_measure_positional_argument.txt deleted file mode 100644 index d43b5c2d446..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Nov-14_cell_measure_positional_argument.txt +++ /dev/null @@ -1,4 +0,0 @@ -* A :class:`iris.coords.CellMeasure` requires a string ``measure`` attribute to be defined, which can only have a value - of ``area`` or ``volume``. Previously, the ``measure`` was provided as a keyword argument to - :class:`~iris.coords.CellMeasure` with an default value of ``None``, which caused a ``TypeError`` when no - ``measure`` was provided. The default value of ``area`` is now used. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Nov-19_cell_measure_copy_loss.txt b/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Nov-19_cell_measure_copy_loss.txt deleted file mode 100644 index 3a0bbfaf568..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2019-Nov-19_cell_measure_copy_loss.txt +++ /dev/null @@ -1,2 +0,0 @@ -* Copying a cube would previously ignore any attached class:`iris.coords.CellMeasure`. - These are now copied over. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2020-Feb-13_cube_iter_remove.txt b/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2020-Feb-13_cube_iter_remove.txt deleted file mode 100644 index 082cd8acc81..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2020-Feb-13_cube_iter_remove.txt +++ /dev/null @@ -1,3 +0,0 @@ -* The `__iter__()` method in class:`iris.cube.Cube` was set to `None`. - `TypeError` is still raised if a `Cube` is iterated over but - `isinstance(cube, collections.Iterable)` now behaves as expected. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2020-Jun-15_remove_aux_factories_with_remove_coord.txt b/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2020-Jun-15_remove_aux_factories_with_remove_coord.txt deleted file mode 100644 index f5d88ab3570..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/bugfix_2020-Jun-15_remove_aux_factories_with_remove_coord.txt +++ /dev/null @@ -1,2 +0,0 @@ -* The method :meth:`~iris.Cube.cube.remove_coord` would fail to remove derived - coordinates, will now remove derived coordinates by removing aux_factories. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/deprecate_2019-Oct-11_remove_LBProc_flag_attributes.txt b/docs/iris/src/whatsnew/contributions_3.0.0/deprecate_2019-Oct-11_remove_LBProc_flag_attributes.txt deleted file mode 100644 index 56c14353161..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/deprecate_2019-Oct-11_remove_LBProc_flag_attributes.txt +++ /dev/null @@ -1,2 +0,0 @@ -* :attr:`iris.fileformats.pp.PPField.lbproc` is now an `int`. The - deprecated attributes `flag1`, `flag2` etc. have been removed from it. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/deprecate_2019-Oct-14_remove_deprecated_future_flags.txt b/docs/iris/src/whatsnew/contributions_3.0.0/deprecate_2019-Oct-14_remove_deprecated_future_flags.txt deleted file mode 100644 index 3bf515187b5..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/deprecate_2019-Oct-14_remove_deprecated_future_flags.txt +++ /dev/null @@ -1,3 +0,0 @@ -* The deprecated :class:`iris.Future` flags `cell_date_time_objects`, - `netcdf_promote`, `netcdf_no_unlimited` and `clip_latitudes` have - been removed. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2019-Dec-04_black_code_formatting.txt b/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2019-Dec-04_black_code_formatting.txt deleted file mode 100644 index 500a215bb97..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2019-Dec-04_black_code_formatting.txt +++ /dev/null @@ -1,6 +0,0 @@ -* Added support for the `black `_ code formatter. - This is now automatically checked on GitHub PRs, replacing the older, unittest-based - "iris.tests.test_coding_standards.TestCodeFormat". - Black provides automatic code format correction for most IDEs. - See the new developer guide section on this : - https://scitools-docs.github.io/iris/master/developers_guide/code_format.html. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-10_modernise_documentation_using_themes_and_readthedocs.txt b/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-10_modernise_documentation_using_themes_and_readthedocs.txt deleted file mode 100644 index 5ff8c001e8d..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-10_modernise_documentation_using_themes_and_readthedocs.txt +++ /dev/null @@ -1,2 +0,0 @@ -* Updated documentation to use a modern sphinx theme and be served from - https://scitools-iris.readthedocs.io/en/latest/. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-23_moved_gallery_entry.txt b/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-23_moved_gallery_entry.txt deleted file mode 100644 index d73021dcc9d..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-23_moved_gallery_entry.txt +++ /dev/null @@ -1,2 +0,0 @@ -* Moved the :ref:`sphx_glr_generated_gallery_oceanography_plot_orca_projection.py` - from the general part of the gallery to oceanography. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-12_remove_experimental_concatenate_module.txt b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-12_remove_experimental_concatenate_module.txt deleted file mode 100644 index 418377aabcb..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-12_remove_experimental_concatenate_module.txt +++ /dev/null @@ -1,3 +0,0 @@ -* The :mod:`iris.experimental.concatenate` module has now been removed. In ``v1.6.0`` the experimental `concatenate` - functionality was moved to the :meth:`iris.cube.CubeList.concatenate` method. Since then, calling the - :func:`iris.experimental.concatenate.concatenate` function raised an exception. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-13_move_experimental_equalise_cubes.txt b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-13_move_experimental_equalise_cubes.txt deleted file mode 100644 index a7ddaa441b4..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-13_move_experimental_equalise_cubes.txt +++ /dev/null @@ -1,3 +0,0 @@ -* The :func:`iris.experimental.equalise_cubes.equalise_attributes` function has been moved from the - :mod:`iris.experimental` module into the :mod:`iris.util` module. Please use the :func:`iris.util.equalise_attributes` - function instead. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-26_remove_coord_comparison.txt b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-26_remove_coord_comparison.txt deleted file mode 100644 index a8ba4131d07..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-26_remove_coord_comparison.txt +++ /dev/null @@ -1 +0,0 @@ -* The former function "iris.analysis.coord_comparison" has been removed. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2020-May-22_cubelist_extract_cubes.txt b/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2020-May-22_cubelist_extract_cubes.txt deleted file mode 100644 index ed8e6a8e2c5..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2020-May-22_cubelist_extract_cubes.txt +++ /dev/null @@ -1,10 +0,0 @@ -* The method :meth:`~iris.cube.CubeList.extract_strict`, and the 'strict' - keyword to :meth:`~iris.cube.CubeList.extract` method have been removed, and - are replaced by the new routines :meth:`~iris.cube.CubeList.extract_cube` and - :meth:`~iris.cube.CubeList.extract_cubes`. - The new routines perform the same operation, but in a style more like other - Iris functions such as :meth:`iris.load_cube` and :meth:`iris.load_cubes`. - Unlike 'strict extraction', the type of return value is now completely - consistent : :meth:`~iris.cube.CubeList.extract_cube` always returns a cube, - and :meth:`~iris.cube.CubeList.extract_cubes` always returns a CubeList of a - length equal to the number of constraints. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Dec-20_cache_area_weights.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Dec-20_cache_area_weights.txt deleted file mode 100644 index 8c9b7b95d23..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Dec-20_cache_area_weights.txt +++ /dev/null @@ -1,5 +0,0 @@ -* The area weights used when performing area weighted regridding with :class:`iris.analysis.AreaWeighted` - are now cached. - This allows a significant speedup when regridding multiple similar cubes, by repeatedly using - a `'regridder' object <../iris/iris/analysis.html?highlight=regridder#iris.analysis.AreaWeighted.regridder>`_ - which you created first. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Nov-27_cell_measure_statistics.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Nov-27_cell_measure_statistics.txt deleted file mode 100644 index cf8c83e5945..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Nov-27_cell_measure_statistics.txt +++ /dev/null @@ -1,5 +0,0 @@ -* Statistical operations :meth:`iris.cube.Cube.collapsed`, - :meth:`iris.cube.Cube.aggregated_by` and :meth:`iris.cube.Cube.rolling_window` - previously removed every :class:`iris.coord.CellMeasure` attached to the cube. - Now, a :class:`iris.coord.CellMeasure` will only be removed if it is associated - with an axis over which the statistic is being run. \ No newline at end of file diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-14_cf_ancillary_data.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-14_cf_ancillary_data.txt deleted file mode 100644 index ea70702f38c..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-14_cf_ancillary_data.txt +++ /dev/null @@ -1 +0,0 @@ -* CF Ancillary Variables are now supported in cubes. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_nameconstraint.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_nameconstraint.txt deleted file mode 100644 index eeb40990e24..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_nameconstraint.txt +++ /dev/null @@ -1 +0,0 @@ -* The :class:`~iris.NameConstraint` provides richer name constraint matching when loading or extracting against cubes, by supporting a constraint against any combination of ``standard_name``, ``long_name``, NetCDF ``var_name`` and ``STASH`` from the attributes dictionary of a :class:`~iris.cube.Cube`. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_names_property.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_names_property.txt deleted file mode 100644 index a0926311520..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_names_property.txt +++ /dev/null @@ -1 +0,0 @@ -* Cubes and coordinates now have a new ``names`` property that contains a tuple of the ``standard_name``, ``long_name``, NetCDF ``var_name``, and ``STASH`` attributes metadata. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_relaxed_name_loading.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_relaxed_name_loading.txt deleted file mode 100644 index 6773ac28b15..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-15_relaxed_name_loading.txt +++ /dev/null @@ -1 +0,0 @@ -* Name constraint matching against cubes during loading or extracting has been relaxed from strictly matching against the :meth:`~iris.cube.Cube.name`, to matching against either the ``standard_name``, ``long_name``, NetCDF ``var_name``, or ``STASH`` attributes metadata of a cube. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-17_unpin_mpl.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-17_unpin_mpl.txt deleted file mode 100644 index bbee87037a1..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2019-Oct-17_unpin_mpl.txt +++ /dev/null @@ -1,2 +0,0 @@ -* Supporting Iris for both Python2 and Python3 resulted in pinning our dependency on matplotlib at v2.x. - Now that Python2 support has been dropped, Iris is free to use the latest version of matplotlib. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-06_relax_geostationary.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-06_relax_geostationary.txt deleted file mode 100644 index e1113c838c8..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-06_relax_geostationary.txt +++ /dev/null @@ -1,6 +0,0 @@ -* :class:`iris.coord_systems.Geostationary` can now accept creation arguments of - `false_easting=None` or `false_northing=None`, equivalent to values of 0. - Previously these kwargs could be omitted, but could not be set to `None`. - This also enables loading netcdf data on a Geostationary grid, where either of these - keys is not present as a grid-mapping variable property : Previously, loading any - such data caused an exception. diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-31_nimrod_format_enhancement.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-31_nimrod_format_enhancement.txt deleted file mode 100644 index 18378691cb0..00000000000 --- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-31_nimrod_format_enhancement.txt +++ /dev/null @@ -1,3 +0,0 @@ -* The :class:`~iris.fileformats.nimrod` provides richer meta-data translation - when loading Nimrod-format data into cubes. This covers most known operational - use-cases. diff --git a/docs/iris/src/whatsnew/index.rst b/docs/iris/src/whatsnew/index.rst index 00b925a48e6..a574e7a6896 100644 --- a/docs/iris/src/whatsnew/index.rst +++ b/docs/iris/src/whatsnew/index.rst @@ -6,11 +6,11 @@ What's new in Iris These "What's new" pages describe the important changes between major Iris versions. + .. toctree:: :maxdepth: 1 latest.rst - 3.0.0.rst 2.4.rst 2.3.rst 2.2.rst diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst new file mode 100644 index 00000000000..a8057cf870c --- /dev/null +++ b/docs/iris/src/whatsnew/latest.rst @@ -0,0 +1,123 @@ + +************ + +This document explains the changes made to Iris for this release +(:doc:`View all changes `.) + + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + +* The :class:`~iris.fileformats.nimrod` provides richer meta-data translation + when loading Nimrod-format data into cubes. This covers most known + operational use-cases. + +* Statistical operations :meth:`iris.cube.Cube.collapsed`, + :meth:`iris.cube.Cube.aggregated_by` and :meth:`iris.cube.Cube.rolling_window` + previously removed every :class:`iris.coord.CellMeasure` attached to the + cube. Now, a :class:`iris.coord.CellMeasure` will only be removed if it is + associated with an axis over which the statistic is being run. + +* Supporting Iris for both Python2 and Python3 resulted in pinning our + dependency on matplotlib at v2.x. Now that Python2 support has been dropped, + Iris is free to use the latest version of matplotlib. + +* CF Ancillary Variables are now supported in cubes. + + +Bugs Fixed +========== + +* The method :meth:`~iris.Cube.cube.remove_coord` would fail to remove derived + coordinates, will now remove derived coordinates by removing aux_factories. + +* The `__iter__()` method in class:`iris.cube.Cube` was set to `None`. + `TypeError` is still raised if a `Cube` is iterated over but + `isinstance(cube, collections.Iterable)` now behaves as expected. + +* Concatenating cubes along an axis shared by cell measures would cause + concatenation to inappropriately fail. These cell measures are now + concatenated together in the resulting cube. + +* Copying a cube would previously ignore any attached + class:`iris.coords.CellMeasure`. These are now copied over. + +* A :class:`iris.coords.CellMeasure` requires a string ``measure`` attribute + to be defined, which can only have a value of ``area`` or ``volume``. + Previously, the ``measure`` was provided as a keyword argument to + :class:`~iris.coords.CellMeasure` with an default value of ``None``, which + caused a ``TypeError`` when no ``measure`` was provided. The default value + of ``area`` is now used. + + +Incompatible Changes +==================== + +* The method :meth:`~iris.cube.CubeList.extract_strict`, and the 'strict' + keyword to :meth:`~iris.cube.CubeList.extract` method have been removed, and + are replaced by the new routines :meth:`~iris.cube.CubeList.extract_cube` and + :meth:`~iris.cube.CubeList.extract_cubes`. + The new routines perform the same operation, but in a style more like other + Iris functions such as :meth:`iris.load_cube` and :meth:`iris.load_cubes`. + Unlike 'strict extraction', the type of return value is now completely + consistent : :meth:`~iris.cube.CubeList.extract_cube` always returns a cube, + and :meth:`~iris.cube.CubeList.extract_cubes` always returns a CubeList of a + length equal to the number of constraints. + +* The former function "iris.analysis.coord_comparison" has been removed. + +* The :func:`iris.experimental.equalise_cubes.equalise_attributes` function + has been moved from the :mod:`iris.experimental` module into the + :mod:`iris.util` module. Please use the :func:`iris.util.equalise_attributes` + function instead. + +* The :mod:`iris.experimental.concatenate` module has now been removed. In + ``v1.6.0`` the experimental `concatenate` functionality was moved to the + :meth:`iris.cube.CubeList.concatenate` method. Since then, calling the + :func:`iris.experimental.concatenate.concatenate` function raised an + exception. + + +Deprecations +============ + +* The deprecated :class:`iris.Future` flags `cell_date_time_objects`, + `netcdf_promote`, `netcdf_no_unlimited` and `clip_latitudes` have + been removed. + +* :attr:`iris.fileformats.pp.PPField.lbproc` is now an `int`. The + deprecated attributes `flag1`, `flag2` etc. have been removed from it. + + +Documentation +============= + +* Moved the :ref:`sphx_glr_generated_gallery_oceanography_plot_orca_projection.py` + from the general part of the gallery to oceanography. + +* Updated documentation to use a modern sphinx theme and be served from + https://scitools-iris.readthedocs.io/en/latest/. + +* Added support for the `black `_ code + formatter. This is now automatically checked on GitHub PRs, replacing the + older, unittest-based "iris.tests.test_coding_standards.TestCodeFormat". + Black provides automatic code format correction for most IDEs. See the new + developer guide section on :ref:`iris_code_format`. + +* Refreshed the :ref:`whats_new_contributions` for the :ref:`iris_whatsnew`. + This includes always creating the ``latest`` what's new page so it appears + on the latest documentation at + https://scitools-iris.readthedocs.io/en/latest/whatsnew. This resolves + :issue:`2104` and :issue:`3451`. Also updated the + :ref:`iris_development_releases_steps` to follow when making a release. + +* Enabled the pdf creation of the documentation on the `Read the Docs`_ service. + The pdf may be accessed by clicking on the version at the bottom of the side + bar, then selecting **pdf** from the downloads section. + +.. _Read the Docs: https://scitools-iris.readthedocs.io/en/latest/ diff --git a/docs/iris/src/whatsnew/latest.rst.template b/docs/iris/src/whatsnew/latest.rst.template new file mode 100644 index 00000000000..82f87d9e5ac --- /dev/null +++ b/docs/iris/src/whatsnew/latest.rst.template @@ -0,0 +1,46 @@ + +************ + +This document explains the changes made to Iris for this release +(:doc:`View all changes `.) + + +.. contents:: Skip to section: + :local: + :depth: 3 + + +Features +======== + +* N/A + + +Bugs Fixed +========== + +* N/A + + +Incompatible Changes +==================== + +* N/A + + +Dependencies +============ + +* N/A + + +Internal +======== + +* N/A + + +Documentation +============= + +* N/A \ No newline at end of file