omfit-data 2020.12.2.22.59
omfit_data
Requires Python: >=3.6

**DATA** files used as part of the OMFIT project: https://omfit.io/

Provides:
=========
* reindex_interp
* reindex_conv
* split_data
* smooth_data
* exportDataset
* importDataset
* OMFITncDataset
* OMFITncDynamicDataset
* DataArray
* Dataset

Requires:
=========
* numpy>=1.12
* scipy>=1.0
* uncertainties>=3
* xarray>=0.10.8
* omfit_commonclasses==2020.12.2.22.59

Authors:
=========
https://omfit.io/contributors.html

Documentation:
==============
reindex_interp
--------------
Conform this object onto a new set of indexes, filling in
    missing values using interpolation. If only one indexer is specified,
    utils.uinterp1d is used. If more than one indexer is specified,
    utils.URegularGridInterpolator is used.

    :params copy : bool, optional
        If `copy=True`, the returned array's dataset contains only copied
        variables. If `copy=False` and no reindexing is required then
        original variables from this array's dataset are returned.

    :params method : {'linear'}, optional
        Method to use for filling index values in ``indexers`` not found on
        this data array:
        * linear: Linear interpolation between points

    :params interpolate_kws : dict, optional
        Key word arguments passed to either uinterp1d (if len(indexers)==1) or
        URegularGridInterpolator.

    :params \**indexers : dict
        Dictionary with keys given by dimension names and values given by
        arrays of coordinates tick labels. Any mis-matched coordinate values
        will be filled in with NaN, and any mis-matched dimension names will
        simply be ignored.

    :return: Another dataset array, with new coordinates and interpolated data.

    See Also:

    DataArray.reindex_like
    align
    

reindex_conv
------------
Conform this object onto a new set of indexes, filling values along changed dimensions
    using nu_conv on each in the order they are kept in the data object.

    :param copy: bool, optional
        If `copy=True`, the returned array's dataset contains only copied
        variables. If `copy=False` and no reindexing is required then
        original variables from this array's dataset are returned.

    :param method: str/function, optional
        Window function used in nu_conv for filling index values in ``indexers``.

    :param window_sizes: dict, optional
        Window size used in nu_conv along each dimension specified in indexers.
        Note, no convolution is performed on dimensions not explicitly given in indexers.

    :param causal: bool, optional
        Passed to nu_conv, where it forces window function f(x>0)=0.

    :param \**indexers: dict
        Dictionary with keys given by dimension names and values given by
        arrays of coordinate's tick labels. Any mis-matched coordinate values
        will be filled in with NaN, and any mis-matched dimension names will
        simply be ignored.

    :param interpolate: False or number
        Parameter indicating to interpolate data so that there are `interpolate`
        number of data points within a time window

    :param std_dev: str/int.
       Accepted strings are 'propagate' or 'none'. Future options will include 'mean', and 'population'.
       Setting to an integer will convolve the error uncertainties to the std_dev power before taking the std_dev root.

    :return: DataArray
        Another dataset array, with new coordinates and interpolated data.

    See Also:

    DataArray.reindex_like
    align
    

split_data
----------

    Split the OMFITdataArray in two wherever the step in a given coordinate
    exceeds the specified limit.

    :param indexers: dict-like with key,value pairs corresponding to dimension labels and step size.

    Example:

    >> dat = OMFITdataArray([0.074,-0.69,0.32,-0.12,0.14],coords=[[1,2,5,6,7],dims=['time'],name='random_data')
    >> dats=dat.split(time=2)])
    >> print(dats)

    

