ChangeLog.txt

2.2
---

This release brings a lot of changes in the way we interact with unstructured grids, with expansion of the Domain and
FileReader classes. We have also added support for interacting with other model types via subclasses of RegularReader
and/or FileReader for HYCOM, CMEMS and NEMO outputs.

Since we spend a lot of our time interpolating data from one model grid to another, we have implemented a new
"interpolate" module which will host most of these routines. This will minimise the duplication of interpolation
routines for working with unstructured and structured grids.

- PyFVCOM.buoy
	- Fix a few small issues with the Buoy class.
- PyFVCOM.coast - remove this and put its functions in PyFVCOM.grid, mostly.

- PyFVCOM.coordinate
	- Update the british_national_grid_to_lonlat function to use PyProj instead of a convoluted conversion.
	- Add new function lonlat_decimal_from_degminsec_wco to handle Western Channel Observatory formatted time data.
	- Update the lonlat_decimal_from_degminsec function to fix bugs with negative longitudes between -1 and 0.

- PyFVCOM.current
	- Minor fixes to remove the use of removed methods on self.

- PyFVCOM.grid
	- Fix handling subsampling in space for combinations of nodes and elements. We now check for incompatible pairings
	and act accordingly (GridReaderNetCDF).
	- Fix loading data for sets of nodes/elements to be a lot faster. The old way was a) inexplicably complicated and
	b (GridReaderNetCDF).
	slow. The new way is a) simple and b) faster (GridReaderNetCDF). Win win.
	- Fix loading only vertical layers (no other dimensions) (GridReaderNetCDF).
	- Fix depths when loading vertical layers (the _z arrays now have the correct signs) (GridReaderNetCDF).
	- Add method on Domain (subset_domain) which will subset with a given shapely Polygon or interactively.
	- Add new function (subset_domain) which subsets interactively or with a given shapely Polgyon.
	- Add a few new methods on Domain to do some useful things:
		- calculate_control_area_and_volume - calculates control areas and volumes.
		- calculate_element_lengths - calculate the length of the element faces.
		- gradient - compute the gradient of a field.
		- to_nodes - move a field from elements to nodes.
		- to_elements - move a field from nodes to elements.
		- in_element - is a given position in a given element?
		- exterior - return the exterior boundary of the current grid.
		- info - print some basic information about the loaded grid.
	- Fix loading open boundaries from SMS grid which have duplicated start and end nodes in the node string.
	- OpenBoundary.add_tpxo_tides can now be given an interpolation method ('linear', 'nearest' etc.).
	- Fix issue in OpenBoundary._interpolate_tpxo_harmonics where the interpolated phase was across the 360 to 0 degrees
	transition. We now do the interpolation on the components of amplitude and phase (u and v) instead and recombine to
	get amplitude and phase from those.
	- Interpolating data in OpenBoundary.add_nested_forcing now handles internal land masses correctly.
	- OpenBoundary.add_nested_forcing can also now interpolate from sigma coarse model data (e.g. NEMO output).
	- New function to read an SMS map file (read_sms_map).
	- New function to read in smeshing mesh files (read_smesh_mesh).
	- Add the read_sms_cst function from the (now removed) PyFVCOM.coast module.
	- Add the write_sms_cst function from the (now removed) PyFVCOM.coast module.
	- Add the MIKEarc2cst function from the (now removed) PyFVCOM.coast module.
	- Add the shp2cst function from the (now removed) PyFVCOM.coast module.
	- Simplify the code in write_sms_mesh a little.
	- The function get_boundary_polygons can now be given a set of nodes to identify whether they are interior or
	exterior to the grid (i.e. islands or not).
	- The control_volumes function can optionally return the coordinates of the node control areas. This is useful for
	plotting things.
	- In reduce_triangulation, make sure the nodes to which we are reducing the grid are sorted otherwise the reduced
	triangulation is all sorts of broken.
	- Add new function to return the exterior boundary of a model grid (model_exterior).
	- Add new function to apply the UGRID conventions to an FVCOM netCDF file (fvcom2ugrid).
	- Add new function to identify whether a given point lies within a given pixel (point_in_pixel).
	- Add new function to move a node-based field to an element-based field using a cubic interpolation rather than
	linear (as is done in elems2nodes).

