ChangeLog.txt

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.