smooth_data
-----------

    One dimensional smoothing. Every projection of the DataArray values
    in the specified dimension is passed to the OMFIT nu_conv smoothing function.

    :param axis: Axis along which 1D smoothing is applied.
    :type axis: int,str (if data is DataArray or Dataset)

    Documentation for the smooth function is below.

    
    Convolution of a non-uniformly discretized array with window function.

    The output values are np.nan where no points are found in finite windows (weight is zero).
    The gaussian window is infinite in extent, and thus returns values for all xo.

    Supports uncertainties arrays.
    If the input --does not-- have associated uncertainties, then the output will --not-- have associated uncertainties.

    :param yi: array_like (...,N,...). Values of input array

    :param xi: array_like (N,). Original grid points of input array (default y indicies)

    :param xo: array_like (M,). Output grid points of convolution array (default xi)

    :param window_size: float.
      Width of passed to window function (default maximum xi step).
      For the Gaussian, sigma=window_size/4. and the convolution is integrated across +/-4.*sigma.

    :param window_function: str/function.
      Accepted strings are 'hanning','bartlett','blackman','gaussian', or 'boxcar'.
      Function should accept x and window_size as arguments and return a corresponding weight.

    :param axis: int. Axis of y along which convolution is performed

    :param causal: int. Forces f(x>0) = 0.

    :param interpolate: False or integer number > 0
     Paramter indicating to interpolate data so that there are`interpolate`
     number of data points within a time window. This is useful in presence of sparse
     data, which would result in stair-case output if not interpolated.
     The integer value sets the # of points per window size.

    :param std_dev: str/int
       Accepted strings are 'none', 'propagate', 'population', 'expand', 'deviation', 'variance'.
       Only 'population' and 'none' are valid if yi is not an uncertainties array (i.e. std_devs(yi) is all zeros).
       Setting to an integer will convolve the error uncertainties to the std_dev power before taking the std_dev root.
       std_dev = 'propagate' is true propagation of errors (slow if not interpolating)
       std_dev = 'population' is the weighted "standard deviation" of the points themselves (strictly correct for the boxcar window)
       std_dev = 'expand' is propagation of errors weighted by w~1/window_function
       std_dev = 'deviation' is equivalent to std_dev=1
       std_dev = 'variance' is equivalent to std_dev=2

    :return: convolved array on xo

    >> M=300
    >> ninterp = 10
    >> window=['hanning','gaussian','boxcar'][1]
    >> width=0.05
    >> f = figure(num='nu_conv example')
    >> f.clf()
    >> ax = f.add_subplot(111)
    >>
    >> xo=np.linspace(0,1,1000)
    >>
    >> x0=xo
    >> y0=(x0>0.25)&(x0<0.75)
    >> pyplot.plot(x0,y0,'b-',label='function')
    >>
    >> x1=np.cumsum(rand(M))
    >> x1=(x1-min(x1))/(max(x1)-min(x1))
    >> y1=(x1>0.25)&(x1<0.75)
    >> pyplot.plot(x1,y1,'b.',ms=10,label='subsampled function')
    >> if window=='hanning':
    >>     ys=smooth(interp1e(x0,y0)(xo),int(len(xo)*width))
    >>     pyplot.plot(xo,ys,'g-',label='smoothed function')
    >>     yc=smooth(interp1e(x1,y1)(xo),int(len(xo)*width))
    >>     pyplot.plot(xo,yc,'m--',lw=2,label='interp subsampled then convolve')
    >>
    >> y1=unumpy.uarray(y1,y1*0.1)
    >> a=time.time()
    >> yo=nu_conv(y1,xi=x1,xo=xo,window_size=width,window_function=window,std_dev='propagate',interpolate=ninterp)
    >> print('nu_conv time: {:}'.format(time.time()-a))
    >> ye=nu_conv(y1,xi=x1,xo=xo,window_size=width,window_function=window,std_dev='expand',interpolate=ninterp)
    >>
    >> uband(x1,y1,color='b',marker='.',ms=10)
    >> uband(xo,yo,color='r',lw=3,label='convolve subsampled')
    >> uband(xo,ye,color='c',lw=3,label='convolve with expanded-error propagation')
    >>
    >> legend(loc=0)
    >> pyplot.ylim([-0.1,1.1])
    >> pyplot.title('%d points , %s window, %3.3f width, interpolate %s'%(M,window,width, ninterp))

    

