dorado.routines

Higher level methods for routing and visualizing tracer particles.

Project Homepage: https://github.com/passaH2O/dorado

dorado.routines.animate_plots(start_val, end_val, folder_name)

Animation routine, requires an optional animation writer.

Routine to make mp4 animation of the particle routing from png outputs of the previous plotting routines.

Inputs :

start_valint

Number of first plot to use

end_valint

Number of last plot to use

folder_namestr

Name of output folder to get results from

Outputs :

Saves an mp4 animation to the results folder

dorado.routines.draw_travel_path(grid, walk_data, particles_to_follow='all', output_file='travel_paths.png', interval=1, plot_legend=False)

Make a plot with the travel path of specified particles drawn out.

Inputs :

gridnumpy.ndarray

A 2-D grid upon which the particles will be plotted. Examples of grids that might be nice to use are dorado.particle_track.modelParams.depth, dorado.particle_track.modelParams.stage, dorado.particle_track.modelParams.topography.

walk_datadict

Output of steady_plots, unsteady_plots, time_plots, as well as the particle_track.run_iteration method.

particles_to_followlist, optional

List of particle numbers for which to draw the travel paths. Default is all particles.

output_filestr, optional

Path to save the output image to.

intervalint, optional

Determines how “smooth” each particle trajectory appears by skipping iterations between successive points on the path. Default it to show every iteration

plot_legendbool, optional

Controls whether resulting plot includes a legend of particle IDs. Default is False

Outputs :

Saves a plot of particle travel paths.

dorado.routines.get_state(walk_data, iteration=-1, verbose=True)

Pull walk_data values from a specific iteration.

Routine to return slices of the walk_data dict at a given iteration #. This function provides a shortcut to ‘smart’ indexing of the dict. By default returns information on the most recent step

Inputs :

walk_datadict

Dictionary of all x and y locations and travel times

iterationint, optional

Iteration number at which to slice the dictionary. Defaults to -1, i.e. the most recent step

verbosebool, optional

Toggles whether or not messages print to the console. If False, nothing is output, if True, messages are output. Default value is True. Errors are always raised.

Outputs :

xindslist

List containing equivalent of walk_data[‘xinds’][:][iteration]

yindslist

List containing equivalent of walk_data[‘yinds’][:][iteration]

timeslist

List containing equivalent of walk_data[‘travel_times’][:][iteration]

dorado.routines.get_time_state(walk_data, target_time, verbose=True)

Pull walk_data values nearest to a specific time.

Routine to return slices of the walk_data dict at a given travel time. This function provides a shortcut to ‘smart’ indexing of the dict.

Inputs :

walk_datadict

Dictionary of all x and y locations and travel times

target_timefloat

Travel time at which to slice the dictionary.

verbosebool, optional

Toggles whether or not messages print to the console. If False, nothing is output, if True, messages are output. Default value is True. Errors are always raised.

Outputs :

xindslist

List containing equivalent of walk_data[‘xinds’][:][i], where i represents the index at which travel time is nearest to input.

yindslist

List containing equivalent of walk_data[‘yinds’][:][i], where i represents the index at which travel time is nearest to input.

timeslist

List containing equivalent of walk_data[‘travel_times’][:][i], where i represents the index at which travel time is nearest to input. Times will differ slightly from input time due to the nature of the method.

dorado.routines.plot_exposure_time(walk_data, exposure_times, folder_name=None, timedelta=1, nbins=100, save_output=True, verbose=True)

Plot exposure time distribution of particles in a specified region.

Function to plot the exposure time distribution (ETD) of particles to the specified region. Relies on the output of particle_track.exposure_time

Inputs :

walk_datadict

Output of a previous function call to run_iteration.

exposure_timeslist

List [] of floats containing the output of particle_track.exposure_time

folder_namestr, optional

Path to folder in which to save output plots.

timedeltaint or float, optional

Unit of time for time-axis of ETD plots, specified as time in seconds (e.g. an input of 60 plots things by minute).

nbinsint, optional

Number of bins to use as the time axis for differential ETD. Using fewer bins smoothes out curves.

save_outputbool, optional

Controls whether or not the output images/data are saved to disk. Default value is True.

verbosebool, optional

Toggles whether or not messages print to the console. If False, nothing is output, if True, messages are output. Default value is True. Errors are always raised.

Outputs :

If save_output is set to True, script saves plots of the cumulative and differential forms of the ETD as a png and the list of exposure times as a json (‘human-readable’) text file.

dorado.routines.plot_state(grid, walk_data, iteration=-1, target_time=None, c='b')

Plot particle positions on an array.

Inputs :

gridnumpy.ndarray