- PyFVCOM.interpolate
	- Add new module to handle interpolations.
	- Function mask_to_fvcom constructs a mask for a list of points which is True for points outside the FVCOM domain
	and False inside.
	- Function mask_to_fvcom_meshgrid to mask a regularly gridded set of coordinates to an FVCOM grid.
	- MPIRegularInterpolateWorker is a class to handle interpolation using MPI instead of multiprocessing (which is what
	we tend to use elsewhere).

- PyFVCOM.ocean
	- Add function to compute the CFL number.
	- Add function to compute the turbulent kinetic energy from a velocity field (largely untested).

- PyFVCOM.plot
	- Add support for plotting with cartopy instead of Basemap. The default is still the latter. Use the 'mapper'
	keyword in Plotter.
	- Fix the orientation of slice plots in Time.plot_slice and Time.plot_surface.
	- Add new methods on Plotter to plot streamlines (plot_streamlines), add scales (add_scale), set a title (set_title),
	reinitialise a plot (replot) and close the current figure (close).
	- Remove some options which were largely historic leftovers from the PyLag version of this class.
	- Handle masking when plotting surfaces with Plotter.plot_field.
	- Add option to interpolate quivers onto a regular grid.
	- Tweaks the set up when plotting in parallel with MPIWorker.
	- Add the ability to plot streamlines with MPIWorker.
	- Add new class to interactively animate FVCOM output (Player).
	- Add new function to find the colour bar extension for a given field and current plot range.

- PyFVCOM.preproc
	- Force times in the SST data to be at midday (a requirement for FVCOM).
	- Add support for generalised sigma coordinates in Model.
	- Fix indices for writing out tidal elevation files.
	- Add method (read_ea_river_temperature_climatology) on Model to read in the English Environment Agency River
	Temperature archive data.
	- New method (load_nested_forcing) to add an existing FVCOM nesting file's data to the current set of nests in
	a Model.
	- Add support for writing out ERSEM variables to a nested forcing netCDF file.
	- Add option to write groundwater at the surface for my customised FVCOM "surfacewater" code.
	- Add method to load an existing elevation time series from netCDF (load_elevtide).
	- Add method to write a standard FVCOM temperature and salinity open boundary forcing file (write_tsobc).
	- Concatenation in time for FileReader-like object (RegularReader, HYCOMReader etc.) now done with >> rather than
	+=.
	- Add a FileReader-like object for interacting with NEMO data (NEMOReader). This has the option to convert the NEMO
	grid into an unstructured grid for use with many of our existing tools.
	- Add a NEMO restart class to make restart files for FVCOM from NEMO data.

- PyFVCOM.read
	- Add new method to export data from a FileReader object to an Excel spreadsheet.
	- Fix removal of dodgy times from the file being read in (FileReader).
	- Force times read in from an FVCOM averaged file to be at the midpoint of the time interval instead of the end.
	- Add methods to add, subtract, multiply, divide and raise to a power FileReader objects (or rather, the data that
	has been loaded in them).
	- The concatenation in time of FileReader objects is now achieved with >> rather than +=.
	- New function to read in nesting nodes from an FVCOM netCDF nesting file (read_nesting_nodes).
	- New function to apply a mask to specified variables (apply_mask).
	- Set the zero indexing option on get_river_config to default to True.
	- Add new class to write a FileReader object to netCDF (WriteFVCOM).

- PyFVCOM.stats
	- Set the minimum number of samples required for computation of a correlation coefficient as an argument rather than
	hard-coding it.

- PyFVCOM.tide
	- Miscellaneous minor fixes.

