gnome.outputters.netcdf¶

NetCDF outputter - write the nc_particles netcdf file format

Attributes¶

var_attributes

Classes¶

NetCDFOutput

A NetCDFOutput object is used to write the model's data to a NetCDF file.

Module Contents¶

gnome.outputters.netcdf.var_attributes¶

class gnome.outputters.netcdf.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

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',...¶

forecast_filename¶

zip_filename¶

name¶: define as property in base class so all objects will have a name by default

zip_output = False¶

arrays_to_output¶

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¶

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

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.

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.