gnome.outputters.netcdf ======================= .. py:module:: gnome.outputters.netcdf .. autoapi-nested-parse:: NetCDF outputter - write the nc_particles netcdf file format Attributes ---------- .. autoapisummary:: gnome.outputters.netcdf.var_attributes Classes ------- .. autoapisummary:: gnome.outputters.netcdf.NetCDFOutput Module Contents --------------- .. py:data:: var_attributes .. py:class:: NetCDFOutput(filename, zip_output=False, which_data='standard', compress=True, surface_conc='kde', _start_idx=0, **kwargs) Bases: :py:obj:`gnome.outputters.outputter.Outputter`, :py:obj:`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 :param filename: Required parameter. The filename in which to store the NetCDF data. :type filename: str. or unicode :param zip_output=True: whether to zip up the output netcdf files :param 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 :type which_data: string -- one of {'standard', 'most', 'all'} 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): :param cache: sets the cache object from which to read data. The model will automatically set this param :param output_timestep: 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. :type output_timestep: timedelta object :param output_zero_step: default is True. If True then output for initial step (showing initial release conditions) is written regardless of output_timestep :type output_zero_step: boolean :param output_last_step: default is True. If True then output for final step is written regardless of output_timestep :type output_last_step: boolean use super to pass optional kwargs to base class __init__ method .. py:attribute:: which_data_lu .. py:attribute:: compress_lu .. py:attribute:: cf_attributes .. py:attribute:: standard_arrays :value: ['latitude', 'longitude', 'depth', 'status_codes', 'spill_num', 'id', 'mass', 'age', 'density',... .. py:attribute:: special_arrays .. py:attribute:: usually_skipped_arrays :value: ['next_positions', 'last_water_positions', 'windages', 'mass_components', 'half_lives',... .. py:attribute:: forecast_filename .. py:attribute:: zip_filename .. py:attribute:: name define as property in base class so all objects will have a name by default .. py:attribute:: zip_output :value: False .. py:attribute:: arrays_to_output .. py:property:: uncertain_filename if uncertain SpillContainer is present, write its data out to this file .. py:property:: which_data .. py:property:: chunksize .. py:property:: compress .. py:property:: netcdf_format .. py:method:: prepare_for_model_run(model_start_time, spills, uncertain=False, **kwargs) .. function:: 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' :param spills: 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'. :type spills: gnome.spill_container.SpillContainerPair object. .. 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 .. py:method:: write_output(step_num, islast_step=False) Write NetCDF output at the end of the step :param int step_num: the model step number you want rendered. :param bool islast_step: 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 .. py:method:: post_model_run() This is where to clean up -- close files, etc. .. py:method:: 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 .. py:method:: rewind() reset a few parameter and call base class rewind to reset internal variables. .. py:method:: read_data(netcdf_file, time=None, index=None, which_data='standard') :classmethod: 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. :param netcdf_file: Name of the NetCDF file from which to read the data :param 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 :param int index: 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 :param which_data='standard': Which data arrays are desired. Options are: ('standard', 'most', 'all', [list_of_array_names]) :type which_data: string or sequence of strings. :return: 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', ] .. py:method:: 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.