- PyFVCOM.utilities
	- New functions to convert from polar to cartesian coordinates and back (general.cart2pol and general.pol2cart).
	- Renamed the _passive_data_store class to PassiveStore.
	- Fix bug with general.fix_range where all values are identical, in which case we return the values unchanged.
	- Move the `grid` utility StubFile into the tests (the only place it was being used).

- PyFVCOM.validation
	- PEP8 compliance fixes.

- Existing tests have been updated to reflect bug fixes and new functionality (to a limited extent).


2.1.3
-----

Re-release 2.1.2 without my in-progress changes.

2.1.2
-----

Fix the PyPI archive.

2.1.1
-----

Fix version number in __init__.py.

2.1.0
-----

Added functions for generating input files for running FVCOM.

Also miscellaneous changes across the rest of the toolbox.

All deprecated functions from v2.0.0 have been removed.

Major changes
-------------

- PyFVCOM.preproc
    - Provides a new `Model' class which provides methods for generating input
    files for FVCOM.

    - At the moment, this includes:
        - casename_grd.dat - model grid.
        - casename_dep.dat - depth file.
        - casename_z0.dat - bed roughness file.
        - casename_obc.dat - model open boundaries.
        - casename_spg.dat - sponge layer.
        - casename_cor.dat - Coriolis file.
        - casename_sigma.dat - Sigma coordinate file.
        - casename_riv.nc - River forcing (including ERSEM support).
        - casename_riv.nml - River forcing configuration.
        - casename_elevtide.nc - Tidal forcing at the boundary.
        - casename_tsobc.nc - Temperature and salinity at the open boundary.
        - casename_groundwater.nc - Groundwater input.
        - casename_nest.nc - Nested forcing from another model (e.g. regularly
        gridded data interpolated onto the FVCOM grid).
        - casename_probes.dat - A probe configuration file.
        - casename_stations.dat - A stations configuration file.
        - casename_sstgrd.nc - Sea surface temperature data assimilation input.
        - casename_adygrd.nc - Gelbstoff absorption file for the given FVCOM
        domain for ERSEM.
        - casename_restart.nc - A modified FVCOM restart file.

    - There is a corresponding examples/pyfvcom_preprocessing_example.ipynb
    Jupyter Notebook to illustrate how to use this functionality.

    - A new ModelNameList class also allows for the easy creation and writing
    of FVCOM namelists, including support for FABM.
    - Also provides a Nest class for configuring nested inputs.
    - New WriteForcing class creates netCDF forcing files for FVCOM.
    - A class for reading regularly gridded data (RegularReader) to mimic the
    behavious of PyFVCOM.read.FileReader.
    - A class for reading HYCOM data in the same vein as RegularReader.
    - A class for handling restart data (Restart) for replacing data with
    arbitrary data.


Minor changes
-------------

- PyFVCOM.buoy
    - Added a new class to handle buoy time series data. At the moment, this is
    mainly focused on using data from the Western Channel Observatory
    (http://www.westernchannelobservatory.org.uk) and the British Oceanographic
    Data Centre (http://www.bodc.ac.uk).

- PyFVCOM.coordinate
    - New function to convert from degrees minutes seconds to decimal degrees.

- PyFVCOM.ctd
    - Added a new CTD class to hold CTD data. Again, this is mainly focused on
    using data from the Western Channel Observatory and BODC.

- PyFVCOM.current
    - Mostly minor code tweaks.
    - vector2scalar can now optionally use a vertical vector when calculating
    speed.
    - progressive_vectors: new function to calculate progressive vectors from
    a time series of u and v.
    - principal_axis: fix the orientation of the resulting axis (was formerly
    90 degrees out).

- PyFVCOM.grid
    - Add a new Domain class which forms the basis of the functions which deal
    with FVCOM grids (e.g. PyFVCOM.read.FileReader). This is also used in the
    preprocessing tools.
    - A new class has been added to handle open boundaries, specifically with
    a view to using them for generating boundary forcing in models.
    - New function (parse_obc_sections) to split an open boundary file from
    a list of open boundary nodes.
    - The function to find the closest node or element in the model grid has
    been updated to use a KDTree making it much faster for a large number of
    points.
    - New function (element_sample) will sampling along a set of positions
    returning the elements which fall closest to the lines between those
    positions.
    - New function get_area_heron will return the area of an element using
    Heron's formula.
    - Graph class to work with the model grid using graph theoretic functions.
    - ReducedFVCOMdist class worked with an FVCOM subdomain
    - GraphFVCOMdepth sets up a graph of an FVCOM grid weighting the edges by
    depth. This is useful for finding a channel between two arbitrary points
    e.g. find the centre of a river channel.
    - The function node_control_area has a new argument to return the
    positions of the polygon which makes up the node control area.
    - New function clockwise will order points clockwise from North.
    - New function parse_obc_sections to separate each open boundary from a
    list of open boundary nodes.
    - Removed fix_coordinates.
    - Removed clip_triangulation (better to use reduce_triangulation instead).
    - Moved get_river_config and get_rivers to `PyFVCOM.read'.

- PyFVCOM.ocean
    - Make the depth-averaging work with less fiddling around trying to find
    out what dimensions we've got.
    - Add support to mld for more dimensions in the density supplied when
    calculating mixed layer depth.
    - Minor tweak to the mixed layer depth function (support for higher
    dimension arrays).

- PyFVCOM.plot
    - New Depth class for plotting depth-resolved slice plots from FVCOM
    outputs.
    - Tweaks to the Time time-series plotting class and the Plotter grid
    plotting class.
    - New function to quickly plot a domain (plot_domain).
    - New worker function intended to facilitate plotting in parallel with
    MPI. Takes a series of time IDs and plots those data only.

- PyFVCOM.read
    - Indexing for dimensions is now the same for all dimensions (including
    time). Previously only a range could be given for time, but now time works
    the same as the other dimensions.
    - FileReader can now receive either a file string or a netCDF4 Dataset
    object.
    - Improve the handling of missing data in files being read by FileReader.
    - FileReader is now a superclass of PyFVCOM.grid.Domain, so a lot of the
    code has been moved into there.
    - Add new method to time average a variable.
    - Add new method to add river flow data to the object.
    - Add new method to calculate the grid volume.
    - Add new method to calculate the total volume of given variable over time.
    - Add new method to calcualte the average volume of a given variable.
    - Add new method to average a given variable at a given time interval.
    - Grid metrics are now loaded by default.
    - New class (SubDomainReader) for reading a subdomain of an FVCOM grid, by
    either interactively selecting a region or specifying one as coordinates.
    This class includes methods for integrating fields within the subdomain.
    - New function for reading a river configuration file.

- PyFVCOM.stats
    - Minor fixes.

- PyFVCOM.tide
    - New class to write harmonic analysis output to an FVCOM-style netCDF file.

- PyFVCOM.validation
    - Tweak the database handling code.
    - New class for comparison with ICES bottle data.

- PyFVCOM.utilities
    - New function for flattening nested lists (general.flatten_list).
    - New function (general.split_string) to split a list of strings on a given
    separators.
    - New function to make a ramped signal (time.ramped_signal).
    - general.ObjectFromDict converts an object into a dictionary with
    attributes named from the dictionary keys.
    - general.cleanhtml removes markup leaving only text.
    - grid.cfl calculates the CFL number for a model output file from the
    velocity fields.
    - general.fvcom2ugrid adds the necessary metadata to an existing FVCOM
    output file to make it compatible with the UGRID conventions:
    https://github.com/ugrid-conventions/ugrid-conventions.


2.0.0
-----

Major reorganisation of the toolbox with non-backward compatible changes.

We've added a few new classes which should simplfy interacting with FVCOM
model outputs.

The module names have also been rationalised and methods/functions which were
in illogical modules have been moved to more sensible places.

The old and new module names are:

