.. _General-custom_file_loading:


Loading a cube from a custom file format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example shows how a custom text file can be loaded using the standard Iris
load mechanism.

The first stage in the process is to define an Iris :class:`FormatSpecification
<iris.io.format_picker.FormatSpecification>` for the file format. To create a
format specification we need to define the following:

* format_name - Some text that describes the format specification we are
  creating
* file_element - FileElement object describing the element which identifies
  this FormatSpecification.

  Possible values are:

    ``iris.io.format_picker.MagicNumber(n, o)``
        The n bytes from the file at offset o.

    ``iris.io.format_picker.FileExtension()``
        The file's extension.

    ``iris.io.format_picker.LeadingLine()``
        The first line of the file.

* file_element_value - The value that the file_element should take if a file
  matches this FormatSpecification
* handler (optional) - A generator function that will be called when the file
  specification has been identified. This function is provided by the user and
  provides the means to parse the whole file. If no handler function is
  provided, then identification is still possible without any handling.

  The handler function must define the following arguments:

  * list of filenames to process
  * callback function - An optional function to filter/alter the Iris cubes
    returned

  The handler function must be defined as generator which yields each cube as
  they are produced.

* priority (optional) - Integer giving a priority for considering this
  specification where higher priority means sooner consideration

In the following example, the function :func:`load_NAME_III` has been defined
to handle the loading of the raw data from the custom file format. This
function is called from :func:`NAME_to_cube` which uses this data to create and
yield Iris cubes.

In the ``main()`` function the filenames are loaded via the ``iris.load_cube``
function which automatically invokes the ``FormatSpecification`` we defined.
The cube returned from the load function is then used to produce a plot.



.. plot:: examples/General/custom_file_loading.py
    :include-source: