`gnome.outputters`¶

Submodules¶

Package Contents¶

Classes¶

`Outputter`	Base class for all outputters
`NetCDFOutput`	A NetCDFOutput object is used to write the model's data to a NetCDF file.
`Renderer`	Map Renderer
`WeatheringOutput`	class that outputs GNOME weathering results on a time step by time step basis
`BinaryOutput`	class that outputs GNOME trajectory results on a time step by time step basis
`TrajectoryGeoJsonOutput`	class that outputs GNOME results in a geojson format. The output is a
`IceGeoJsonOutput`	Class that outputs GNOME ice velocity results for each ice mover
`IceJsonOutput`	Class that outputs GNOME ice property results for each ice mover
`CurrentJsonOutput`	Class that outputs GNOME current velocity results for each current mover
`SpillJsonOutput`	Class that outputs data on GNOME particles.
`KMZOutput`	class that outputs GNOME results in a kmz format.
`IceImageOutput`	Class that outputs ice data as an image for each ice mover.
`ShapeOutput`	class that outputs GNOME results (particles) in a shapefile format.
`OilBudgetOutput`	Outputter for the oil budget table
`ERMADataPackageOutput`	Outputs the GNOME results as shapefile, and then wraps in an

Attributes¶

`outputters`
`schemas`

class gnome.outputters.Outputter(cache=None, on=True, output_timestep=None, output_zero_step=True, output_last_step=True, output_single_step=False, output_start_time=None, output_dir=None, surface_conc=None, *args, **kwargs)¶

Bases: gnome.gnomeobject.GnomeId

Base class for all outputters Since this outputter doesn’t do anything, it’ll never be used as part of a gnome model. As such, it should never need to be serialized

Sets attributes for outputters, like output_timestep, cache, etc.

Parameters:

cache – sets the cache object from which to read data. The model will automatically set this parameter.
output_timestep=None – If None output will be written every model time step. If set, then output is written every output_timestep starting from the model start time. If the output_timestep is less than the model timestep, an Warning will be raised at runtime.
output_zero_step=True – If True then output for initial step (showing initial release conditions) is written regardless of output_timestep or output_single_step
output_last_step=True – If True then output for final step is written regardless of output_timestep or output_single_step. This is potentially an extra output, if not aligned with output_timestep.
output_single_step=False – If True then output is written for only one step, the output_start_time, regardless of output_timestep. output_zero_step and output_last_step are still respected, set these to False if you want only one time step.
output_start_time=None – Time to start outputting restults. If None it is set to the model start time
output_dir=None – Directory to dump output in, if it needs to do this.
surface_conc=None – Compute surface concentration Any non-empty string will compute (and output) the surface concentration. The contents of the string determine the algorithm used. “kde” is currently the only available option.

property output_timestep¶

property middle_of_run¶

_schema¶

_surf_conc_computed = False¶

prepare_for_model_run(model_start_time=None, spills=None, model_time_step=None, map=None, **kwargs)¶

This method gets called by the model at the beginning of a new run. Do what you need to do to prepare.

Parameters:

model_start_time (datetime.datetime object) – (Required) start time of the model run. NetCDF time units calculated with respect to this time.
spills (gnome.spill_container.SpillContainerPair object) – (Required) model.spills object (SpillContainerPair)
model_time_step (float seconds) – time step of the model – used to set timespans for some outputters

Optional argument - in case cache needs to be updated

Parameters:: cache=None – Sets the cache object to be used for the data. If None, it will use the one already set up.

also added **kwargs since a derived class like NetCDFOutput could require additional variables.

Note

base class doesn’t use model_start_time or spills, but multiple outputters need spills and netcdf needs model_start_time, so just set them here

prepare_for_model_step(time_step, model_time)¶

This method gets called by the model at the beginning of each time step Do what you need to do to prepare for a new model step

base class method checks to see if data for model_time should be output Set self._write_step flag to true if:

model_time < self._dt_since_lastoutput <= model_time + time_step

It also updates the _dt_since_lastoutput internal variable if the data from this step will be written to output

Parameters:

time_step – time step in seconds
model_time – current model time as datetime object

Note

The write_output() method will be called after the Model calls model_step_is_done(). Let’s set the _write_step flag here and update the _dt_since_lastoutput variable

model_step_is_done()¶: This method gets called by the model when after everything else is done in a time step. Put any code need for clean-up, etc. The write_output method is called by Model after all processing.

post_model_run()¶: Override this method if a derived class needs to perform any actions after a model run is complete (StopIteration triggered)

write_output(step_num, islast_step=False)¶

called by the model at the end of each time step This is the last operation after model_step_is_done()

Parameters:

step_num (int) – the model step number you want rendered.
islast_step (bool) – default is False. Flag that indicates that step_num is last step. If ‘output_last_step’ is True then this is written out

clean_output_files()¶

Cleans out the output dir

This should be implemented by subclasses that dump files.

Each outputter type dumps different types of files, and this should only clear out those.

See the OutputterFilenameMixin for a simple example.

rewind()¶

Called by model.rewind()

Reset variables set during prepare_for_model_run() to init conditions Make sure all child classes call parent rewind() first!

write_output_post_run(*, model_start_time, model_time_step, num_time_steps, **kwargs)¶