buoy_tools    -> buoy
cst_tools     -> coast
ll2utm        -> coordinate
ctd_tools     -> ctd
current_tools -> current
grid_tools    -> grid
ocean_tools   -> ocean
read_results  -> read
stats_tools   -> stats
tide_tools    -> tide
              -> validation

Major changes
-------------

- PyFVCOM.coordinate is home to british_national_grid_to_lonlat (formerly
PyFVCOM.grid.OSGB36_to_WGS84). The old LL_to_UTM and UTM_to_LL functions are
deprecated (in favour of lonlat_from_utm and utm_from_lonlat, respectively).

- PyFVCOM.current has a new Residual class which calculates residual vectors
(that is the difference) from two time series of currents. We mostly use this
to identify the non-tidal currents by comparing modelled currents with
currents predicted from tidal constituents.

- PyFVCOM.process_tools has had most of its outdated CO2 functions removed and
the remaining function has been subsumed into PyFVCOM.current.

- PyFVCOM.grid has a lot of new functions, including:
    - find_connected_nodes (formerly surrounders)
    - find_connected_elements
    - find_bad_node
    - trigradient
    - rotate_points
    - get_boundary_polygons
    - get_attached_unique_nodes
    - grid_metrics
    - control_volumes
    - node_control_area
    - element_control_area
    - vincenty_distance
    - haversine_distance
    - shape_coefficients
    - getcrosssectiontriangles
    - isintriangle

- PyFVCOM.grid is also the new home of:
    - unstructured_grid_volume (formerly in PyFVCOM.process_results)
    - elems2nodes (formerly in PyFVCOM.read)
    - nodes2elems (formerly in PyFVCOM.read)

- PyFVCOM.ocean has had a couple of functions which didn't work removed
(sw_sal80 and sw_salinity).

- PyFVCOM.plot has modifications to Plotter to return more useful bits of the
figure (axes, scatter, tripcolor etc.). There is also a new class (Time) which
will plot time series data in a similar manner to Plotter will for maps.

- PyFVCOM.read has a new FileReader class which takes an FVCOM model output
file and does a lot of preprocessing on it to make it easier to use with
Python. This includes:
    - adding missing spatial coordinates (e.g. creating spherical from
    cartesian and vice versa).
    - adding missing time representations (e.g. creating Modified Julian Days
    from the Times string).
    - creating python datetime objects.
    - fixing broken triangulation tables.
    - loading data within a bounding box.

- The PyFVCOM.read FileReader class also allows subsetting in time and space and
can return a user-defined list of variables (in addition to the space and time
variables, which are always loaded). FileReader objects can also append other
FileReader objects, so you can easily create long time series representations.

- The node and element swapping functions (nodes2elems and elems2nodes) have
been moved from PyFVCOM.read to PyFVCOM.grid as that seems a more fitting
place for them.

- PyFVCOM.stats has lost fix_range to PyFVCOM.utilities. The
coefficient_of_determination has also been renamed to calculate_coefficient to
reflect its function and make the name shorted.

- PyFVCOM.tide has also lost julian_day, gregorian_date, common_time and overlap
to PyFVCOM.utilities.

- PyFVCOM.validation has been added and provides some tools for comparing
FVCOM model output with observations.

- Finally, the top-level tests subdirectory contains some nosetests for most of
the toolbox. The aim is that all new functions have corresponding tests added
(where appropriate) so we can ensure functionality is maintained into the
future.


1.6.2
-----

Fix broken functionality by using the right name for a function.


1.6.1
-----

Fix version numbers. Eventually I'll get this right.


1.6
---

Fairly major overhaul. This includes a complete rewrite of the coordinate
conversion utilites as well as the inclusion of a new module to facilitate
plotting FVCOM outputs.

grid_tools:
    * Improve the quality of the calculated area (fewer floating point
    precision issues). Add compatibility function following the rename.

ll2utm:
    * This function has been completely rewritten to (hopefully) speed up
    conversions of large numbers of positions. All the existing functionality
    remains (including compatibility functions).