exportDataset
-------------

    Method for saving xarray Dataset to NetCDF, with support for boolean, uncertain, and complex data
    Also, attributes support OMFITexpressions, lists, tuples, dicts

    :param data: Dataset object to be saved

    :param path: filename to save NetCDF to

    :param complex_dim: str. Name of extra dimension (0,1) assigned to (real, imag) complex data.

    :param \*args: arguments passed to Dataset.to_netcdf function

    :param \**kw: keyword arguments passed to Dataset.to_netcdf function

    :return: output from Dataset.to_netcdf function

    **ORIGINAL Dataset.to_netcdf DOCUMENTATION**

    Write dataset contents to a netCDF file.

        Parameters
        ----------
        path : str, Path or file-like object, optional
            Path to which to save this dataset. File-like objects are only
            supported by the scipy engine. If no path is provided, this
            function returns the resulting netCDF file as bytes; in this case,
            we need to use scipy, which does not support netCDF version 4 (the
            default format becomes NETCDF3_64BIT).
        mode : {'w', 'a'}, optional
            Write ('w') or append ('a') mode. If mode='w', any existing file at
            this location will be overwritten. If mode='a', existing variables
            will be overwritten.
        format : {'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_64BIT',
                  'NETCDF3_CLASSIC'}, optional
            File format for the resulting netCDF file:

            * NETCDF4: Data is stored in an HDF5 file, using netCDF4 API
              features.
            * NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only
              netCDF 3 compatible API features.
            * NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format,
              which fully supports 2+ GB files, but is only compatible with
              clients linked against netCDF version 3.6.0 or later.
            * NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not
              handle 2+ GB files very well.

            All formats are supported by the netCDF4-python library.
            scipy.io.netcdf only supports the last two formats.

            The default format is NETCDF4 if you are saving a file to disk and
            have the netCDF4-python library available. Otherwise, xarray falls
            back to using scipy to write netCDF files and defaults to the
            NETCDF3_64BIT format (scipy does not support netCDF4).
        group : str, optional
            Path to the netCDF4 group in the given file to open (only works for
            format='NETCDF4'). The group(s) will be created if necessary.
        engine : {'netcdf4', 'scipy', 'h5netcdf'}, optional
            Engine to use when writing netCDF files. If not provided, the
            default engine is chosen based on available dependencies, with a
            preference for 'netcdf4' if writing to a file on disk.
        encoding : dict, optional
            Nested dictionary with variable names as keys and dictionaries of
            variable specific encodings as values, e.g.,
            ``{'my_variable': {'dtype': 'int16', 'scale_factor': 0.1,
                               'zlib': True}, ...}``

            The `h5netcdf` engine supports both the NetCDF4-style compression
            encoding parameters ``{'zlib': True, 'complevel': 9}`` and the h5py
            ones ``{'compression': 'gzip', 'compression_opts': 9}``.
            This allows using any compression plugin installed in the HDF5
            library, e.g. LZF.

        unlimited_dims : sequence of str, optional
            Dimension(s) that should be serialized as unlimited dimensions.
            By default, no dimensions are treated as unlimited dimensions.
            Note that unlimited_dims may also be set via
            ``dataset.encoding['unlimited_dims']``.
        compute: boolean
            If true compute immediately, otherwise return a
            ``dask.delayed.Delayed`` object that can be computed later.
        

