effluent.io =========== .. py:module:: effluent.io .. autoapi-nested-parse:: The package contains functions and classes for reading and writing simulation data. Classes ------- .. autoapisummary:: effluent.io.Ambient effluent.io.AmbientRoms effluent.io.AmbientXarray effluent.io.Output effluent.io.OutputCSV effluent.io.OutputNC effluent.io.Pipe Functions --------- .. autoapisummary:: effluent.io.append_xr_to_nc effluent.io.convert_to_nc_date effluent.io.read_csv effluent.io.write_nc_to_xr effluent.io.write_xr_to_nc Module Contents --------------- .. py:class:: Ambient Data about the ambient ocean. This is an abstract base class with no explicit constructor. To initialize an instance of the class, use the factory method. .. py:method:: close() Close the underlying data source .. py:method:: from_config(conf) :staticmethod: Initialize using :doc:`configuration parameters ` :param conf: A dict of configuration parameters :return: An initialized object .. py:method:: select(time) :abstractmethod: Compute the ambient conditions at a specific time. :param time: A numpy.datetime64 object :return: An xarray.Dataset object with variables ``u``, ``v`` and ``dens``, all indexed by the coordinate ``depth``. .. py:class:: AmbientRoms(file, latitude, longitude, azimuth) Bases: :py:obj:`Ambient` Data about the ambient ocean, from ROMS. This subclass is using ROMS output files as its data source. The constructor also needs the pipe position and azimuth, as described in the :doc:`documentation ` of the configuration file. The class lazily opens the underlying data source the first time it's needed. :param file: A set of ROMS files, specified with a wildcard string :param latitude: The pipe latitude :param longitude: The pipe longitude :param azimuth: The pipe azimuth (north = 0, east = 90) .. py:method:: close() Close the underlying data source .. py:method:: select(time) Compute the ambient conditions at a specific time. :param time: A numpy.datetime64 object :return: An xarray.Dataset object with variables ``u``, ``v`` and ``dens``, all indexed by the coordinate ``depth``. .. py:class:: AmbientXarray(dset) Bases: :py:obj:`Ambient` Data about the ambient ocean, from in-memory dataset. This subclass is using an xarray.Dataset object as its data source. The dataset should have variables ``u``, ``v`` and ``dens``, all indexed by the coordinates ``depth`` and ``time``. :param dset: An xarray.Dataset object .. py:method:: select(time) Compute the ambient conditions at a specific time. :param time: A numpy.datetime64 object :return: An xarray.Dataset object with variables ``u``, ``v`` and ``dens``, all indexed by the coordinate ``depth``. .. py:class:: Output Class for writing simulation output to disk This is an abstract base class with no explicit constructor. To initialize an instance of the class, use the factory method. .. py:method:: close() Close the underlying data stream .. py:method:: from_config(conf) :staticmethod: Initialize using :doc:`configuration parameters ` :param conf: A dict of configuration parameters :return: An initialized object .. py:method:: write(time, result) :abstractmethod: Write simulation results to disk :param time: Discharge time, as numpy.datetime64 object :param result: Simulation result, as returned by :func:`effluent.solver.Solver.solve` .. py:class:: OutputCSV(file, variables=None, float_format='%.10g', separator=',') Bases: :py:obj:`Output` Class for writing simulation output to CSV file. The output file is created lazily upon the first write statement. :param file: Name of output file :param variables: A list of variable names to include :param float_format: Output format for float numbers :param separator: Symbol used as data separator .. py:method:: close() Close the underlying data stream .. py:method:: from_config(conf) :staticmethod: Initialize using :doc:`configuration parameters ` :param conf: A dict of configuration parameters :return: An initialized object .. py:method:: write(time, result) Write simulation results to disk :param time: Discharge time, as numpy.datetime64 object :param result: Simulation result, as returned by :func:`effluent.solver.Solver.solve` .. py:class:: OutputNC(file, variables) Bases: :py:obj:`Output` Class for writing simulation output to netCDF file. The output file is created lazily upon the first write statement. :param file: Name of output file :param variables: A list of variable names to include .. py:method:: close() Close the underlying data stream .. py:method:: from_config(conf) :staticmethod: Initialize using :doc:`configuration parameters ` :param conf: A dict of configuration parameters :return: An initialized object .. py:method:: write(time, result) Write simulation results to disk :param time: Discharge time, as numpy.datetime64 object :param result: Simulation result, as returned by :func:`effluent.solver.Solver.solve` .. py:class:: Pipe(dset) Data about the pipe and the effluent release. The constructor takes an xarray.Dataset object as input. If the source data is in the form of a data file, the factory method should be used instead. :param dset: An xarray.Dataset object with variables ``depth``, ``u``, ``w``, ``dens`` and ``diam``, all indexed by the coordinate ``time``. .. py:method:: from_config(conf) :staticmethod: Initialize using :doc:`configuration parameters ` :param conf: A dict of configuration parameters :return: An initialized object .. py:method:: select(time) Interpolate pipe parameters to a specific point in time :param time: A time in numpy.datetime64 format :return: An xarray.Dataset object with variables ``depth``, ``u``, ``w``, ``dens`` and ``diam``. .. py:function:: append_xr_to_nc(xr_dset, nc_dset) Append data from an xarray.Dataset to a netCDF4.Dataset This method does not create new variables in the destination dataset, but only appends to the existing variables. :param xr_dset: Input dataset :param nc_dset: Output dataset .. py:function:: convert_to_nc_date(xr_var, units = 'seconds since 1970-01-01', calendar = 'proleptic_gregorian', dtype='i8') Convert an xarray date variable to a CF-style date variable On default, the xarray date will be converted to seconds (int64) since the unix epoch (1970-01-01) using the proleptic gregorian calendar. :param xr_var: Input variable, with values of type numpy.datetime64 :param units: Output units, as defined by CF conventions :param calendar: Output calendar, as defined by CF conventions :param dtype: Output data type, as defined by numpy conventions :return: Output variable, with values converted to seconds since epoch .. py:function:: read_csv(file) Read csv file, and return a pandas.DataFrame :param file: File name :return: A pandas.DataFrame object .. py:function:: write_nc_to_xr(nc_dset, xr_dset) Write data from a netCDF4.Dataset to a an xarray.Dataset :param nc_dset: Input dataset :param xr_dset: Output dataset .. py:function:: write_xr_to_nc(xr_dset, nc_dset) Write data from an xarray.Dataset to a netCDF4.Dataset :param xr_dset: Input dataset :param nc_dset: Output dataset