Modules

Utilities to create a simple map of the Mermaid float locations.

author

Lucas Sawade (lsawade@princeton.edu), 2019

license

GNU Lesser General Public License, Version 3 (http://www.gnu.org/copyleft/lgpl.html):

Last Update:

September 2019

class merplot.mermaid_plot.GC

Bases: matplotlib.backend_bases.GraphicsContextBase

This class is unrelated to Mermaid, but fixes the issue of jagged Lines when creating a LineCollection by defining the capstyle as round.

class merplot.mermaid_plot.MermaidLocations(latitudes, longitudes, times=None, mermaid_names=None, lon_ticks=[160.0, 180.0, -180.0, -160.0, -140.0, -120.0, -100.0], lat_ticks=[-60, -40.0, -20.0, 0.0, 20.0], minlon=160.0, maxlon=260.0, minlat=-42.5, maxlat=5.0, central_longitude=180.0, mermaid_markersize=30, markerfontsize=None, legend=True, legend_cols=1, legend_title=None, fontsize=14, plot_labels=True, label_offset=-0.05, trajectories=True, trajectory_width=8, trajectory_cmp='gist_heat', wms=False, wms_url=None, wms_layer=None, frames=100, frames_per_sec=24, animation_writer='ffmpeg', movie_dpi=150, figsize=(15, 8))

Bases: object

Class that handles plotting of MERMAIDS using the vital file input. The underlying mapping tool box is Cartopy which is very powerful, but not yet fully grown. As a result Only the PlateCarree projection can be used as of now; hence, no option to vary this parameter in terms of plotting.

Usage:

# Create ML plotting class
ML = MermaidLocation.from_vit_file(vital_file_list)

# Plot full map
ML.plot()

activate_colorbar()

This activates the colorbar.

add_aux_data(lon, lat, **kwargs)

Adding auxiliary data.

Parameters

• lon (float or list of floats) – Longitudes

• lat – Latitudes

• kwargs – keyword arguments for matplotlib functions

Returns

animate(f=None, writer=None, **kwargs)

Animates the trajectories of the Mermaids…

Parameters

• f (str) – output file name

• writer (str) – name of movie writer. Overwrites class config.

auxiliary_data = None

Will be stored in form of dictionaries xdata:, ydata:, kwarg_dict

compute_second_record()

Takes in all times and creates smallest and largest number from max and min UTCDatetimes.

classmethod from_vit_file(vital_file_list, filter_dict=False, **kwargs)

Gets the content of the vital and parses it to the class. Parameters are the same as for the __init__ except the latitude, longitude, times, and mermaid_names

plot(f=None, **kwargs)

Plots everything.

Parameters

• f – Filename. No plot will be displayed, but a file will be generated.

• kwargs – Are parsed to pyplot.savefig if f is defined and to plt.show if f is None

plot_animation()

Plots animation of the trajectories

Warning

This method only works if you have defined the times!

The way this method works is, first all full segments to be drawn at each timestep are computed into lists as well as the final marker positions. These are then accessed by the update() function, which changes the location of the marker and adds the trajectory.

The update function is defined inside this function, as it has no meaning outside.

plot_aux_data()

Plot data that is added to the class prior to plotting.

plot_legend()

Plots legend with the given parameters

plot_map()

Plots the background map for float visualization and sets the axis and figure properties.

plot_markers()

This function uses the data included in MermaidLocations to plot the last positions of each Mermaid.

plot_trajectories()

This function uses the the complete data of latitude, longitude and times to plot the trajectories.

Warning

This method only works if you have defined the times!

merplot.mermaid_plot.custom_new_gc(self)

Returns new rendering class.

merplot.mermaid_plot.get_coordinates_from_kml_path(kml_file)

Reads .kml file and returns corresponding latitude and longitude lists. WARNING!!! Only works for kmls with a single path!

Parameters

kml_file (str) – path/to/kml_file

Returns

tuple with list of latitudes and list longitudes

Usage:

# KML file
kml_file = "<path/to/kml_file>"

# Get lats, lons
lat, lon = get_coordinates_from_kml_path(kml_file)

merplot.mermaid_plot.get_last_positions(vital_file_list)

Get all last positions of a list of vital files.

Parameters

vital_file_list –

Returns

prints list of last positions on the screen

merplot.mermaid_plot.get_positions(vital_file, filter_dict=False)

Reads vital file and the gps coordinates in it.

Parameters

• vital_file – path/to/your_float.vit

• filter_dict – This is a filter dictionary for the specific

Returns

tuple of three lists (dates, latitudes, longitudes)

Usage:

# Vital file
vit_file = "<path/to/<your_vital_file>.vit>"

# Get lats, lons
mermaid_name, dates, latitudes, longitudes = get_positions(vit_file, filter_dict)

merplot.mermaid_plot.max_UTC(UTC_list, ind=False)

Get first, latest time in a list of UTC

Parameters

• UTC_list – list of UTCDateTime stamps

• ind – boolean defining whether the index in list is supposed to be output. Default False

Returns

latest UTCDateTime stamp. If ind is True, tuple of (latest time stamp, index) is output.

Usage:

from mermaid_plot import max_UTC

# Assuming you have a list of UTCDateTimes
most_recent_UTC = max_UTC(<some_UTCDatetime_list>)

merplot.mermaid_plot.min_UTC(UTC_list, ind=False)

Get first, earliest time in a list of UTC

Parameters

• UTC_list – list of UTCDateTime stamps

• ind – boolean defining whether the index in list is supposed to be output. Default False

Returns

earliest UTCDateTime stamp. If ind is True, tuple of (earliest time stamp, index) is output.

Usage:

from mermaid_plot import max_UTC

# Assuming you have a list of UTCDateTimes
oldest_UTC = min_UTC(<some_UTCDatetime_list>)

merplot.mermaid_plot.plot_path(lon, lat, **kwargs)

Plots line on map.

Parameters

• lat – list of latitudes

• lon – list of logitudes

• kwargs – keyword arguments for plotting function

Returns

path handle

merplot.mermaid_plot.plot_point(lon, lat, size=2, **kwargs)

Plots line on map.

Parameters

• lat – one latitude degree

• lon – one longitude degree

• kwargs – keyword arguments for plotting function

Returns

plot handle

merplot.mermaid_plot.plot_text(text, lon, lat, **kwargs)

Plots line on map.

Parameters

• text – String with text input

• lat – one latitude degree

• lon – one longitude degree

• kwargs – keyword arguments for plotting function

Returns

text handle

merplot.mermaid_plot.read_yaml_file(filename)

Reads yaml file and returns dictionary with content.

Parameters

filename (str) – String with yaml file location

Returns

dict

Usage:

# Read the file
d = read_yaml_file(<some_yaml_file_location_as_string>)

value = d[key]