plot:
    * New function to provide a nice plotting class (`Plotter') which can
    plot:
        - FVCOM 2D fields
        - FVCOM 2D vectors as quivers
        - Time varying arrays of lines (e.g. particle trajectories)
        - Scatter data on a map
    This function has been subsumed from PyLag-tools.


1.5.1
-----

Fix version numbers in setup.py.

1.5
---

Add better support for using datetime objects with netCDF and FVCOM ASCII
outputs. Improve the behaviour of a number of routines to offer more robust
behaviour. Ensure code works with Python 3.

buoy_tools:
    * Make SQLite3 an optional dependency and quit if we try and use it.

ctd_tools:
    * Make SQLite3 an optional dependency and quit if we try and use it.

grid_tools:
    * read_sms_mesh: Add support for returning the node strings (if any).
    * read_fvcom_obc: New function to read FVCOM formatted open boundary
    files.
    * write_fvcom_mesh: New function to write FVCOM formatted mesh files.
    * line_sample: Tweak the algorithm to be a bit more robust.
    * find_connected_elements: New function to find the elements connected to
    a specific node(s).
    * ind2sub: Replicate the MATLAB ind2sub function in Python.
    * rotate_points: Given a set of points and an origin, rotate by a certain
    angle.
    * make_water_column: Make a depth-resolved, time varying water column.

ll2utm:
    * Improve documentation.

ocean_tools:
    * Miscellaneous code tweaks.

read_results:
    * ncwrite: Add the option of specifying a certain netCDF format.
    * ncread: Improve support for converting times to datetime objects. Also
    read in all attributes for the requested variables.
    * read_probes: Add option to convert times to datetime objects.

stats_tools:
    * coefficient_of_determination: Removed.
    * calculate_coefficient: Added new function to calculate pearson's R and
    p-values.

tide_tools:
    * Make SQLite3 an optional dependency and quit if we try and use it.
    * overlap: New function to tell whether two time ranges overlap one
    another.
    * Improve documentation.


1.4.1
-----

Satisfy PyPI packaging rules that mean you can't overwrite an existing
version. So, we have 1.4.1 which is functionally identical to 1.4.0 but with
a different version number.


1.4.0
-----

Add new flag to ncread to provide python datetimes from FVCOM output.
Remove the TAPPY functions and transfer them to the main TAPPY project
(https://gitlab.ecosystem-modelling.pml.ac.uk/pica/tappy or
https://github.com/pwcazenave/tappy/).

read_results:
    * ncread has a new optional flag (`datetimes') to convert FVCOM Modified
    Julian Days to Python datetime objects. This only occurs if a time
    variable (`Times' or `time') has been requested in `vars' or if no
    specific variables have been requested (i.e. `vars' is empty).

tide_tools:
    * Remove TAPPY and run_TAPPY since those functions now exist in the main
    TAPPY project.


1.3.3
-----

More leftover bugs in ncread due to its renaming.


1.3.2
-----

Fix showstopper bug in ncread (due to the rename from readFVCOM to ncread).

Also fix references in the documentation to deprecated function names.


1.3.1
-----

This minor version adds a better error message if TAPPY is not found
(including a link to where to get it).

The bulk of the changes is a correction of the deprecation warnings.

The setup.py also includes a list of dependencies which should be
automatically resolved at installation time.

Specific changes:

grid_tools:
    * Update the triangulation tool to the not deprecated version in
    matplotlib.


1.3
---

The major aspect of this release is a harmonisation of the naming scheme for
the functions in the toolbox. The new naming more closely follows the PEP8
recommendation of lower case function names (ome old functions used camel
case). The old function names are retained as wrappers around the new
functions with a warning that they are deprecated.

Along the same lines, the redundant FVCOM in the process_FVCOM_results and
read_FVCOM_results files have been removed. Again, the old names exist for
backwards compatibility but will be removed in the future.

This release also removes a (slightly dodgy) function called img2xyz which
attempted to convert an RGB array to xyz data. It was far from perfect, so
it's now gone.

README.md:
    * Add the new function names to the README (and add some missing ones).
    * Updated with accurate installation instructions (pip vs. setup.py).
    * Also updated the version numbers for the dependencies against which
    PyFVCOM has been tested.
    * The examples section has been removed and a note about the notebooks put
    in its place instead.


1.2.1
-----

Fix version number and links in the setup.py.


1.2
---

Since PyFVCOM is on PyPI (and can therefore be installed with pip), the
version scheme has changed from date to major.minor.release.

Rather than bundling TAPPY within this toolbox, this version imports my forked
version of TAPPY, available from:

    https://github.com/pwcazenave/tappy
    http://gitlab.em.pml.ac.uk/pica/tappy

- The print statements have been replaced by the print function as a move
towards Python 3 compatibility.

- Added a new examples directory with Jupyter (iPython) notebooks of the
examples in the README.

- Update setup.py and add setup.cfg and the MIT licence so PyFVCOM can be
uploaded to PyPI.

Other changes:

grid_tools:
    * lineSample can now return the distance along the line (for better
    plotting).

process_FVCOM_results:
    * Remove unused import.

read_FVCOM_results:
    * writeProbes: new function to export data in FVCOM probes format.

tide_tools:
    * Move the imports to the top of the file.
    * julianDay now better support single values and arrays.
    * gregorianDate now also works with single values.
    * New wrapper around TAPPy called TAPPY to maintain backwards
    compatibility with existing scripts.


20151103
--------

Some new functions (see below) and a general tidy up of the code formatting.

buoy_tools:
    * Miscellaneous code clean ups.
cst_tools:
    * Miscellaneous code clean ups.
ctd_tools:
    * Miscellaneous code clean ups.
current_tools:
    * Miscellaneous code clean ups.
    * scalar2vector: New function to take a direction and speed and return
    the vector components of those values.
    * vector2scalar: New function to reverse scalar2vector and return speed
    and direction from a given pair of vector components.
grid_tools:
    * Miscellaneous code clean ups.
    * surrounders: Find the node IDs surrounding a given node.
    * heron: New function to calculate the area of a triangle given its corner
    coordines.
ll2utm:
    * Miscellaneous code clean ups.
ocean_tools:
    * Miscellaneous code clean ups.
    * dissipation: New function to calculate tidal dissipation for a given
    tidal harmonic.
    * calculate_rhum: New function to calculate relative humidity from dew
    temperature and ambient temperature.
process_FVCOM_results:
    * Miscellaneous code clean ups.
read_FVCOM_results:
    * Miscellaneous code clean ups.
stats_tools:
    * Miscellaneous code clean ups.
    * fixRange: New function to scale a set of values between a specified
    minimum and maximum.
    * rmse: New function to calculate the Root Mean Squared Error of a given
    data set.
tappy:
    * Miscellaneous code clean ups.
    * Don't assume where python lives.
tidal_ellipse:
    * Miscellaneous code clean ups.
tide_tools:
    * Miscellaneous code clean ups.
    * julianDay: Convert the function to use an external library (jdcal)
    instead of a slightly fragile and not particularly clean implementation.
    * gregorianDate: Use the same jdcal library for the conversion.
README.md:
    * Add new dependency (jdcal).


20150122
--------

Add a few new functions, expand some others (maintaining backward
compatibility) and fix some bugs.

cst_tools:
    * writeCST: New function to write out a CST file for a given set of arcs.
grid_tools:
    * Remove unused import math.
    * lineSample: Fix (in a manner of speaking) a bug when creating a transect
    through an unstructured grid.
    * connectivity: Fix docstring to be correct for one of the outputs.
ocean_tools:
    * zbar: Add support for time varying arrays.
    * pea: Add support for time varying arrays.
    * simpsonhunter: New function to calculate the Simpson-Hunter parameter
    for some velocity and depth data.
    * mixedlayerdepth: New function to calculate the mixed layer depth (as
    defined in ERSEM).
    * stokes: Initial attempt at calculating the Stokes number as a predictor
    of front locations (in the same vein as simpsonhunter). As yet unfinished
    but may be useful to someone as is.
read_FVCOM_results:
    * readFVCOM: Add support for exporing the global attributes from a netCDF
    file.
    * ncwrite: Add function to write netCDF files.
    * readProbes: Add support for returning the location of each probe.
tappy:
    * Make the code python3 safe.
tide_tools:
    * getObservedMetedata: Tidy the docstring.


20140804
--------

Changes since the last release.

buoy_tools:
    * Tidy up all the import statements to be at the beginning of the file.
cst_tools:
    * Tidy up all the import statements to be at the beginning of the file.
    * readCST: Fix the way the end of a vertex is identified to be more
    robust.
ctd_tools:
    * Tidy up all the import statements to be at the beginning of the file.
grid_tools:
    * Tidy up all the import statements to be at the beginning of the file.
    * Remove the plotUnstructuredGrid, plotUnstructuredGridProjected and
    plotCoast functions as they were pretty basic and only replicated half
    a dozen lines of matplotlib which is better demonstrated in the examples
    given on the wiki.
ocean_tools:
    * pea: new function to calculate the potential energy anomaly from
    temperature, salinity and depth.
    * zbar: new function to calculate the depth averaged value of an input.
    Naive implementation with a loop which can almost certainly be optimised
    significantly.
    * dens_jackett: add support for arrays of pressure as opposed to single
    values.
    * _tests: add a test for the conversion from depth to pressure using the
    output of the pressure2depth.
process_FVCOM_results:
    * Tidy up all the import statements to be at the beginning of the file.
read_FVCOM_results:
    * Tidy up all the import statements to be at the beginning of the file.
    * elems2nodes: fix the function to support n-dimensional arrays (rather
    than being limited to 2D arrays).
stats_tools:
    * Tidy up all the import statements to be at the beginning of the file.
tidal_ellipse:
    * Tidy up all the import statements to be at the beginning of the file.
tide_tools:
    * gregorianDate: fix issue with some month numbers being returned as zero.

README.md
    * Remove some old dependencies (mainly to do with the shapefile plotting
    routine which has now been removed).
    * Also update the list of functions provided by each group of functions.


20140422
--------

Changes since the last release.

buoy_tools:
    * getCTDMetadata: read CTD metadata from an SQLite3 data base.
    * getCTDData: extract CTD data from an SQLite3 dadta base.
cst_tools:
    * readCST: read SMS CST files into a dict for each specified arc.
img2xyz:
    * rgb2z: Crude attempt at converting RGB images to depths.
ll2utm:
    * Code clean up and ability to work with arrays. Also included some tests
    to ensure further changes don't negatively impact on the results.
read_FVCOM_results:
    * ncread: wrapper around readFVCOM with a more generic name since the
    function is not specific to FVCOM, but works with any netCDF file.
    * readProbes: read in FVCOM probes outputs (both 1 and 2D data).

README.md:
    * Added new functions to the list of functions.


20140221
--------

grid_tools:
    * parseUnstructuredGridGMSH: new function to read GMSH unstructured grids.
    * OSGB36toWGS84: new function to convert from British National Grid to
    spherical (WGS84).
    * connectivity: new function to calculate the connectivity of an
    unstructured grid (e.g. find the boundary).
ll2utm:
    * Update the function to use arrays of positions rather than single
    positions.
    * Also add some tests to make sure things don't break with the new
    changes.
ocean_tools:
    * cond2salt: new function to convert conductivity to salinity (assuming
    temperature constant at 25 Celsius).
read_FVCOM_results:
    * readFVCOM: update to try aggregating multiple files along a dimension
    called 'time' if unsuccessful with the automatic aggregation.

README.md:
    * Add example code section for some simple plots.