A 2-D grid upon which the particles will be plotted. Examples of grids that might be nice to use are dorado.particle_track.modelParams.depth, dorado.particle_track.modelParams.stage, dorado.particle_track.modelParams.topography.

walk_datadict

The dictionary with the particle information. This is the output from one of the other routines or the dorado.particle_track.Particles.run_iteration() function.

iterationint, optional

Iteration number at which to plot the particles. Default is -1, i.e. the most recent step

target_timefloat, optional

Travel time at which to plot the particles. If specified, iteration is ignored.

cstr, optional

String to specify the color of the particle marks to draw on the figure, default is ‘b’ for blue

Outputs :

axmatplotlib.axes

A matplotlib.axes with the intended plot drawn on it

dorado.routines.show_nourishment_area(visit_freq, grid=None, walk_data=None, cmap='Reds', sigma=0.7, min_alpha=0, show_seed=True, seed_color='dodgerblue')

Plot a smoothed, normalized heatmap of particle visit frequency.

Function will plot the history of particle travel locations in walk_data as a heatmap overtop the specified grid, using the output of dorado.particle_track.nourishment_area(). Colors indicate number of instances in which that cell was occupied by a particle.

Inputs :

visit_freqnumpy.ndarray

A 2-D grid of normalized particle visit frequencies, i.e. the output of the dorado.particle_track.nourishment_area() function

gridnumpy.ndarray, optional

An optional 2-D grid upon which the particles will be plotted. Examples of grids that might be nice to use are dorado.particle_track.modelParams.depth, dorado.particle_track.modelParams.stage, dorado.particle_track.modelParams.topography.

walk_datadict, optional

The dictionary with the particle information, which is used to show the seed location. This is the output from one of the other routines or the dorado.particle_track.Particles.run_iteration() function.

cmapstr, optional

Name of Matplotlib colormap used for the foreground (heatmap). Default is ‘Reds’

sigmafloat, optional

Degree of spatial smoothing of the heatmap used in the dorado.particle_track.nourishment_area() function, only used to adjust the plot asthetics for low sigma’s

min_alphafloat, optional

Minimum alpha value of the heatmap, representing the least frequented cell locations, default is full transparency

show_seedbool, optional

Determines whether resulting plot shows a marker indicating the (first) seed location. Uses indices of walk_data[:][0][0]. Default is True, but only if ‘walk_data’ is also provided.

seed_colorstr, optional

Name of matplotlib color used for the marker seed, if shown. Default is a light blue to contrast with the ‘Reds’ heatmap.

Outputs :

axmatplotlib.axes

A matplotlib.axes upon which the nourishment area is drawn

dorado.routines.show_nourishment_time(mean_times, grid=None, walk_data=None, cmap='magma', show_colorbar=True, min_alpha=0.3, show_seed=True, seed_color='dodgerblue')

Plot a smoothed heatmap of mean particle visit time.

Function will plot the history of mean particle travel times in walk_data as a heatmap overtop the specified grid, using the output of dorado.particle_track.nourishment_time(). Colors indicate the mean length of time particles spent in each cell (potentially after smoothing)

Inputs :

mean_timesnumpy.ndarray

Array of mean occupation times in each cell, i.e. the output of the dorado.particle_track.nourishment_time() function

gridnumpy.ndarray, optional

An optional 2-D grid upon which the particles will be plotted. Recommended to use dorado.particle_track.modelParams.topography

walk_datadict, optional

The dictionary with the particle information, which is used to show the seed location. This is the output from one of the other routines or the dorado.particle_track.Particles.run_iteration() function.

cmapstr, optional

Name of Matplotlib colormap used for the foreground (heatmap). Default is ‘magma’

show_colorbarbool, optional

Controls whether to plot a colorbar for mean_times, default is False

min_alphafloat, optional

Minimum alpha value of the heatmap, representing the cells which spent the least amount of time occupied, default is 0.3

show_seedbool, optional

Determines whether resulting plot shows a marker indicating the (first) seed location. Uses indices of walk_data[:][0][0]. Default is True, but only if ‘walk_data’ is also provided.

seed_colorstr, optional

Name of matplotlib color used for the marker seed, if shown. Default is a light blue.

Outputs :

axmatplotlib.axes

A matplotlib.axes upon which the nourishment times are drawn

dorado.routines.snake_plots(grid, walk_data, num_steps, folder_name=None, interval=4, tail_length=12, rgba_start=[1, 0.4, 0.2, 1], rgba_end=[1, 0.3, 0.1, 0], verbose=True)

Plot particle positions with a trailing tail.

Loops through existing walk_data history and creates a series of plots of the particle locations, with recent locations shown as a trailing tail. Default is for the tails to fade away, but they can also change color. Currently this function can only sync up particles by iteration number, not travel_times.