If the model has already been run and the data is cached, then use this function to write output. In this case, num_time_steps is known so pass it into this function.

Parameters:

model_start_time (datetime.datetime object) – (Required) start time of the model run. NetCDF time units calculated with respect to this time.
num_time_steps (int) – (Required) total number of time steps for the run. Currently this is known and fixed.

Optional argument - depending on the outputter, the following may be required. For instance, the ‘spills’ are required by NetCDFOutput, GeoJson, but not Renderer in prepare_for_model_run(). The **kwargs here are those required by prepare_for_model_run() for an outputter

Parameters:

cache=None – Sets the cache object to be used for the data. If None, it will use the one already set up.
uncertain (bool) – is there uncertain data to write. Used by NetCDFOutput to setup attributes for uncertain data file
spills (This is the Model's spills attribute which refers to the SpillContainerPair object) – SpillContainerPair object containing spill information Used by both the NetCDFOutput and by GeoJson to obtain spill_id from spill_num

Follows the iteration in Model().step() for each step_num

_check_filename(filename)¶: basic checks to make sure the filename is valid

_check_is_dir(filename)¶: split this out - causes problems for shape and most outputters dont need it

_file_exists_error(file_)¶

invoked by prepare_for_model_run. If file already exists, it will raise this error.

Do this in prepare_for_model_run, because user may want to define the model and run it in batch mode. This will allow netcdf_outputter to be created, but the first time it tries to write this file, it will check and raise an error if file exists

class gnome.outputters.NetCDFOutput(filename, zip_output=False, which_data='standard', compress=True, surface_conc='kde', _start_idx=0, **kwargs)¶

Bases: gnome.outputters.outputter.Outputter, gnome.outputters.outputter.OutputterFilenameMixin

A NetCDFOutput object is used to write the model’s data to a NetCDF file. It inherits from Outputter class and implements the same interface.

This class is meant to be used within the Model, to be added to list of outputters.

>>> model = gnome.model.Model(...)
>>> model.outputters += gnome.netcdf_outputter.NetCDFOutput(
            os.path.join(base_dir,'sample_model.nc'), which_data='most')

which_data flag is used to set which data to add to the netcdf file:

‘standard’ : the basic stuff most people would want

‘most’: everything the model is tracking except the internal-use-only: arrays
‘all’: everything tracked by the model (mostly used for diagnostics of: save files)

Note

cf_attributes is a class attribute: a dict that contains the global attributes per CF convention

The attribute: .arrays_to_output is a set of the data arrays that will be added to the netcdf file. array names may be added to or removed from this set before a model run to customize what gets output: the_netcdf_outputter.arrays_to_output.add[‘rise_vel’]

Since some of the names of the netcdf variables are different from the names in the SpillContainer data_arrays, this list uses the netcdf names

Constructor for Net_CDFOutput object. It reads data from cache and writes it to a NetCDF4 format file using the CF convention

Parameters:

filename (str. or unicode) – Required parameter. The filename in which to store the NetCDF data.
zip_output=True – whether to zip up the output netcdf files
which_data='standard' – If ‘standard’, write only standard data. If ‘most’ means, write everything except the attributes we know are for internal model use. If ‘all’, write all data to NetCDF – usually only for diagnostics. Default is ‘standard’. These are defined in the standard_arrays and usually_skipped_arrays attributes

NOTE: if you want a custom set of output arrays, you can cahnge the .self.arrays_to_output set after initialization.

Optional arguments passed on to base class (kwargs):

Parameters:

cache – sets the cache object from which to read data. The model will automatically set this param
output_timestep (timedelta object) – default is None in which case every time the write_output is called, output is written. If set, then output is written every output_timestep starting from model_start_time.
output_zero_step (boolean) – default is True. If True then output for initial step (showing initial release conditions) is written regardless of output_timestep
output_last_step (boolean) – default is True. If True then output for final step is written regardless of output_timestep

use super to pass optional kwargs to base class __init__ method

property uncertain_filename¶: if uncertain SpillContainer is present, write its data out to this file

property which_data¶

property chunksize¶

property compress¶

property netcdf_format¶

which_data_lu¶

compress_lu¶

cf_attributes¶

standard_arrays = ['latitude', 'longitude', 'depth', 'status_codes', 'spill_num', 'id', 'mass', 'age', 'density',...¶

special_arrays¶

usually_skipped_arrays = ['next_positions', 'last_water_positions', 'windages', 'mass_components', 'half_lives',...¶

_schema¶

_update_var_attributes(spills)¶: update instance specific self._var_attributes

_initialize_rootgrp(rootgrp, sc)¶: create dimensions for root group and set cf_attributes

_update_arrays_to_output(sc)¶: create list of variables that we want to put in the file

prepare_for_model_run(model_start_time, spills, uncertain=False, **kwargs)¶

prepare_for_model_run(model_start_time,
spills,
**kwargs)

Write global attributes and define dimensions and variables for NetCDF file. This must be done in prepare_for_model_run because if model _state changes, it is rewound and re-run from the beginning.

If there are existing output files, they are deleted here.

This takes more than standard ‘cache’ argument. Some of these are required arguments - they contain None for defaults because non-default argument cannot follow default argument. Since cache is already 2nd positional argument for Renderer object, the required non-default arguments must be defined following ‘cache’.

If uncertainty is on, then SpillContainerPair object contains identical _data_arrays in both certain and uncertain SpillContainers, the data itself is different, but they contain the same type of data arrays. If uncertain, then datay arrays for uncertain spill container are written to filename + ‘_uncertain.nc’

Parameters:: spills (gnome.spill_container.SpillContainerPair object.) – If ‘which_data’ flag is set to ‘all’ or ‘most’, then model must provide the model.spills object (SpillContainerPair object) so NetCDF variables can be defined for the remaining data arrays. If spills is None, but which_data flag is ‘all’ or ‘most’, a ValueError will be raised. It does not make sense to write ‘all’ or ‘most’ but not provide ‘model.spills’.

Note

Does not take any other input arguments; however, to keep the interface the same for all outputters, define **kwargs in case future outputters require different arguments.

use super to pass model_start_time, cache=None and remaining kwargs to base class method

_create_nc_var(grp, var_name, dtype, shape, chunksz)¶

write_output(step_num, islast_step=False)¶

Write NetCDF output at the end of the step

Parameters:

step_num (int) – the model step number you want rendered.
islast_step (bool) – Default is False. Flag that indicates that step_num is last step. If ‘output_last_step’ is True then this is written out

Use super to call base class write_output method

post_model_run()¶: This is where to clean up – close files, etc.

_zip_output_files()¶

clean_output_files()¶

deletes output files that may be around

called by prepare_for_model_run

here in case it needs to be called from elsewhere

rewind()¶: reset a few parameter and call base class rewind to reset internal variables.

classmethod read_data(netcdf_file, time=None, index=None, which_data='standard')¶

Read and create standard data arrays for a netcdf file that was created with NetCDFOutput class. Make it a class method since it is independent of an instance of the Outputter. The method is put with this class because the NetCDF functionality for PyGnome data with CF standard is captured here.

Parameters:

netcdf_file – Name of the NetCDF file from which to read the data
time – timestamp at which the data is desired. Looks in the netcdf data’s ‘time’ array and finds the closest time to this and outputs this data. If both ‘time’ and ‘index’ are None, return data if file only contains one ‘time’ else raise an error
index (int) – Index of the ‘time’ variable (or time_step). This is only used if ‘time’ is None. If both ‘time’ and ‘index’ are None,return data if file only contains one ‘time’ else raise an error
which_data='standard' – Which data arrays are desired. Options are: (‘standard’, ‘most’, ‘all’, [list_of_array_names])

Returns:

A dict containing standard data closest to the indicated ‘time’.

Standard data is defined as follows:

Standard data arrays are numpy arrays of size N, where N is number of particles released at time step of interest. They are defined by the class attribute “standard_arrays”, currently:

'current_time_stamp': datetime object associated with this data
'positions'         : NX3 array. NetCDF variables:
                      'longitude', 'latitude', 'depth'
'status_codes'      : NX1 array. NetCDF variable :'status_codes'
'spill_num'         : NX1 array. NetCDF variable: 'spill_num'
'id'                : NX1 array of particle id. NetCDF variable
                      'id'
'mass'              : NX1 array showing 'mass' of each particle

standard_arrays = ['latitude',
                   'longitude', # pulled from the 'positions' array
                   'depth',
                   'status_codes',
                   'spill_num',
                   'id',
                   'mass',
                   'age',
                   ]

to_dict(json_=None)¶

Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is.

The json_ parameter is ignored in this base class. ‘save’ is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving.

class gnome.outputters.Renderer(map_filename=None, output_dir='./', image_size=(800, 600), projection=None, viewport=None, map_BB=None, land_polygons=None, draw_back_to_fore=True, draw_map_bounds=False, draw_spillable_area=False, formats=['png', 'gif'], draw_ontop='forecast', cache=None, output_timestep=None, output_zero_step=True, output_last_step=True, output_single_step=False, output_start_time=None, on=True, timestamp_attrib={}, point_size=2, depth_colors=None, min_color_depth=0, max_color_depth=100, **kwargs)¶

Bases: gnome.outputters.Outputter, gnome.utilities.map_canvas.MapCanvas

Map Renderer

class that writes map images for GNOME results.

Writes the frames for the LE “movies”, etc.

Init the image renderer.

Parameters:

map_filename=None – GnomeMap or name of file for basemap (BNA)
output_dir='./' (str) – directory to output the images
600) (2-tuple image_size=(800,) – size of images to output
projection=None – projection instance to use: If None, set to projections.FlatEarthProjection()
viewport (pair of (lon, lat) tuples ( lower_left, upper right )) – viewport of map – what gets drawn and on what scale. Default is full globe: (((-180, -90), (180, 90))) If not specifies, it will be set to the map’s bounds.
map_BB=None – bounding box of map if None, it will use the bounding box of the mapfile.
draw_back_to_fore=True – draw the background (map) to the foregound image when outputting the images each time step.
formats=['gif'] – list of formats to output.
draw_ontop (str) – draw ‘forecast’ or ‘uncertain’ LEs on top. Default is to draw ‘forecast’ LEs, which are in black on top

Following args are passed to base class Outputter’s init:

Parameters:

cache – sets the cache object from which to read prop. The model will automatically set this param
output_timestep (timedelta object) – default is None in which case everytime the write_output is called, output is written. If set, then output is written every output_timestep starting from model_start_time.
output_zero_step (boolean) – default is True. If True then output for initial step (showing initial release conditions) is written regardless of output_timestep
output_last_step (boolean) – default is True. If True then output for final step is written regardless of output_timestep
point_size=2 – size to draw elements, in pixels
depth_colors=None –
colorscheme to use to color elements according to their depth for 3D modeling. Any scheme that py_gd provides can be used:: py_gd.colorschemes.keys() Currently: ‘cividis’, ‘inferno’, ‘magma’, ‘plasma’, ‘turbo’, ‘twilight’, ‘viridis’ (borrowed from matplotlib)

If None, elements will not be colored by depth
min_color_depth=0 – depth to map the first color in the scheme (m)
max_color_depth=100 – depth to map the last color in the scheme (m)

Remaining kwargs are passed onto Outputter.__init__(…)

property delay¶

property repeat¶

property map_filename¶

property draw_ontop¶

property formats¶

map_colors = [('background', (255, 255, 255)), ('lake', (255, 255, 255)), ('land', (255, 204, 153)), ('LE',...¶

background_map_name = 'background_map.'¶

foreground_filename_format = 'foreground_{0:05d}.'¶

foreground_filename_glob = 'foreground_?????.*'¶

_schema¶

output_dir_to_dict()¶

start_animation(filename)¶

prepare_for_model_run(*args, **kwargs)¶

prepares the renderer for a model run.

Parameters passed to base class (use super): model_start_time, cache

Does not take any other input arguments; however, to keep the interface the same for all outputters, define **kwargs and pass into the base class

In this case, it draws the background image and clears the previous images. If you want to save the previous images, a new output dir should be set.

set_timestamp_attrib(**kwargs)¶

Function to set details of the timestamp’s appearance when printed. These details are stored as a dict.

Recognized attributes:

Parameters:

on (Boolean) – Turn the draw function on or off
dt_format (String) – Format string for strftime to format the timestamp
background (str) – Color of the text background. Color must be present in foreground palette
color (str) – Color of the font. Note that the color must be present in the foreground palette
size (str) – Size of the font, one of {‘tiny’, ‘small’, ‘medium’, ‘large’, ‘giant’}
position (tuple) – x, y pixel coordinates of where to draw the timestamp.
align (str) – The reference point of the text bounding box. One of: {‘lt’(left top), ‘ct’, ‘rt’, ‘l’, ‘r’, ‘lb’, ‘cb’, ‘rb’}

draw_timestamp(time)¶

Function that draws the timestamp to the foreground. Uses self.timestamp_attribs to determine it’s appearance.

Parameters:: time (datetime) – the datetime object representing the timestamp

clean_output_files()¶

Cleans out the output dir

This should be implemented by subclasses that dump files.

Each outputter type dumps different types of files, and this should only clear out those.

See the OutputterFilenameMixin for a simple example.

draw_background()¶

Draws the background image – land and optional graticule

This should be called whenever the scale changes

add_grid(grid, on=True, color='grid_1', width=2)¶

draw_grids()¶

add_vec_prop(prop, on=True, color='LE', mask_color='uncert_LE', size=3, width=1, scale=1000)¶

draw_props(time)¶

draw_masked_nodes(grid, time)¶

draw_land()¶: Draws the land map to the internal background image.

draw_elements(sc)¶

Draws the individual elements to a foreground image

Parameters:: sc – a SpillContainer object to draw

draw_raster_map()¶

draws the raster map used for beaching to the image.

draws a grid for the pixels

this is pretty slow, but only used for diagnostics. (not bad for just the lines)

write_output(step_num, islast_step=False)¶

Render the map image, according to current parameters.

Parameters:

step_num (int) – the model step number you want rendered.
islast_step (bool) – default is False. Flag that indicates that step_num is last step. If ‘output_last_step’ is True then this is written out

Returns:

A dict of info about this step number if this step is to be output, None otherwise. ‘step_num’: step_num ‘image_filename’: filename ‘time_stamp’: time_stamp # as ISO string

use super to call base class write_output method

If this is last step, then prop is written; otherwise prepare_for_model_step determines whether to write the output for this step based on output_timestep

post_model_run()¶: Override this method if a derived class needs to perform any actions after a model run is complete (StopIteration triggered)

_draw(step_num)¶: create a small function so prop arrays are garbage collected from memory after this function exits - it returns current_time_stamp

projection_to_dict()¶: store projection class as a string for now since that is all that is required for persisting todo: This may not be the case for all projection classes, but keep simple for now so we don’t have to make the projection classes serializable

to_dict(json_=None)¶

Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is.

The json_ parameter is ignored in this base class. ‘save’ is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving.

class gnome.outputters.WeatheringOutput(output_dir=None, **kwargs)¶

Bases: BaseMassBalanceOutputter

class that outputs GNOME weathering results on a time step by time step basis

The output is the aggregation of properties for all LEs (aka Mass Balance) for a particular time step. There are a number of different things we would like to graph: - Evaporation - Dissolution - Dissipation - Biodegradation - ???

Parameters:: output_dir=None (str) – output directory for the json files. If not directory is provided, files will not be written.

other arguments as defined in the Outputter class

_schema¶

write_output(step_num, islast_step=False)¶: Weathering data is only output for forecast spill container, not the uncertain spill container. This is because Weathering has its own uncertainty and mixing the two was giving weird results. The cloned models that are modeling weathering uncertainty do not include the uncertain spill container.

output_to_file(json_content, step_num)¶

clean_output_files()¶

Cleans out the output dir

This should be implemented by subclasses that dump files.

Each outputter type dumps different types of files, and this should only clear out those.

See the OutputterFilenameMixin for a simple example.

__getstate__()¶

This is to support pickle.dumps() inside the uncertainty model subprocesses. We need to be able to pickle our weathering outputters so that our uncertainty subprocesses can send them back to the parent process through a message queue. And the cache attribute (specifically, the ElementCache.lock attribute) can not be pickled, and instead produces a RuntimeError.

(Note: The __setstate__() probably doesn’t need to recreate the: ElementCache since it will be created inside the Model.setup_model_run() function.)

class gnome.outputters.BinaryOutput(filename, zip_output=True, **kwargs)¶

Bases: gnome.outputters.outputter.OutputterFilenameMixin, gnome.outputters.outputter.Outputter

class that outputs GNOME trajectory results on a time step by time step basis this is the format output by desktop GNOME for use in Gnome Analyst

Parameters:

filename (str) – full path and basename of the zip file
zip_output=True – whether to zip up the output binary files

other arguments as defined in the Outputter class

_schema¶

prepare_for_model_run(model_start_time, spills, uncertain=False, **kwargs)¶

prepare_for_model_run(model_start_time,
cache=None,
uncertain=False,
spills=None,
**kwargs)

Reset file_num and uncertainty

This must be done in prepare_for_model_run because if model _state changes, it is rewound and re-run from the beginning.

If there are existing output files, they are deleted here.

This takes more than standard ‘cache’ argument. Some of these are required arguments - they contain None for defaults because non-default argument cannot follow default argument. Since cache is already 2nd positional argument for Renderer object, the required non-default arguments must be defined following ‘cache’.

If uncertainty is on, then SpillContainerPair object contains identical _data_arrays in both certain and uncertain SpillContainer’s, the data itself is different, but they contain the same type of data arrays. If uncertain, then data arrays for uncertain spill container are written to separate files.

Note

Does not take any other input arguments; however, to keep the interface the same for all outputters, define kwargs in case future outputters require different arguments.

write_output(step_num, islast_step=False)¶: Write data from time step to binary file

output_to_file(filename, sc)¶: dump a timestep’s data into binary files for Gnome Analyst

_zip_binary_files(num_files)¶

clean_output_files()¶

deletes output files that may be around

called by prepare_for_model_run

here in case it needs to be called from elsewhere

__getstate__()¶

This is to support pickle.dumps() inside the uncertainty model subprocesses. We need to be able to pickle our weathering outputters so that our uncertainty subprocesses can send them back to the parent process through a message queue. And the cache attribute (specifically, the ElementCache.lock attribute) can not be pickled, and instead produces a RuntimeError.

(Note: The __setstate__() probably doesn’t need to recreate the: ElementCache since it will be created inside the Model.setup_model_run() function.)

class gnome.outputters.TrajectoryGeoJsonOutput(round_data=True, round_to=4, output_dir=None, **kwargs)¶

Bases: gnome.outputters.outputter.Outputter

class that outputs GNOME results in a geojson format. The output is a collection of Features. Each Feature contains a Point object with associated properties. Following is the format for a particle - the data in <> are the results for each element.

{
"type": "FeatureCollection",
"features": [
    {
        "geometry": {
            "type": "Point",
            "coordinates": [
                <LONGITUDE>,
                <LATITUDE>
            ]
        },
        "type": "Feature",
        "id": <PARTICLE_ID>,
        "properties": {
            "current_time": <TIME IN SEC SINCE EPOCH>,
            "status_code": <>,
            "spill_id": <UUID OF SPILL OBJECT THAT RELEASED PARTICLE>,
            "depth": <DEPTH>,
            "spill_type": <FORECAST OR UNCERTAIN>,
            "step_num": <OUTPUT ASSOCIATED WITH THIS STEP NUMBER>
        }
    },
    ...
}

Parameters:

round_data=True (bool) – if True, then round the numpy arrays containing float to number of digits specified by ‘round_to’. Default is True
round_to=4 (int) – round float arrays to these number of digits. Default is 4.
output_dir=None (str) – output directory for geojson files. Default is None since data is returned in dict for webapi. For using write_output_post_run(), this must be set

use super to pass optional **kwargs to base class __init__ method

_schema¶

write_output(step_num, islast_step=False)¶: dump data in geojson format

output_to_file(json_content, step_num)¶

_dataarray_p_types(data_array)¶: return array as list with appropriate python dtype This is partly to make sure the dtype of the list elements is a python data type else geojson fails

clean_output_files()¶

Cleans out the output dir

This should be implemented by subclasses that dump files.

Each outputter type dumps different types of files, and this should only clear out those.

See the OutputterFilenameMixin for a simple example.

class gnome.outputters.IceGeoJsonOutput(ice_movers, **kwargs)¶

Bases: gnome.outputters.outputter.Outputter

Class that outputs GNOME ice velocity results for each ice mover in a geojson format. The output is a collection of Features. Each Feature contains a Point object with associated properties. Following is the output format - the data in <> are the results for each element:

{
 "time_stamp": <TIME IN ISO FORMAT>,
 "step_num": <OUTPUT ASSOCIATED WITH THIS STEP NUMBER>,
 "feature_collections": {<mover_id>: {"type": "FeatureCollection",
                                      "features": [{"type": "Feature",
                                                    "id": <PARTICLE_ID>,
                                                    "properties": {"ice_fraction": <FRACTION>,
                                                                   "ice_thickness": <METERS>,
                                                                   "water_velocity": [u, v],
                                                                   "ice_velocity": [u, v]
                                                                   },
                                                    "geometry": {"type": "Point",
                                                                 "coordinates": [<LONG>, <LAT>]
                                                                 },
                                                    },
                                                    ...
                                                   ],
                                      },
                         ...
                         }
}

Parameters:: ice_movers (An ice_mover object or sequence of ice_mover objects.) – ice_movers associated with this outputter.

Use super to pass optional **kwargs to base class __init__ method

_schema¶

clean_output_files()¶

Cleans out the output dir

This should be implemented by subclasses that dump files.

Each outputter type dumps different types of files, and this should only clear out those.

See the OutputterFilenameMixin for a simple example.

write_output(step_num, islast_step=False)¶: dump data in geojson format

get_coverage_fc(coverage, triangles)¶

get_thickness_fc(thickness, triangles)¶

get_grouped_fc_from_1d_array(values, triangles, property_name, decimals)¶

get_rounded_ice_values(coverage, thickness)¶

get_unique_ice_values(ice_values)¶: In order to make numpy perform this function fast, we will use a contiguous structured array using a view of a void type that joins the whole row into a single item.

get_matching_ice_values(ice_values, v)¶

rewind()¶: remove previously written files

class gnome.outputters.IceJsonOutput(ice_movers, **kwargs)¶

Bases: gnome.outputters.outputter.Outputter

Class that outputs GNOME ice property results for each ice mover in a raw JSON format. The output contains a dict keyed by mover id. Each value item in the dict contains a list of feature data. Each feature item contains the ice fraction and thickness, and polyonal coordinate data. Following is the output format.

{
 "time_stamp": <TIME IN ISO FORMAT>,
 "step_num": <OUTPUT ASSOCIATED WITH THIS STEP NUMBER>,
 "feature_collections": {<mover_id>: [[<ICE_CONCENTRATION>,
                                       <ICE_THICKNESS>,
                                       [[<LONG>, <LAT>], ...],
                                       ],
                                      ...
                                      ],
                         ...
                         }
}

Parameters:: ice_movers (An ice_mover object or sequence of ice_mover objects.) – ice_movers associated with this outputter.

Use super to pass optional kwargs to base class __init__ method

_schema¶

clean_output_files()¶

this outputter doesn’t write any files

but this method needs to be here

write_output(step_num, islast_step=False)¶: dump data in geojson format

rewind()¶: remove previously written files

class gnome.outputters.CurrentJsonOutput(current_movers, **kwargs)¶

Bases: gnome.outputters.outputter.Outputter

Class that outputs GNOME current velocity results for each current mover in a geojson format. The output is a collection of Features. Each Feature contains a Point object with associated properties. Following is the output format - the data in <> are the results for each element.

{
 "time_stamp": <TIME IN ISO FORMAT>,
 "step_num": <OUTPUT ASSOCIATED WITH THIS STEP NUMBER>,
 "feature_collections": {<mover_id>: {"type": "FeatureCollection",
                                      "features": [{"type": "Feature",
                                                    "id": <PARTICLE_ID>,
                                                    "properties": {"velocity": [u, v]
                                                                   },
                                                    "geometry": {"type": "Point",
                                                                 "coordinates": [<LONG>, <LAT>]
                                                                 },
                                                },
                                                ...
                                               ],
                                  },
                     ...
                     }
}

Parameters:: current_movers (list) – A list or collection of current grid mover objects.

use super to pass optional kwargs to base class __init__ method

_schema¶

write_output(step_num, islast_step=False)¶: dump data in geojson format

get_rounded_velocities(velocities)¶

get_unique_velocities(velocities)¶: In order to make numpy perform this function fast, we will use a contiguous structured array using a view of a void type that joins the whole row into a single item.

get_matching_velocities(velocities, v)¶

current_movers_to_dict()¶: a dict containing ‘obj_type’ and ‘id’ for each object in list/collection

class gnome.outputters.SpillJsonOutput(_additional_data=None, **kwargs)¶

Bases: gnome.outputters.outputter.Outputter

Class that outputs data on GNOME particles. Following is the format for a particle - the data in <> are the results for each element.

{
    "certain": {
        "length":<LENGTH>
        "longitude": []
        "latitude": []
        "status_code": []
        "mass": []
        "spill_num":[]
    }
    "uncertain":{
        "length":<LENGTH>
        "longitude": []
        "latitude": []
        "status_code": []
        "mass": []
        "spill_num":[]
    }
    "step_num": <STEP_NUM>
    "timestamp": <TIMESTAMP>
}

Parameters:: current_movers (list) – A list or collection of current grid mover objects.

use super to pass optional kwargs to base class __init__ method

_schema¶

write_output(step_num, islast_step=False)¶: dump data in geojson format

class gnome.outputters.KMZOutput(filename, **kwargs)¶

Bases: gnome.outputters.outputter.OutputterFilenameMixin, gnome.outputters.outputter.Outputter

class that outputs GNOME results in a kmz format.

Suitable for Google Earth, and semi-suitable for MarPlot

Parameters:: output_dir=None (str) – output directory for kmz files.

uses super to pass optional **kwargs to base class __init__ method

_schema¶

time_formatter = '%m/%d/%Y %H:%M'¶

prepare_for_model_run(model_start_time, spills, **kwargs)¶

prepare_for_model_run(model_start_time,
cache=None,
uncertain=False,
spills=None,
**kwargs)

Write the headers, png files, etc for the KMZ file

This must be done in prepare_for_model_run because if model _state changes, it is rewound and re-run from the beginning.

If there are existing output files, they are deleted here.

This takes more than standard ‘cache’ argument. Some of these are required arguments - they contain None for defaults because non-default argument cannot follow default argument. Since cache is already 2nd positional argument for Renderer object, the required non-default arguments must be defined following ‘cache’.

If uncertainty is on, then SpillContainerPair object contains identical _data_arrays in both certain and uncertain SpillContainer’s, the data itself is different, but they contain the same type of data arrays. If uncertain, then data arrays for uncertain spill container are written to the KMZ file.

Note

Does not take any other input arguments; however, to keep the interface the same for all outputters, define kwargs in case future outputters require different arguments.

write_output(step_num, islast_step=False)¶: dump a timestep’s data into the kmz file

rewind()¶: reset a few parameter and call base class rewind to reset internal variables.

class gnome.outputters.IceImageOutput(ice_movers=None, image_size=(800, 600), projection=None, viewport=None, **kwargs)¶

Bases: gnome.outputters.Outputter

Class that outputs ice data as an image for each ice mover.

The image is PNG encoded, then Base64 encoded to include in a JSON response.

Parameters:: ice_movers (An ice_mover object or sequence of ice_mover objects.) – ice_movers associated with this outputter.

Use super to pass optional kwargs to base class __init__ method

_schema¶

set_gradient_colors(gradient_name, color_range=((0, 0, 127), (0, 255, 255)), scale=(0.0, 10.0), num_colors=16)¶

Add a color gradient to our palette representing the colors we will use for our ice thickness

Parameters:

gradient_name (str) – The name of the gradient.
color_range (A 2 element sequence of 3-tuples containing 8-bit RGB values.) – The colors we will build our gradient with.
scale (A 2 element sequence of float) – A range of values representing the low and high end of our gradient.
num_colors (Number) – The number of colors to use for the gradient.

add_gradient_to_canvas(color_range, color_prefix, num_colors)¶

Add a color gradient to our palette

NOTE: Probably not the most efficient way to do this.

Parameters:

color_range (A sequence of 2 or more 3-tuples) – The colors that we would like to use to generate our gradient
color_prefix (str) – The prefix that will be used in the naming of the colors in the gradient
num_colors (Number) – The number of gradient colors to generate

lookup_gradient_color(gradient_name, values)¶

write_output(step_num, islast_step=False)¶: Generate image from data

get_sample_image()¶

This returns a base 64 encoded PNG image for testing, just so we have something

This should be removed when we have real functionality

render_images(model_time)¶

render the actual images This uses the MapCanvas code to do the actual rendering

returns: thickness_image, concentration_image

ice_movers_to_dict()¶: a dict containing ‘obj_type’ and ‘id’ for each object in list/collection

class gnome.outputters.ShapeOutput(filename, zip_output=True, include_certain_boundary=False, certain_boundary_separate_by_spill=True, certain_boundary_hull_ratio=0.5, certain_boundary_hull_allow_holes=False, include_uncertain_boundary=True, uncertain_boundary_separate_by_spill=True, uncertain_boundary_hull_ratio=0.5, uncertain_boundary_hull_allow_holes=False, surface_conc='kde', **kwargs)¶

Bases: gnome.outputters.outputter.Outputter

class that outputs GNOME results (particles) in a shapefile format.

Parameters:

filename – Full path and basename of the shape file.
zip_output=True – Whether to zip up the output shape files.
surface_conc="kde" – Method to use to compute surface concentration current options are: ‘kde’ and None

_schema¶

time_formatter = '%m/%d/%Y %H:%M'¶

__del__()¶

prepare_for_model_run(model_start_time, spills, uncertain=False, **kwargs)¶: If uncertainty is on, then SpillContainerPair object contains identical _data_arrays in both certain and uncertain SpillContainer’s, the data itself is different, but they contain the same type of data arrays. If uncertain, then data arrays for uncertain spill container are written.

write_output(step_num, islast_step=False)¶: Dump a timestep’s data into the shapefile

post_model_run()¶: The final step to wrap everything up

create_bundle(uncertain)¶: Create a shapefile bundle including both certain and uncertain shapefiles

rewind()¶: reset a few parameter and call base class rewind to reset internal variables.

clean_output_files()¶: deletes ouput files that may be around called by prepare_for_model_run here in case it needs to be called from elsewhere

class gnome.outputters.OilBudgetOutput(filename='gnome_oil_budget.csv', file_format='csv', cache=None, on=True, output_timestep=None, *args, **kwargs)¶

Bases: gnome.outputters.weathering.BaseMassBalanceOutputter, gnome.outputters.outputter.OutputterFilenameMixin

Outputter for the oil budget table

Sets attributes for outputters, like output_timestep, cache, etc.

Parameters:

cache – sets the cache object from which to read data. The model will automatically set this parameter.
output_timestep=None – If None output will be written every model time step. If set, then output is written every output_timestep starting from the model start time. If the output_timestep is less than the model timestep, an Warning will be raised at runtime.
output_zero_step=True – If True then output for initial step (showing initial release conditions) is written regardless of output_timestep or output_single_step
output_last_step=True – If True then output for final step is written regardless of output_timestep or output_single_step. This is potentially an extra output, if not aligned with output_timestep.
output_single_step=False – If True then output is written for only one step, the output_start_time, regardless of output_timestep. output_zero_step and output_last_step are still respected, set these to False if you want only one time step.
output_start_time=None – Time to start outputting restults. If None it is set to the model start time
output_dir=None – Directory to dump output in, if it needs to do this.
surface_conc=None – Compute surface concentration Any non-empty string will compute (and output) the surface concentration. The contents of the string determine the algorithm used. “kde” is currently the only available option.

_valid_file_formats¶

budget_categories = ['amount_released', 'evaporated', 'natural_dispersion', 'sedimentation', 'beached', 'floating',...¶

header_row = ['Model Time', 'Hours Since Model Start', 'Amount Released (kg)', 'Evaporated (kg)', 'Dispersed...¶

_schema¶

prepare_for_model_run(model_start_time, spills, **kwargs)¶: start the csv file

write_output(step_num, islast_step=False)¶: Oil budget is only output for forecast spill container, not the uncertain spill container. This is because Weathering has its own uncertainty and mixing the two was giving weird results. The cloned models that are modeling weathering uncertainty do not include the uncertain spill container.

post_model_run()¶

Called after a model run is complete

remove the csv file - hopefully resulting in the file being closed.

class gnome.outputters.ERMADataPackageOutput(filename, folder_name=None, certain_layer_name=None, include_certain_particles=True, uncertain_layer_name=None, include_uncertain_particles=True, certain_boundary_layer_name=None, include_certain_boundary=False, certain_boundary_separate_by_spill=True, certain_boundary_hull_ratio=0.5, certain_boundary_hull_allow_holes=False, certain_boundary_color=None, certain_boundary_size=None, certain_contours_layer_name=None, include_certain_contours=False, certain_contours_hull_ratio=0.5, certain_contours_hull_allow_holes=False, certain_contours_size=None, uncertain_boundary_layer_name=None, include_uncertain_boundary=True, uncertain_boundary_separate_by_spill=True, uncertain_boundary_hull_ratio=0.5, uncertain_boundary_hull_allow_holes=False, uncertain_boundary_color=None, uncertain_boundary_size=None, map_bounds_layer_name=None, include_map_bounds=False, map_bounds_color=None, map_bounds_size=None, spillable_area_layer_name=None, include_spillable_area=False, spillable_area_color=None, spillable_area_size=None, land_polys_layer_name=None, include_land_polys=False, land_polys_color=None, land_polys_size=None, include_spill_location=True, disable_legend_collapse=False, time_step_override=None, time_unit_override=None, surface_conc='kde', **kwargs)¶

Bases: gnome.outputters.outputter.Outputter

Outputs the GNOME results as shapefile, and then wraps in an ERMA data package.

Parameters:

filename – Full path and filename (with ext) of the desired outout file
surface_conc="kde" – method to use to compute surface concentration current options are: ‘kde’ and None

_schema¶

time_formatter = '%m/%d/%Y %H:%M'¶

__del__()¶

prepare_for_model_run(model_start_time, spills, uncertain=False, **kwargs)¶: Setup before we run the model.

write_output(step_num, islast_step=False)¶: Dump a timestep’s data into the shapefile

post_model_run()¶: The final step to wrap everything up

build_package()¶

make_contour_polygon_package_layer(id, shapefile_filename, layer_title, style_name, style_width)¶

make_boundary_polygon_package_layer(id, uncertain, shapefile_filename, layer_title, style_name, color, style_width)¶

make_map_polygon_package_layer(id, map_polygon_name, shapefile_name, layer_title, style_name, color, style_width)¶

make_spill_location_package_layer(id)¶

spills_match_style(spill1, spill2)¶

group_like_spills()¶

generate_cutoff_struct()¶

make_particle_package_layer(id, layer_name, uncertain, shapefile_filename)¶

rewind()¶: reset a few parameter and call base class rewind to reset internal variables.

clean_output_files()¶: deletes ouput files that may be around called by prepare_for_model_run here in case it needs to be called from elsewhere

gnome.outputters.outputters¶

gnome.outputters.schemas¶

gnome.outputters¶

Submodules¶

Package Contents¶

Classes¶

Attributes¶

`gnome.outputters`¶