importDataset
-------------

    Method for loading from xarray Dataset saved as netcdf file, with support for boolean, uncertain, and complex data.
    Also, attributes support OMFITexpressions, lists, tuples, dicts

    :param filename_or_obj: str, file or xarray.backends.*DataStore
        Strings are interpreted as a path to a netCDF file or an OpenDAP URL
        and opened with python-netCDF4, unless the filename ends with .gz, in
        which case the file is gunzipped and opened with scipy.io.netcdf (only
        netCDF3 supported). File-like objects are opened with scipy.io.netcdf
        (only netCDF3 supported).

    :param complex_dim: str, name of length-2 dimension (0,1) containing (real, imag) complex data.

    :param \*args: arguments passed to xarray.open_dataset function

    :param \**kw: keywords arguments passed to xarray.open_dataset function

    :return: xarray Dataset object containing the loaded data

    **ORIGINAL xarray.open_dataset DOCUMENTATION**
    Open and decode a dataset from a file or file-like object.

    Parameters
    ----------
    filename_or_obj : str, Path, file or xarray.backends.*DataStore
        Strings and Path objects are interpreted as a path to a netCDF file
        or an OpenDAP URL and opened with python-netCDF4, unless the filename
        ends with .gz, in which case the file is gunzipped and opened with
        scipy.io.netcdf (only netCDF3 supported). Byte-strings or file-like
        objects are opened by scipy.io.netcdf (netCDF3) or h5py (netCDF4/HDF).
    group : str, optional
        Path to the netCDF4 group in the given file to open (only works for
        netCDF4 files).
    decode_cf : bool, optional
        Whether to decode these variables, assuming they were saved according
        to CF conventions.
    mask_and_scale : bool, optional
        If True, replace array values equal to `_FillValue` with NA and scale
        values according to the formula `original_values * scale_factor +
        add_offset`, where `_FillValue`, `scale_factor` and `add_offset` are
        taken from variable attributes (if they exist).  If the `_FillValue` or
        `missing_value` attribute contains multiple values a warning will be
        issued and all array values matching one of the multiple values will
        be replaced by NA. mask_and_scale defaults to True except for the
        pseudonetcdf backend.
    decode_times : bool, optional
        If True, decode times encoded in the standard NetCDF datetime format
        into datetime objects. Otherwise, leave them encoded as numbers.
    autoclose : bool, optional
        If True, automatically close files to avoid OS Error of too many files
        being open.  However, this option doesn't work with streams, e.g.,
        BytesIO.
    concat_characters : bool, optional
        If True, concatenate along the last dimension of character arrays to
        form string arrays. Dimensions will only be concatenated over (and
        removed) if they have no corresponding variable and if they are only
        used as the last dimension of character arrays.
    decode_coords : bool, optional
        If True, decode the 'coordinates' attribute to identify coordinates in
        the resulting dataset.
    engine : {'netcdf4', 'scipy', 'pydap', 'h5netcdf', 'pynio', 'cfgrib',         'pseudonetcdf'}, optional
        Engine to use when reading files. If not provided, the default engine
        is chosen based on available dependencies, with a preference for
        'netcdf4'.
    chunks : int or dict, optional
        If chunks is provided, it used to load the new dataset into dask
        arrays. ``chunks={}`` loads the dataset with dask using a single
        chunk for all arrays.
    lock : False or duck threading.Lock, optional
        Resource lock to use when reading data from disk. Only relevant when
        using dask or another form of parallelism. By default, appropriate
        locks are chosen to safely read and write files with the currently
        active dask scheduler.
    cache : bool, optional
        If True, cache data loaded from the underlying datastore in memory as
        NumPy arrays when accessed to avoid reading from the underlying data-
        store multiple times. Defaults to True unless you specify the `chunks`
        argument to use dask, in which case it defaults to False. Does not
        change the behavior of coordinates corresponding to dimensions, which
        always load their data from disk into a ``pandas.Index``.
    drop_variables: string or iterable, optional
        A variable or list of variables to exclude from being parsed from the
        dataset. This may be useful to drop variables with problems or
        inconsistent values.
    backend_kwargs: dictionary, optional
        A dictionary of keyword arguments to pass on to the backend. This
        may be useful when backend options would improve performance or
        allow user control of dataset processing.
    use_cftime: bool, optional
        Only relevant if encoded dates come from a standard calendar
        (e.g. 'gregorian', 'proleptic_gregorian', 'standard', or not
        specified).  If None (default), attempt to decode times to
        ``np.datetime64[ns]`` objects; if this is not possible, decode times to
        ``cftime.datetime`` objects. If True, always decode times to
        ``cftime.datetime`` objects, regardless of whether or not they can be
        represented using ``np.datetime64[ns]`` objects.  If False, always
        decode times to ``np.datetime64[ns]`` objects; if this is not possible
        raise an error.

    Returns
    -------
    dataset : Dataset
        The newly created dataset.

    Notes
    -----
    ``open_dataset`` opens the file with read-only access. When you modify
    values of a Dataset, even one linked to files on disk, only the in-memory
    copy you are manipulating in xarray is modified: the original file on disk
    is never touched.

    See Also
    --------
    open_mfdataset
    

OMFITncDataset
--------------

    Class that merges the power of Datasets with OMFIT dynamic loading of objects
    

OMFITncDynamicDataset
---------------------
N/A

DataArray
---------
N-dimensional array with labeled coordinates and dimensions.

    DataArray provides a wrapper around numpy ndarrays that uses labeled
    dimensions and coordinates to support metadata aware operations. The API is
    similar to that for the pandas Series or DataFrame, but DataArray objects
    can have any number of dimensions, and their contents have fixed data
    types.

    Additional features over raw numpy arrays:

    - Apply operations over dimensions by name: ``x.sum('time')``.
    - Select or assign values by integer location (like numpy): ``x[:10]``
      or by label (like pandas): ``x.loc['2014-01-01']`` or
      ``x.sel(time='2014-01-01')``.
    - Mathematical operations (e.g., ``x - y``) vectorize across multiple
      dimensions (known in numpy as "broadcasting") based on dimension names,
      regardless of their original order.
    - Keep track of arbitrary metadata in the form of a Python dictionary:
      ``x.attrs``
    - Convert to a pandas Series: ``x.to_series()``.

    Getting items from or doing mathematical operations with a DataArray
    always returns another DataArray.

    Attributes
    ----------
    dims : tuple
        Dimension names associated with this array.
    values : np.ndarray
        Access or modify DataArray values as a numpy array.
    coords : dict-like
        Dictionary of DataArray objects that label values along each dimension.
    name : str or None
        Name of this array.
    attrs : OrderedDict
        Dictionary for holding arbitrary metadata.
    

Dataset
-------
A multi-dimensional, in memory, array database.

    A dataset resembles an in-memory representation of a NetCDF file, and
    consists of variables, coordinates and attributes which together form a
    self describing dataset.

    Dataset implements the mapping interface with keys given by variable names
    and values given by DataArray objects for each variable name.

    One dimensional variables with name equal to their dimension are index
    coordinates used for label based indexing.