Inputs :

gridnumpy.ndarray

A 2-D grid upon which the particles will be plotted. Examples of grids that might be nice to use are dorado.particle_track.modelParams.depth, dorado.particle_track.modelParams.stage, dorado.particle_track.modelParams.topography.

walk_datadict

Output of steady_plots, unsteady_plots, time_plots, as well as the particle_track.run_iteration method.

num_stepsint

Number of states in the particle history to plot

folder_namestr, optional

Path to folder in which to save output plots

intervalint, optional

Interval of iterations to skip over between each plot. Also determines how “smooth” each particle trajectory appears. Default is to show every 4th iteration

tail_lengthint, optional

Number of previous locations to show in the “tail” behind each particle. Oldest location will be interval*tail_length iterations before the current iteration. Default is 12

rgba_startlist, optional

List of floats to use as the “recent” color in the particle path, specified as [red, green, blue, alpha] in the range 0-1. Default is a light orange

rgba_endlist, optional

List of floats to use as the “oldest” color in the particle path, specified as [red, green, blue, alpha] in the range 0-1. Default slowly fades to red-ish with an alpha of zero

verbosebool, optional

Toggles whether or not messages print to the console. If False, nothing is output, if True, messages are output. Default value is True. Errors are always raised.

Outputs :

Saves a plot of the particle travel history at each step as a png

dorado.routines.steady_plots(particle, num_iter, folder_name=None, save_output=True, verbose=True)

Automated particle movement in steady flow field.

Function to automate plotting of particle movement over a steady flow fields. Particles all have same number of iterations and are allowed to have different travel times.

Inputs :

particledorado.particle_track.Particles

An initialized particle_track.Particles object with some generated particles.

num_iterint

Number of iterations to move particles over

folder_namestr, optional

Path to folder in which to save output plots.

save_outputbool, optional

Controls whether or not the output images/data are saved to disk. Default value is True.

verbosebool, optional

Toggles whether or not messages print to the console. If False, nothing is output, if True, messages are output. Default value is True. Errors are always raised.

Outputs :

walk_datadict

Dictionary of all x and y locations and travel times

If save_output is set to True, script saves result of each iteration to a folder with the figure for each iteration as a png and the data with the particle locations and travel times as a json (‘human-readable’) text file.

dorado.routines.time_plots(particle, num_iter, folder_name=None, verbose=True)

Steady flow plots with particle travel times visualized.

Make plots with each particle’s travel time visualized. Routine assumes a steady flow field, but could be expanded to an unsteady case.

Inputs :

particledorado.particle_track.Particles

An initialized particle_track.Particles object with some generated particles.

num_iterint

Number of iterations to move particles

folder_namestr, optional

Path to folder in which to save output plots.

verbosebool, optional

Toggles whether or not messages print to the console. If False, nothing is output, if True, messages are output. Default value is True. Errors are always raised.

Outputs :

walk_datadict

Dictionary of all x and y locations and travel times

Saves plots and data for each iteration

dorado.routines.unsteady_plots(dx, Np_tracer, seed_xloc, seed_yloc, num_steps, timestep, output_base, output_type, folder_name=None, verbose=True)

Automated particle movement in unsteady flow.

Function to automate plotting of particle movement in an unsteady flow field (time-varying). Particles all have the same travel time at the end of each timestep and are allowed to have a different number of iterations. Flow field variables (qx, qy, depth) are updated after each timestep. Because this function makes very specific assumptions about your model output files, feel free to use this as a template and change the section that updates the flow field.

Inputs :

dxfloat

Length of a cell face

Np_tracerint

Number of particles to generate.

seed_xloclist

List of x-coordinates over which to initially distribute the particles.

seed_yloclist

List of y-coordinates over which to initially distribute the particles.

num_stepsint

Number of model timesteps being covered

timestepfloat

Model timestep duration (seconds)

output_basestr

Filepath string locating hydrodynamic output files

output_typestr

Filetype string of the output files. Currently accepts ‘csv’, ‘npy’, and ‘npz’. Assumes filenames begin with either ‘depth’, ‘stage’, ‘qx’, ‘qy’, or ‘data’, followed by timestep information (limited built-in support, may require modification)

folder_namestr, optional

Path to folder in which to save output plots.

verbosebool, optional

Toggles whether or not messages print to the console. If False, nothing is output, if True, messages are output. Default value is True. Errors are always raised.

Outputs :

walk_datadict

Dictionary of all x and y locations and travel times

Script saves result of each iteration to a folder with the figure for each iteration as a png and the data with the particle locations and travel times as a json text file.