    Extracts GPM_IMERG data from its HDF5 format.

    :param hdf_list:        list of hdf files or directory with hdfs
    :param layer_indexs:    list of integer layer indexs
    :param outdir:          directory to place outputs
    :param resolution:      The size of a pixel in degrees, either
                            "0.1" or "0.15" depending on GPM product.
    :return:                a list of all files created as output

    Typical contents of a GPM HDF are:

    == =========== ================================ ==============
    ID layer shape Layer name                       data type
    == =========== ================================ ==============
    0  [3600x1800] HQobservationTime                (16-bit int)
    1  [3600x1800] HQprecipSource                   (16-bit int)
    2  [3600x1800] HQprecipitation                  (32-bit float)
    3  [3600x1800] IRkalmanFilterWeight             (16-bit int)
    4  [3600x1800] IRprecipitation                  (32-bit float)
    5  [3600x1800] precipitationCal                 (32-bit float)
    6  [3600x1800] precipitationUncal               (32-bit float)
    7  [3600x1800] probabilityLiquidPrecipitation   (16-bit int)
    8  [3600x1800] randomError                      (32-bit float)
    == =========== ================================ ==============


computes the approx distance between two utmx, utmy locations


        computes the distance between two lat/lon coordinates in meters
        using the Haversine formula.


        performs grid interpolation for a smaller subset of the total dataset.
        utmx_matrix and utmy_matrix are the two components of a meshgrid


        Grids a dataset to the desired resolution in a UTM projection. input
        resolution is the length of one square pixel on a side in meters.


    This function takes a gdal dataset object as returned from the
    "_extract_HDF_layer_data" OR "_extractNetCDF_layer_data functions
    and writes it to tif with either the embedded projection and
    geotransform or custom ones. This function should be wrapped in another
    function for a specific datatype.

    :param gdal_dataset:        A gdal.Dataset object
    :param outpath:             Output filepath for this dataset (tif)
    :param cust_projection:     A projection string, see datatype_library
    :param cust_geotransform:   A geotransform array, see datatype_library
    :param force_custom:        If True, forces the custom geotransform and
                                projections to be used even if valid
                                geotransforms and projections can be read
                                from the gdal.dataset. If False, custom
                                projections and geotransforms will be ignored
                                if valid variables can be pulled from the
                                gdal.dataset metadata.
    :param nodata_value:        The value to set to Nodata

    :return outpath:            The local system filepath to output dataset


    Extracts one or more layers from an HDF file and returns a dictionary with
    all the data available in the HDF layer for use in further format conversion
    to better supported formats.

    For example -
    hdfpath = filepath to an hdf file. (any HDF 4 or 5 datatype)
    layer indexs = [1,2,3]

    the output dict will have keys :
                    ["MasterMetadata", "1", "2", "3"]

    where the "MasterMetadata" values very widely in format depending on
    data source, but might contain georeferencing information and the like.
    Each of the values for those integer keys will simply be a gdal.dataset
    object.

    This function is the first step in the chain for turning HDF data into
    geotiff. the next step is to build an established datatype

    :param hdfpath          filepath to any HDF formated file
    :param layer_indexs     list of integer index values for layers to extract
    :return out_info:       dict of metadata and gdal.dataset objects


    Extracts one or more layers from an NetCDF file and returns a dictionary with
    all the data available in the NetCDF layer for use in further format conversion
    to better supported formats.

    example:
    ncpath = filepath to an NetCDF file. (any HDF 4 or 5 datatype)
    layer indexs = [1,2,3]

    the output dict will have keys :
                    ["MasterMetadata", "1", "2", "3"]

    where the "MasterMetadata" values very widely in format depending on
    data source, but might contain georeferencing information and the like.
    Each of the values for those integer keys will simply be a gdal.dataset
    object.

    this function is the first step in the chain for turning HDF data into
    geotiff. the next step is to build an established datatype

    :param ncpath          filepath to any NetCDF formated file
    :param layer_indexs     list of integer index values for layers to extract


    Extracts SMOS data from its native NetCDF format.

    :param netcdf_list:     list of hdf files or directory with netcdfs
    :param layer_indexs:    list of integer layer indices
    :param outdir:          directory to place outputs
    :param resolution:      Presently ONLY supports input of "25k"

    :return:                a list of all files created as output


    Fills gaps in raster data by spatial kriging interpolation. This should only
    be used to fill small gaps in continuous datasets (like a DEM), and in
    instances where it makes sense. This function creates a feature class
    layer of points where pixels are not NoData, then performs a "kriging"
    interpolation on the point data to rebuild a uniform grid with a value
    at every location, thus filling gaps.

    WARNING: This script is processing intensive and may take a while to run
    even for modestly sized datasets.

    :param in_rasterpath:   input filepath to raster to fill gaps
    :param out_rasterpath:  filepath to store output gap filled raster in
    :param model:           type of kriging model to run, options include
                            "SPHERICAL", "CIRCULAR", "EXPONENTIAL",
                            "GAUSSIAN", and "LINEAR"
    :param max_cell_dist:   The maximum number of cells to interpolate between,
                            data gaps which do not have at least "min_points"
                            points within this distance will not be filled.
    :param min_points:      Minimum number of surrounding points to use in determining
                            value at missing cell.

    :return out_rasterpath: Returns path to file created by this function


    Ensures perfect coincidence between a snap_raster and any input rasters

    This script is primarily intended for calling by the "raster.spatially_match" function
    but may be called independently.

    it is designed to input a reference image and a working image. The working image must
    be in exactly the same projection and spatial resolution as the reference image. This
    script will simply ensure the tif files are perfectly coincident, and that the total image
    extents are identical. This is important when performing numpy manipulations on matrices
    derived from different datasets manipulated in different ways to ensure alignment.

    This script makes modifications to the original raster file, so save a backup if you are
    unsure how to use this.

    :param snap_raster:     filepath and name of reference raster whos extent will be taken on by
                            the input rastername.
    :param rastname:        name of raster which should be snapped to the snap_raster
    :param NoData_Value:    Value desired to represent NoData in the saved image.

    :return snap_meta:      metadata of the snap_raster file as output by to_numpy
    :return meta:           metadata of the rastername file as output by to_numpy


    Applies a linear correction to a raster dataset.
    New offset rasters are saved in the output directory with a suffix of "lc"
    unless one is specified. This may be used to apply any kind of linear relationship
    that can be described with "mx + b" such as conversion between between K,C, and F.
    Also useful when ground truthing satellite data and discovering linear errors.
    All outputs are 32 bit floating point values.

    :param rasterlist:  list of rasters, a single raster, or a directory full of tiffs to
                        Have a linear correction applied to them.
    :param factor:      every pixel in the raster will be MULTIPLIED by this value.
    :param offset:      this offset value will be ADDED to every pixel in the raster.
    :param suffix:      output files will take the same name as input files with this string
                        appended to the end. So input "FILE.tif" outputs "FILE_suffix.tif"
    :param outdir:      directory to save output rasters. "None" will save output images
                        in the same folder as the input images.
    :param floor:       Used to manage NoData. All values less than floor are set to floor
                        then floor is set to the new NoData value. defaults to -999,999

    return outputpath:  filepath to output files created by this function

    Example Usage
    to convert from MODIS Land surface temperature from digital number to kelvin, you
    must simply multiply by 0.02 as the stated scale factor listed at the link below
    [https://lpdaac.usgs.gov/products/modis_products_table/myd11a1].

    Now that it is in kelvin, converting to Celsius can be done by adding (-273.15)
    So, use this function with::

        factor = 0.02
        offset = -273.15

    and one may convert MODIS land surface temperature digital numbers directly to
    celsius!


    Lists all the rasters in an input directory. finds all formats
    supported by ``raster.enf_rastlist()``.

    :param dir_name:    directory to search rasters for
    :param recursive:   Set to "True" to search within subfolders of input
                        directory "dir_name"


    Simply creates a new raster dataset mosaic of input rasters by wrapping the
    arcpy.MosaicToNewRaster_management function. learn more about the fields here

    http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//001700000098000000

    :param rasterpaths:     list of complete filepaths to raster data to mosaic
    :param output_path:     place to save new mosaic raster dataset
    :param mosaic_method:   options are "FIRST", "LAST", "BLEND", "MEAN", "MINIMUM","MAXIMUM"
    :param cell_size:       of format "[cellwidth] [cellheight]" in the appropriate linear units,
                            usually meters.

    :return output_path:    returns filepath to new file, same as input ``output_path``


    Wrapper for multiple arcpy projecting functions. Projects to reference file. Inputs a
    filelist and a reference file, then projects all rasters or feature classes
    in the filelist to match the projection of the reference file. Writes new files with a
    in the filelist to match the projection of the reference file. Writes new files with a
    "_p" appended to the end of the input filenames. This also will perform resampling.

    :param filelist:            list of files to be projected
    :param outdir:              optional desired output directory. If none is specified, output files
                                will be named with '_p' as a suffix.
    :param reference_file:      Either a file with the desired projection, or a .prj file.
    :param resampling_type:     exactly as the input for arcmaps project_Raster_management function
    :param cell_size:           exactly as the input for arcmaps project_Raster_management function

    :return output_filelist:    list of files created by this function.


    Prepares input rasters for further numerical processing.
    This function simply ensures all rasters in "rasterlist" are identically projected
    and have the same cell size, then calls the raster.clip_and_snap function to ensure
    that the cells are perfectly coincident and that the total spatial extents of the images
    are identical, even when NoData values are considered. This is useful because it allows
    the two images to be passed on for numerical processing as nothing more than matrices
    of values, and the user can be sure that any index in any matrix is exactly coincident
    with the same index in any other matrix. This is especially important to use when
    comparing different datasets from different sources outside arcmap, for example MODIS
    and Landsat data with an ASTER DEM.

    :param snap_raster:     raster to which all other images will be snapped
    :param rasterlist:      list of rasters, a single raster, or a directory full of tiffs which
                            will be clipped to the extent of "snap_raster" and aligned such that
                            the cells are perfectly coincident.
    :param outdir:          the output directory to save newly created spatially matched tifs.
    :param resamp_type:     The resampling type to use if images are not identical cell sizes.
                            "NEAREST","BILINEAR",and "CUBIC" are the most common.

    this function automatically invokes
        * clip_and_snap
        * project_resample


function to set up an initial figure


        Function to update a figure that already exists.

        :param numpy_rast:  a numpy array representing a raster dataset
        :param title:       title to put on the raster figure object


closes an active figure


    Simple batch clipping script to clip rasters to shapefiles.

    :param rasterlist:      single file, list of files, or directory for which to clip rasters
    :param shapefile:       shapefile to which rasters will be clipped
    :param outdir:          desired output directory. If no output directory is specified, the
                            new files will simply have '_c' added as a suffix.

    :return output_filelist:    list of files created by this function.


    Take statistics across many input rasters. This function is used to take
    statistics on large groups of rasters with identical spatial extents.

    :param rasterlist:      list of raster filepaths for which to take statistics
    :param outdir:          directory where output should be stored.
    :param outname:         output name filename string that will be used in output filenames
    :param saves:           which statistics to save in a raster. Defaults to all
                            three ['AVG','NUM','STD'].
    :param low_thresh:      values below low_thresh are assumed erroneous and set to NoData
    :param high_thresh:     values above high_thresh are assumed erroneous and set to NoData.
    :param numtype:         type of numerical value. defaults to 32bit float.

    This function does not return anything.


    Wrapper for arcpy.NumPyArrayToRaster function with better metadata handling

    this is just a wrapper for the NumPyArrayToRaster function within arcpy. It is used in
    conjunction with to_numpy to streamline reading image files in and out of numpy
    arrays. It also ensures that all spatial referencing and projection info is preserved
    between input and outputs of numpy manipulations.

    :param numpy_rast:      The numpy array version of the input raster
    :param metadata:        The variable exactly as output from "to_numpy"
    :param outpath:         Output filepath of the individual raster
    :param NoData_Value:    The no data value of the output raster

    :return outpath:        Same as input outpath, filepath to created file.

    Usage example
    call to_numpy with  "rast,metadata = to_numpy(Raster)"
    perform numpy manipulations as you please
    then save the array with "raster.from_numpy(rast, metadata, output)"


    Changes values within a certain range to NoData. similar to ``raster.null_define``,
    but can take an entire range of values to set to NoData. useful in filtering
    obviously erroneous high or low values from a raster dataset.

    :param rastlist:     list of rasters for which to set no dta values
    :param high_thresh:  will set all values above this to  NoData
    :param low_thresh:   will set all values below this to NoData

    :return rastlist:    list of all rasters modified by this function


    Wrapper for arcpy.RasterToNumpyArray with better metadata handling

    This is just a wraper for the RasterToNumPyArray function within arcpy, but it also
    extracts out all the spatial referencing information that will probably be needed
    to save the raster after desired manipulations have been performed.
    also see raster.from_numpy function in this module.

    :param raster:         Any raster supported by the arcpy.RasterToNumPyArray function
    :param numpy_datatype: must be a string equal to any of the types listed at the following
                           address [http://docs.scipy.org/doc/numpy/user/basics.types.html]
                           for example: 'uint8' or 'int32' or 'float32'

    :return numpy_rast:   the numpy array version of the input raster
    :return Metadata:     a metadata object. see ``raster.metadata``


sets all required metadata attributes from an existing raster image


        gets a "pixel_type" attribute that matches format of arcpy function
        inputs for manual datatype manipulations from the confusingly encoded
        "pixelType" variable associated with arcpy.Describe()

        as of arcpy 10.2.2


        further translates the arcpy pixel_type format preferences into something
        that matches the format for numpy "datatype" arguments

        note that numpy does not do 4 and 2 bit integers


    Accumulates degree days in a time series rasterlist

    This function is the logical successor to calc.degree_days. Input a list of rasters
    containing daily data to be accumulated. Output raster for a given day will be the sum
    total of the input raster for that day and all preceding days. The last output raster in
    a years worth of data (image 356) would be the sum of all 365 images. The 25th output
    raster would be a sum of the first 25 days.
    Critical value rasters will also be created. Usefull for example: we wish to know on what day
    of our 365 day sequence every pixel hits a value of 100. Input 100 as a critical value
    and that output raster will be generated.

    :param rasterlist:          list of files, or directory containing rasters to accumulate
    :param critical_values:     Values at which the user wishes to know WHEN the total accumulation
                                value reaches this point. For every critical value, an output
                                raster will be created. This raster contains integer values denoting
                                the index number of the file at which the value was reached.
                                This input must be a list of ints or floats, not strings.
    :param outdir:              Desired output directory for all output files.

    :return output_filelist:    a list of all files created by this function.


    This function is designed to input a time sequence of rasters with partial voids and
    output a copy of each input image with every pixel equal to the last good value taken.
    This function will step forward in time through each raster and fill voids from the values
    of previous rasters. The resulting output image will contain all the data that was in the
    original image, with the voids filled with older data. A second output image will be
    generated where the pixel values are equal to the age of each pixel in the image. So
    if a void was filled with data that's 5 days old, the "age" raster will have a value of
    "5" at that location.

    :param rasterlist:      A list of filepaths for rasters with which to fill gaps. THESE IMAGES
                            MUST BE ORDERED FROM OLDEST TO NEWEST (ascending time).
    :param outdir:          the path to the desired output folder, if left "None", outputs will be
                            saved right next to respective inputs.
    :param continuous:      if "True" an output raster will be generated for every single input raster,
                            which can be used to fill gaps in an entire time series. So, for example
                            output raster 2 will have all the good points in input raster 2, with gaps
                            filled with data from raster 1. output raster 3 will then be gap filled with
                            output raster 2, which might contain some fill values from raster 1, and so
                            forth. If "False" an output raster will only be generated for the LAST raster
                            in the input rasterlist.
    :param numpy_datatype:  the numpy datatype of the output raster. usually "float32"

    :return output_filelist: returns a list of filepaths to new files created by this function.


    Ensures a list of inputs filepaths contains only valid raster types

    :param filelist:        a list of filepaths that contains some raster filetypes
    :return new_filelist:   a list of filepaths with all non-raster files removed


    Inputs rasters for maximum and minimum temperatures, calculates Growing Degree Days

    this function is built to perform the common degree day calculation on either a pair
    of raster filepaths, a pair of numpy arrays It requires, at minimum a maximum
    temperature value, a minimum temperature value, and a base temperature. This
    equation could also be used to calculate Chill hours or anything similar.

    The equation is ``[(Max+Min)/2 + T_base]``

    where values in Max which are greater than roof are set equal to roof
    where values in Min which are less than floor are set equal to floor
    consult [https://en.wikipedia.org/wiki/Growing_degree-day] for more information.

    :param T_base:          base temperature to ADD, be mindful of sign convention.
    :param Max:             filepath, numpy array, or list of maximum temperatures
    :param Min:             filepath, numpy array, or list of minimum temperatures
    :param NoData_Value:    values to ignore (must be int or float)
    :param outpath:         filepath to which output should be saved. Only works if Max and Min inputs
                            are raster filepaths with spatial referencing.
    :param roof:            roof value above which Max temps do not mater
    :param floor:           floor value below which Min temps do not mater

    :return deg_days:       a numpy array of the output degree_days


    Finds overlaping area between two raster images. this function examines
    two images and outputs a raster identifying pixels where both rasters have
    non-NoData values. Output raster has 1's where both images have data and
    0's where one or both images are missing data.

    :param file_A:      the first file
    :param file_B:      the second file
    :param outpath:     the output filename for the desired output. must end in ".tif"
    :param NoData_A:    the NoData value of file A
    :param NoData_B:    the NoData value of file B

    :return outpath:    filepath to raster created by this function.

    This function automatically invokes
        * clip_and_snap
        * null_define


    Simple batch NoData setting function. Makes raster data more arcmap viewing friendly

    Function inputs a list of raster (usually tifs) files and sets no data values. This
    function does not actually change the raster values in any way, and simply defines which
    numerical values to be considered NoData in metadata.

    :param rastlist:        list of rasters for which to set nodata value
    :param NoData_Value:    Value to declare as NoData (usually 0 or -9999)

    :return rastlist:       returns list of modified files


    Verifies that input filename exists, and is of a valid raster format

    :param filename:  check if this filename is a valid accessible raster.
    :return <bool>: returns True if filename is valid accessible raster. False otherwise.


    This script can be used to add python libraries to the arcmap
    installation of python from wheel files. A great source of wheel files
    can be found at [http://www.lfd.uci.edu/~gohlke/pythonlibs/]

    :param whl_filepath:    the full local filepath to a downloaded wheel file.


    Simple file listing function with more versatility than python builtins or arcpy.List

    This function sifts through a directory and returns a list of filepaths for all files
    meeting the input criteria. Useful for discriminatory iteration or recursive searches.
    Could be used to find all tiles with a given datestring such as 'MOD11A1.A2012', or
    perhaps all Band 4 tiles from a directory containing landsat 8 data.

    :param recursive:       'True' if search should search subfolders within the directory
                            'False' if search should ignore files in subfolders.
    :param directory:       The directory in which to search for files meeting the criteria
    :param contains:        search criteria to limit returned file list. File names must
                            contain parameters listed here. If no criteria exists use 'False'
    :param not_contains:    search criteria to limit returned file list. File names must not
                            contain parameters listed here. If no criteria exists use 'False'

    :return filelist:        An array of full filepaths meeting the criteria.


    Ensures input location is either a file or a folder

    :param location:    a filepath to a directory or file
    :return bool:       returns true if filepath leads to a real place


    This function formats and runs commands that one would call from the console.
    Primarily intended for calling gdal commands from other functions in cases
    where the python bindings are absent. Particularly useful for commands with
    list type arguments. This function provides simplicity, but users wanting more
    functionality should use the subprocess module directly.

    :param command:  command can be virtually any number of string arguments in
                     any configuration of args, lists, and tuples. This function
                     will take all input strings in the order in which they are
                     given and place a space ``" "`` between each argument before
                     passing it to the command line.

    .. code-block:: python

        # all of these are valid syntax
        core.run_command(arg1)
        core.run_command(arg1, arg2)
        core.run_command([arg1, arg2])
        core.run_command(arg1, [arg2, arg3])
        core.run_command(arg1, [arg2, arg3, [arg4, arg5]], (arg7, arg8))


    flattens a list with nested lists, tuples, and other irregular structures
    :param l:   list to flatten
    :return:    generator object that can be converted to list with list().


    When a list is expected, this function can be used to ensure
    non-list data types are placed inside of a single entry list.

    :param item:    any datatype
    :return list:   a list type


    renames a file

    :param filename:        input file to rename
    :param replace_this:    string to be replaced. such as " " (a space)
    :param with_this:       what to replace the string with. such as "_" (an underscore)

    :return newfilename:    the new name of the file.


    Quick way to create unique output file names within iterative functions

    This function is built to simplify the creation of output file names. Function allows
    ``outdir = False`` and will create an outname in the same directory as inname. Function will
    add a the user input suffix, separated by an underscore "_" to generate an output name.
    this is useful when performing a small modification to a file and saving new output with
    a new suffix. Function merely returns an output name, it does not save the file as that name.

    :param outdir:      either the directory of the desired outname or False to create an outname
                        in the same directory as the inname
    :param inname:      the input file from which to generate the output name "outname"
    :param suffix:      suffix to attach to the end of the filename to mark it as output
    :param ext:         specify the file extension of the output filename. Leave blank or False
                        and the outname will inherit the same extension as inname.

    :return outname:    the full filepath at which a new file can be created.


    Sanitizes file list inputs

    This function checks that the input is a list of files and not a directory. If the input
    is a directory, then it returns a list of files in the directory which match the desired
    extension. This is to allow all functions which input filelists to be a little more
    flexible by accepting directories instead.

    :param filelist:        a list of filepath strings
    :param extension:       output list contains only files with this string extension. (txt, tif, etc)

    :return new_filelist:   sanitized file list


    moves a file, ensures destination directory exists

    :param source:      the current full location of the file
    :param destination:  the desired full location of the file


    Simple script to track downloads of dnppy assets. Generates
    text file report with some key stats in it that help indicate
    the number of downloads, and whether our user base is mostly
    32 or 64 bit.


    This function creates a batch file for running sphinx-build on
    the developers system then runs it. The batch file is saved
    for troubleshooting purposes. This uses absolute filepaths,
    so the developer does not need to modify their PATH variable.


downloads and unzips a shape file of VA for testing purposes


structural similarity measurement system.


    Reads data from the galaxies.hdf5 file inside sam_output_filepath.
    The option number_of_galaxies sets the _approximate_ number of galaxies
    in the output (which are drawn, randomly, from the sample, taking into
    account halo press-schechter weights. Other options allow to select
    by minimum mass of the final galaxy.

    Returns a dictionary of dictionaries containing times as keys in the
    first level, dataset names in the second level and the arrays
    associated with each dataset in the last level.
    Redshift and time information can be obtained from the special keys: zout
    and tout.


 Tests the module ploting the time evolution of galaxy mass.
        gtype can be either: all, central/cen or sat/satellite.


    Filters a dictionary full of numpy (or similar) arrays using 'ok'
    filter array.

    Returns a new up-to-date dictionary


    Filters a dictionary full of numpy (or similar) arrays using 'ok'
    filter array.

    NB the dictionary is altered in the process.


Concatenates all the keys of two dictionaries.


    Prints to screen summary statistics about errors in a particular output.

    Input:  h5file -> h5py file object
            error_codes, optional -> list with exit codes considered to be errors.
                                     Default: ['e','g','h','H','s','i','p']


Concatenates a matrix (dataset) called dataset_name to an openned HDF5 file (storage), creating if necessary


 Reads the galaxy parameters from file
        Input: filename
        Output: dictionary of dictionaries containing all data
                example:   Mgas = d['M31']['Mgas']


 Prepares a galaxies.hdf5 file from a dictionary of galaxy
        data. Will assume a constant SFR and compute the evolution
        of Mgas and Mstars accordingly.

        Input: data_dict -> dictionary with structure:
                            d[name] = {'Mgas':Mgas,
                                      'Mstars':Mstars,
                                      'r_disk':r_disk,
                                      'SFR':SFR}
               t0 -> initial snapshot time (earliest), in Gyr
               tf -> final snapshot time (present), in Gyr
               nt -> number of snapshots
               optional, output_filename -> name of the output filename


    Reads data from the galaxies.hdf5 file inside sam_output_filepath.
    The option number_of_galaxies sets the _approximate_ number of galaxies
    in the output (which are drawn, randomly, from the sample, taking into
    account halo Press-Schechter weights.

    Returns a dictionary with the structure:
        { Galaxy_ID : { dataset_name : time_series_array }}
    for all galaxies/datasets.

    Missing items in the time series are replaced by the value fill_value.


    Computes a Probability Density Distribution

    Uses scipy's kernel density estimation to compute normalized PDFs of a
    given array.

    Parameters
    ----------
    data : array
        An array or astropy.units.Quantity object containing some data. In the
        case of the latter, units are reported in the axes.
    name : str
        Name of the quantity whose PDF is being plotted
    plot_histogram : bool
        If True, plots an histogram together with the kde, for checking.
    ax : matplotlib.axes.Axes
        The axis where the figures should be plotted (typically, a panel in a
        subplot). If set to None, a new axis is generated.
    vmin, vmax : float
        The minimum and maximum values.
    log : bool
        Whether the ideia is to plot $PDF(data)$ or $PDF(log_{10}(data))$.
    log0 : float or str or None
        Sets the behaviour when using log=True and there is a 0 value in `data`.
        If None, zero values (and infinite logs) in `data` will be propagated.
        If set to 'remove', they are removed before further processing.
        If set to a real number, the 0 is substituted by the number (this is the
        most convenient for plotting).

    Returns
    -------
    x,y : numpy.ndarray
        Values used for the PDF


Plots the time variation of a quantity for a given galaxy


Plots the time variation of a quantity


Prepares a page o plots


Prepares portfolios of various galaxies for a given Magnetizer run.


    Plots the redshift evolution of the 25th, 50th and 85 percentiles of a
    given quantity. This can be a single panel or a set of panels showing
    different mass bins.

    Parameters
    ----------
    quantity : str
        Name of the quantity to be plotted (e.g. 'Br').
    mag_run : MagnetizerRun
        A MagnetizerRun object containing the run.
    position : float
        For radial dependent quantities, plot_redshift_evolution will show the
        redshift evolution at a radius r=`position`*r_disk, where r_disk is the
        half-mass radius of the disc. For scalar/global galaxy properties
        (e.g. Mgas_disk) this parameter must be set to None.
    target_redshifts: array_like
        If present, specifies which redshifts should be used for the plot.
    bin_objs : BinningObject or list
        If a BinningObject is specified, use it to construct different panels
        for each of the redshifts in the target_redshifts parameter.
        If a list of BinningObjects is specified, use the redshift associated
        with each BinningObject.
    minimum_number_per_bin : int
        Minimum number of galaxies per bin (smaller number are not plotted).
        Default: 5
    ignore_zero_valued : bool
        Ignore galaxies where the `quantity` is less than zero_value_tol.
        Default: False
    zero_value_tol : float
        See ignore_zero_valued. Default: 1e-4
    log : bool
        Plots the log of the percentiles. Default: True
    color : str
        Color of the lines and shades (same colour for all the panels).
    single_panel : bool
        Plots different bins in the same panel.
    colors : list
        List of colours to use, if in single_panel mode.
    show_t_and_z : bool
        Shows an extra x-axis with the time coordinate.
    use_t : bool
        Use time instead of redshift
    cache_intermediate : bool
        Caches intermediate quantities used in computation of quantity.
        Default: True


    Helper function that prepares a list of `MassBinningObject`s computed at
    each redshift.

    Parameters
    ----------
    mag_run


    Prepares pandas DataFrame objects from the magnetizer run

    Parameters
    ----------
    quantities : list
        List of strings with the names of the requested quantites
    magnetizer_run : MagnetizerRun
        A MagnetizerRun object containing the run.
    redshifts : list
        List of redshifts to be loaded into the DataFrame

    Returns
    -------
    df : pandas.DataFrame
        Dataframe containing all the selected quantities in selected redshifts.


    Computes extra Magnetizer quantites.

    This function needs to be called with either gal_id or z different
    from None - i.e. the extra quantity qname will be computed for a given
    galaxy at various redshifts or for various galaxies at a single redshift.

    Some of the available quantities are:
    * '|Bp|'/'|Br|'/'|Bz|' - Absolute value of a B component
    * 'Btot' - Total (large scale) magnetic field strength
    * 'Bfull' - Total magnetic field strength
    * r'Bmax' - Maximum field strength
    * r'b' - Turbulent magnetic field strength
    * r'growth' - Growth rate of the B (assuming no radial variation)
    * r'growth_max' - Growth rate of the maximum field strength
    * r'Bfloor' - Target strength of the floor (independently estimated)
    * 'V' - Rotation curve
    * 'D' - Dynamo number
    * 'Dc'/'D_'Dcrit' - critical dynamo number
    * r'D_Dc' - D/Dc
    * 'R_u' - Reynolds number associated with vertical outflow
    * 'p' - Magnetic pitch angle
    * r'B_Beq' - |B|/B_eq
    * r'\tau\Omega'
    * 'q'
    * 'l/h'
    * 'h/r'

    Also, for convenience: any quantity, Q, can be computed at the radius of
    the maximum field strength [i.e. Q(rmax) where B(rmax)=Bmax]
    using 'Q_at_Bmax'.

    Parameters
    ----------
    qname : string
        code-name of the quantity

    mag_run : MagnetizerRun

    gal_id : integer
        index of the required galaxy. Having this different from None
        signals that the redshift evolution of a given galaxy should be
        computed
    z : float
        target redshift . Having this different from None signals that
        the quantity needs to be computed at this redshift only for a
        range of galaxies.
    cache : bool
        Caches any intermediate quantities requested for the calculation

    Returns
    -------
    astropy quantity
        if gal_id!=None, this will have shape (ngrid,nz) or (nz)
        if z!=None, this will have shape (ngals,ngrid) or (ngals)


        Removes incomplete and invalid data from a dataset.

        Parameters
        ----------
        dataset :

        iz :
             (Default value = slice(None)

        Returns
        -------


        Removes incomplete and invalid data from a dataset.

        Parameters
        ----------
        dataset :

        gal_id :

        ivol :

        profile :
             (Default value = True)
        pre_selected_gal_id :
             (Default value = False)

        Returns
        -------


Auxiliary function: gets index of closest redshift


        Saves the parameters to an input file

        Parameters
        ----------
        filname : str
            Name of the file where the input parameters should be saved`


Set the top level directories pysat uses to store and load data.

        Parameters
        ----------
        path : string or list-like of str
            Valid path(s) to directory
        store : bool
            Optionally store parameters to disk. Present to support a
            Deprecated method. (default=True)


Clear all stored settings and sets pysat defaults.

        Note
        ----
        pysat parameters without a default value are set to []


Restore default pysat parameters.

        Note
        ----
        Does not modify any stored custom user keys or pysat parameters
        without a default value.


Store parameters using the filename specified in `self.file_path`.


Report the current orbit to log at the info level.


Create null arrays for storing orbit info.


Prepare data structure for breaking data into orbits.

        Raises
        ------
        ValueError
            If the the Instrument bounds are set to load overlapping data sets


Determine where breaks in an equatorial satellite orbit occur.

        Looks for negative gradients in local time (or longitude) as well as
        breaks in UT.

        Parameters
        ----------
        orbit_index_period : float
            The change in value of supplied index parameter for a single orbit
            (default=24.0)

        Raises
        ------
        ValueError
            If the `orbit_index` attribute is not set to an appropriate value,
            or if the requested index not in loaded data


Determine where breaks in a polar orbiting satellite orbit occur.

        Raises
        ------
        ValueError
            If the `orbit_index` attribute is not set to an appropriate value,
            or if the requested index not in the loaded data

        Note
        ----
        Looks for sign changes in latitude (magnetic or geographic) as well as
        breaks in UT.


Find orbital breaks in a dataset with orbit numbers occur.

        Raises
        ------
        ValueError
            If the `orbit_index` attribute is not set to an appropriate value,
            or if the requested orbit not in the loaded data

        Note
        ----
        Looks for changes in unique values.


Load a particular orbit into .data for loaded day.

        Parameters
        ----------
        orbit_num : int
            Orbit number. Note that the first orbit is `orbit_num=1`,
            rather than a zero index. Negative indexes are allowed
            with `-1` as the last orbit.

        Raises
        ------
        ValueError
            If `orbit_num` set to 0, or if requested orbit past loaded orbits

        Note
        ----
        A day of data must be loaded before this routine functions properly.
        If the last orbit of the day is requested, it will NOT automatically be
        padded with data from the next day.


Provide a deep copy of object.

        Returns
        -------
        Orbits class instance
            Copy of self


Retrieve current orbit number.

        Returns
        -------
        int or NoneType
            None if no orbit data. Otherwise, returns orbit number, beginning
            with zero. The first and last orbit of a day is somewhat ambiguous.
            The first orbit for day n is generally also the last orbit
            on day n - 1. When iterating forward, the orbit will be labeled
            as first (0). When iterating backward, orbit labeled as the last.


Load a particular orbit into .data for loaded day.

        Parameters
        ----------
        orbit_num : int
            orbit number, 1 indexed (1-length or -1 to -length) with sign
            denoting forward or backward indexing

        Raises
        ------
        ValueError
            If index requested lies beyond the number of orbits

        Note
        ----
        A day of data must be loaded before this routine functions properly.
        If the last orbit of the day is requested, it will automatically be
        padded with data from the next day. The orbit counter will be
        reset to 1.


Load the next orbit into associated `Instrument.data` object.

        Raises
        ------
        RuntimeError
            Placed in code that a user should never be able to reach

        Note
        ----
        Forms complete orbits across day boundaries. If no data loaded
        then the first orbit from the first date of data is returned.


Load the previous orbit into associated `Instrument.data` object.

        Raises
        ------
        RuntimeError
            Placed in code that a user should never be able to reach

        Note
        ----
        Forms complete orbits across day boundaries. If no data loaded
        then the last orbit of data from the last day is loaded.


Update the file list (`self.files`) with empty files removed.

        Parameters
        ----------
        path : str
            Path to top-level containing files


Attach stored file lists to `self.files`.

        Parameters
        ---------
        files_info : pds.Series
            Stored file information, filenames indexed by datetime

        Note
        ----
        Updates the file list (files), `start_date`, and `stop_date` attributes
        of the Files class object


Update the file list (`self.files`) to ensure uniqueness.

        Note
        ----
        Logs a warning if there are files with duplicate datetimes. Keeps
        one of each of the duplicated files while dropping all other duplicated
        times.


Store currently loaded filelist for instrument onto filesystem.

        Moves current filelist, if different, to .pysat/archive


Load stored filelist.

        Parameters
        ----------
        prev_version : bool
            If True, will load previous version of file list
        update_path : bool
            If True, the path written to stored info will be
            assigned to `self.data_path` (default=True)

        Returns
        -------
        pandas.Series
            File path names, indexed by datetime. Series is empty if no
            files are found.


Remove the data directory path from filenames.

        Parameters
        ----------
        file_series : pds.Series or NoneType
            Series of filenames, potentially with file paths (default=None)

        Returns
        -------
        pds.series or None
            If `file_series` is a Series, removes `self.data path` from the
            filename, if present.  Returns None if `path_input` is None.


Provide a deep copy of object.

        Returns
        -------
        Files class instance
            Copy of self


Update list of files, if there are changes.

        Note
        ----
        Calls underlying list_files_rtn for the particular science instrument.
        Typically, these routines search in the pysat provided path,
        pysat_data_dir/platform/name/tag/inst_id, where pysat_data_dir is set by
        `pysat.params['data_dirs'] = path`.


Produce a list of files and format it for Files class.

        Parameters
        ----------
        data_path : str or NoneType
            Top level directory to search files for. This directory
            is provided by pysat to the `instrument_module.list_files`
            functions as `data_path`. (default=None)
        format_str : str or NoneType
            Provides the naming pattern of the instrument files and the
            locations of date information so an ordered list may be produced.
            Supports 'year', 'month', 'day', 'hour', 'minute', 'second',
            'version', 'revision', and 'cycle'
            Ex: 'cnofs_cindi_ivm_500ms_{year:4d}{month:02d}{day:02d}_v01.cdf'
            (deafult=None)
        two_digit_year_break : int or NoneType
            If filenames only store two digits for the year, then
            '1900' will be added for years >= two_digit_year_break
            and '2000' will be added for years < two_digit_year_break.
            If None, then four-digit years are assumed. (default=None)
        delimiter : str or NoneType
            Delimiter string upon which files will be split (e.g., '.'). If
            None, filenames will be parsed presuming a fixed width format.
            (default=None)

        Returns
        -------
        pds.Series
            A Series of filenames indexed by time. See
            `pysat.utils.files.process_parsed_filenames` for details.

        Raises
        ------
        ValueError
            If `data_path` or `format_str` is None

        Note
        ----
        Requires fixed_width or delimited filename

        Does not produce a `Files` instance, but the proper output from
        `instrument_module.list_files` method

        The '?' may be used to indicate a set number of spaces for a variable
        part of the name that need not be extracted.
        'cnofs_cindi_ivm_500ms_{year:4d}{month:02d}{day:02d}_v??.cdf'

        When parsing using fixed width filenames (`delimiter=None`), leading
        '*' wilcards are supported, '*{year:4d}{month:02d}{day:02d}_v??.cdf',
        though the '*' is not supported after the first template variable. The
        '?' wildcard may be used anywhere in the template string.

        When parsing using a delimiter, the '*' wildcard is supported
        when leading, trailing, or wholly contained between delimiters, such as
        'data_name-{year:04d}-*-{day:02d}.txt', or '*-{year:04d}-{day:02d}*',
        where '-' is the delimiter. There can not be a mixture of a template
        variable and '*' without a delimiter in between, unless the '*'
        occurs after the variable. The '?' wildcard may be used anywhere in
        the template string.

        The 'day' format keyword may be used to specify either day of month
        (if month is included) or day of year.


Boolean flag reflecting lack of data.

        Parameters
        ----------
        all_inst : bool
            Require all instruments to have data for the empty flag to be
            False, if True.  If False, the empty flag will be False if any
            instrument has data. (default=True)

        Returns
        -------
        eflag : bool
            True if there is no Instrument data, False if there is data
            in at least one/all Instruments.


Create a common time index for the loaded data.

        Returns
        -------
        cindex : pds.Series
            Series containing a common time index for the Instrument data


Get the unique elements of a list-like attribute.

        Parameters
        ----------
        attr : str
            String denoting a list-like Constellation attribute name

        Returns
        -------
        uniq_attrs : list
            List of unique attribute values for the requested Constellation
            attribute

        Raises
        ------
        AttributeError
            If the requested attribute is not present
        TypeError
            If the requested attribute is not list-like


Set an attribute across all instruments.

        Parameters
        ----------
        attr : str
            Instrument attribute
        value
            Appropriate value for the desired attribute


Call a method across all instrumennts.

        Parameters
        ----------
        method : str
            Instrument method name
        *args : list-like
            Optional list of arguments for the method
        **kwargs : dict-like
            Optional dict of keyword arguments for the method

        Raises
        ------
        AttributeError
            If `method` is missing from any Constellation Instrument.


Obtain boundaries for Instruments in Constellation.

        When setting, sets for all instruments in Constellation.

        Parameters
        ----------
        value : tuple or NoneType
            Tuple containing starting time and ending time for Instrument
            bounds attribute or None (default=None)


Date for loaded data.


Drop variables (names) from metadata.

        Parameters
        ----------
        names : str or list-like
            String or list of strings specifying the variable names to drop

        Raises
        ------
        KeyError
            If all of the keys provided in `names` is not found in the
            standard metadata, labels, or header metadata.  If a subset is
            missing, a logger warning is issued instead.


Boolean flag reflecting lack of data.

        Note
        -----
        True if there is no Instrument data in all Constellation Instrument.


Boolean flag reflecting lack of data.

        Note
        ----
        True if there is no Instrument data in any Constellation Instrument.


Combine Constellation data into an Instrument.

        Parameters
        ----------
        common_coord : bool
            For Constellations with any xarray.Dataset Instruments, True to
            include locations where all coordinate arrays cover, False to use
            the maximum location range from the list of coordinates
            (default=True)
        fill_method : str or NoneType
            Fill method if common data coordinates do not match exactly. If
            one of 'nearest', 'pad'/'ffill', 'backfill'/'bfill', or None then
            no interpolation will occur.  If 'linear', 'zero', 'slinear',
            'quadratic', 'cubic', or 'polynomial' are used, then 1D or ND
            interpolation will be used. (default=None)

        Returns
        -------
        inst : pysat.Instrument
            A pysat Instrument containing all data from the constellation at a
            common time index

        Note
        ----
        Uses the common index, `self.index`, that was defined using information
        from the Constellation Instruments in combination with a potential
        user-supplied resolution defined through `self.index_res`.


Retrieve list of uniquely named variables from all loaded data.


Register a function to modify data of member Instruments.

        Parameters
        ----------
        function : str or function object
            Name of function or function object to be added to queue
        apply_inst : bool
            Apply the custom function to all Instruments if True, or at the
            Constellation level if False. (default=True)
        at_pos : str or int
            Accepts string 'end' or a number that will be used to determine
            the insertion order if multiple custom functions are attached
            to an Instrument object. (default='end').
        args : list, tuple, or NoneType
            Ordered arguments following the instrument object input that are
            required by the custom function (default=None)
        kwargs : dict or NoneType
            Dictionary of keyword arguments required by the custom function
            (default=None)

        Note
        ----
        Functions applied using `custom_attach_cost` may add, modify, or use
        the data within any Instrument inside of the function, and so should not
        return anything.

        Constellation-level custom functions are applied after Instrument-level
        custom functions whenever the `load` method is called.

        Unlike Instrument-level custom functions, Constellation-level custom
        functions should take a Constellation object as their first input
        argument.

        See Also
        --------
        Instrument.custom_attach : base method for attaching custom functions


Clear the custom function list.

        See Also
        --------
        Instrument.custom_clear : base method for clearing custom functions


Load instrument data into Instrument `object.data`.

        Parameters
        ----------
        *args : list reference
            References a list of input arguments
        **kwargs : dict reference
            References a dict of input keyword arguments

        See Also
        --------
        Instrument.load : base method for loading Instrument data


Download instrument data into Instrument `object.data`.

        Parameters
        ----------
        *args : list reference
            References a list of input arguments
        **kwargs : dict reference
            References a dict of input keyword arguments

        See Also
        --------
        Instrument.download : base method for loading Instrument data

        Note
        ----
        If individual instruments require specific kwargs that differ from
        other instruments, define that in the individual instrument rather
        than this method.


Alter variables using input function.


Set the default label values for a data variable.

        Parameters
        ----------
        data_var : str or list
            Single or multiple data variable name(s).
        data_type : type, list, or NoneType
            Type for the data value(s) or None if not specified (default=None)

        Note
        ----
        Sets NaN for all float values, -1 for all int values, 'data_var' for
        names labels, '' for all other str values, and None for any other
        data type. If there are multiple data types, sets the data type (if
        included).  Otherwise, chooses the first type in the tuple.


Set default meta attributes for variable.

        Parameters
        ----------
        new_label : str
            New label to use in the Meta object
        current_label : str
            The current label used within Meta object
        default_type : type
            Type of value to be stored
        use_names_default : bool
            if True, MetaData variable names are used as the default
            value for the specified Meta attributes settings (default=False)

        Note
        ----
        Not intended for end user


Return boolean True if there is no metadata.

        Returns
        -------
        bool
            Returns True if there is no data, and False if there is data


Add metadata variables to `self` that are in other but not in `self`.

        Parameters
        ----------
        other : pysat.Meta
            Metadata to be merged into `self`


Keep variables (keep_names) while dropping other parameters.

        Parameters
        ----------
        keep_names : list-like
            Variables to keep


Apply the existing meta labels from `self` onto different MetaData.

        Parameters
        ----------
        other_meta : Meta
            Meta object to have default labels applied

        Returns
        -------
        other_updated : Meta
            Meta object with the default labels applied


Apply labels for default meta labels from other onto `self`.

        Parameters
        ----------
        other_meta : Meta
            Meta object to take default labels from


Provide stored name (case preserved) for case insensitive input.

        Parameters
        ----------
        name : str or list
            Single or multiple variable name(s) using any capitalization scheme.

        Returns
        -------
        case_names : str or list
            Maintains the same type as input, returning the stored name(s) of
            the meta object.

        Note
        ----
        If name is not found (case-insensitive check) then `name` is returned,
        as input. This function is intended to be used to help ensure the
        case of a given variable name is the same across the Meta object.


Case-insensitive check for attribute names in this class.

        Parameters
        ----------
        attr_name : str
            Name of attribute to find

        Returns
        -------
        has_name : bool
            True if the case-insensitive check for attribute name is successful,
            False if no attribute name is present.


Retrieve preserved case name for case insensitive value of name.

        Parameters
        ----------
        name : str or list
            Single or multiple variable name(s) to get stored case form.

        Returns
        -------
        out_name : str or list
            Maintains same type as input. Name(s) in proper case.

        Note
        ----
        Checks first within standard attributes. If not found, returns supplied
        name as it is available for use. Intended to be used to help ensure that
        the same case is applied to all repetitions of a given variable name.


Update the preserved case name for mapped value of name.

        Parameters
        ----------
        mapper : dict or func
            Dictionary with old names as keys and new names as variables or
            a function to apply to all names

        Note
        ----
        Checks first within standard attributes. If not found, returns supplied
        name as it is available for use. Intended to be used to help ensure that
        the same case is applied to all repetitions of a given variable name.


Concats two metadata objects together.

        Parameters
        ----------
        other_meta : Meta
            Meta object to be concatenated
        strict : bool
            If True, this flag ensures there are no duplicate variable names
            (default=False)

        Returns
        -------
        mdata : Meta
            Concatenated object

        Raises
        ------
        KeyError
            If there are duplicate keys and the `strict` flag is True.

        Note
        ----
        Uses units and name label of `self` if `other_meta` is different


Remove and return metadata about variable.

        Parameters
        ----------
        label_name : str
            Meta key for a data variable

        Returns
        -------
        output : pds.Series
            Series of metadata for variable


Transfer non-standard attributes in Meta to the MetaHeader object.

        Parameters
        ----------
        strict_names : bool
            If True, produces an error if the MetaHeader object already
            has an attribute with the same name to be copied (default=False)

        Raises
        ------
        AttributeError
            If `strict_names` is True and a global attribute would be updated.


Transfer non-standard attributes in Meta to Instrument object.

        Parameters
        ----------
        inst : pysat.Instrument
            Instrument object to transfer attributes to
        strict_names : bool
            If True, produces an error if the Instrument object already
            has an attribute with the same name to be copied (default=False)

        Raises
        ------
        ValueError
            If `inst` type is not pysat.Instrument.

        Note
        ----
        `pysat.files.io.load_netCDF` and similar routines are only able to
        attach netCDF4 attributes to a Meta object. This routine identifies
        these attributes and removes them from the Meta object. Intent is to
        support simple transfers to the pysat.Instrument object.

        Will not transfer names that conflict with pysat default attributes.


Add epoch or time-index metadata if it is missing.

        Parameters
        ----------
        epoch_name : str
            Data key for time-index or epoch data


Convert self into a dictionary.

        Parameters
        ----------
        preserve_case : bool
            If True, the case of variables within self are preserved. If False,
            all variables returned as lower case. (default=False)

        Returns
        -------
        export_dict : dict
            A dictionary of the metadata for each variable of an output file


Create instrument metadata object from csv.

        Parameters
        ----------
        filename : string
            Absolute filename for csv file or name of file stored in pandas
            instruments location
        col_names : list-like collection of strings
            Column names in csv and resultant meta object
        sep : string
            Column seperator for supplied csv filename
        **kwargs : dict
            Optional kwargs used by `pds.read_csv`

        Note
        ----
        Column names must include at least ['name', 'long_name', 'units'],
        which are assumed if `col_names` is None


Update the `label_type` attribute, adjusting types as appropriate.


Evaluate the label type for validity.

        Parameters
        ----------
        val_type : type
            Variable type for the value to be assigned to a MetaLabel

        Returns
        -------
        valid : bool
            True if this is a valid type, False if not valid


Retrieve the default values for each label based on their type.

        Parameters
        ----------
        val_type : type
            Variable type for the value to be assigned to a MetaLabel
        data_type : type or NoneType
            Type for the data values or None if not specified (default=None)

        Returns
        -------
        default_val : str, float, int, NoneType
            Sets NaN for all float values, -1 for all int values, and '' for
            all str values, and None for any other data type


Retrieve the default values for each label based on their type.

        Parameters
        ----------
        attr_name : str
            Label attribute name (e.g., max_val)
        data_type : type or NoneType
            Type for the data values or None if not specified (default=None)

        Returns
        -------
        default_val : str, float, int, or NoneType
            Sets NaN for all float values, -1 for all int values, and ''
            for all str values except for 'scale', which defaults to 'linear',
            and None for any other data type

        Raises
        ------
        ValueError
            For unknown `attr_name`


Remove data from MetaLabels.

        Parameters
        ----------
        names : str or list-like
            Attribute or MetaData name(s)

        Raises
        ------
        AttributeError or KeyError
            If any part of `names` is missing and cannot be dropped


Update MetaLabels with a new label.

        Parameters
        ----------
        lattr : str
            Attribute for this new label
        lname : str
            MetaData name for this label
        ltype : type
            Expected data type for this label

        Raises
        ------
        TypeError
            If meta data type is invalid


Drop variables (names) from MetaHeader.

        Parameters
        ----------
        names : list-like
            List of strings specifying the variable names to drop


Convert the header data to a dictionary.

        Returns
        -------
        header_data : dict
            Global meta data where the keys are the attribute names and values
            the metadata for that attribute.


Get the standard epoch name used in this data object.

        Parameters
        ----------
        data : pds.DataFrame, xr.Dataset, or NoneType
            Desired data object to select from or None to use `data` attribute

        Returns
        -------
        epoch_names : list
            List of standard epoch names included in the data indexes


Determine whether or not data has been loaded.

        Parameters
        ----------
        data : NoneType, pds.DataFrame, or xr.Dataset
            Data object. If None, will use `self.data`.

        Returns
        -------
        bool
            True if there is no Instrument data, False if there is data


Retrieve the time index for the loaded data.

        Parameters
        ----------
        data : NoneType, pds.DataFrame, or xr.Dataset
            Data object. If None, use `self.data`.

        Returns
        -------
        index : pds.Series
            Series containing the time indices for the Instrument data


Assign all external instrument attributes to the Instrument object.

        Parameters
        ----------
        by_name : boolean
            If True, uses `self.platform` and `self.name` to load the
            Instrument, if False uses inst_module. (default=False)

        Raises
        ------
        KeyError
            If unknown platform or name supplied
        ImportError
            If there was an error importing the instrument module
        AttributeError
            If a required Instrument method is missing

        Note
        ----
        methods
            init, preprocess, and clean
        functions
            load, list_files, download, and list_remote_files, concat_data
        attributes
            directory_format, file_format, multi_file_day, orbit_info, and
            pandas_format
        test attributes
            _test_download, _test_download_ci, _new_tests, and _password_req


Update Instrument attributes using Constellation data.

        Parameters
        ----------
        const : pysat.Constellation
            Data contained in a Constellation of Instruments

        Note
        ----
        Updates the 'platform', 'name', 'tag', 'inst_id', 'clean_level',
        'pad', 'clean_level', 'date', 'doy', 'yr', 'acknowledgements',
        'references', and 'pandas_format' attributes


Load data for an instrument on given date or filename index.

        Parameters
        ----------
        date : dt.datetime or NoneType
            File date (default=None)
        fid : int or NoneType
            Filename index value (default=None)
        inc : dt.timedelta, int, or NoneType
            Increment of files or dates to load, starting from the
            root date or fid (default=None)
        load_kwargs : dict or NoneType
            Dictionary of keywords that may be options for specific instruments.
            If None, uses `self.kwargs['load']`. (default=None)

        Returns
        -------
        data : pds.DataFrame or xr.Dataset
            pysat data
        meta : pysat.Meta
            pysat meta data

        Raises
        ------
        ValueError
            If both `date` and `fid` are None, or if `inc` left unspecified


Load the next days data (or file) without incrementing the date.

        Parameters
        ----------
        load_kwargs : dict or NoneType
            Dictionary of keywords that may be options for specific instruments.
            If None, uses `self.kwargs['load']`. (default=None)

        Returns
        -------
        data : pds.DataFrame or xr.Dataset
            pysat data
        meta : pysat.Meta
            pysat meta data

        Note
        ----
        Repeated calls will not advance date/file and will produce the same
        data.

        Uses info stored in object to either increment the date,
        or the file. Looks for `self._load_by_date` flag.


Load the previous days data (or file) without decrementing the date.

        Parameters
        ----------
        load_kwargs : dict or NoneType
            Dictionary of keywords that may be options for specific instruments.
            If None, uses `self.kwargs['load']`. (default=None)

        Returns
        -------
        data : pds.DataFrame or xr.Dataset
            pysat data
        meta : pysat.Meta
            pysat meta data

        Note
        ----
        Repeated calls will not decrement date/file and will produce the same
        data

        Uses info stored in object to either decrement the date,
        or the file. Looks for `self._load_by_date` flag.


Set the necesssary load attributes.

        Sets `self._load_by_date`, `self.date`, `self._fid`, `self.yr`, and
        `self.doy`

        Parameters
        ----------
        date : dt.datetime.date or NoneType
            File date (default=None)
        fid : int or NoneType
            Filename index value (default=None)


Determine the two-character type code for a given variable type.

        Parameters
        ----------
        coltype : type or np.dtype
            The type of the variable

        Returns
        -------
        str
            The variable type code for the given type

        Raises
        ------
        TypeError
            When coltype is unknown

        Note
        ----
        Understands np.dtype, numpy int, uint, and float variants, and
        str subclasses


Support file writing by determining data type and other options.

        Parameters
        ----------
        data : pandas object
            Data to be written

        Returns
        -------
        data : pandas object
            Data that was supplied, reformatted if necessary
        data_type : type or dtype
            Type for data values
        datetime_flag : bool
            True if data is np.datetime64, False otherwise


Boundaries for iterating over instrument object by date or file.

        Parameters
        ----------
        start : dt.datetime, str, or NoneType
            Start of iteration, disregarding any time of day information.
            If None uses first data date. List-like collection also
            accepted, allowing mutliple bound ranges. (default=None)
        stop :  dt.datetime, str, or None
            Stop of iteration, inclusive of the entire day regardless of
            time of day in the bounds. If None uses last data date.
            List-like collection also accepted, allowing mutliple bound
            ranges, though it must match `start`. (default=None)
        step : str, int, or NoneType
            Step size used when iterating from start to stop. Use a
            Pandas frequency string ('3D', '1M') or an integer (will assume
            a base frequency equal to the file frequency). If None, defaults to
            a single unit of file frequency (typically 1 day) (default=None).
        width : pandas.DateOffset, int, or NoneType
            Data window used when loading data within iteration. If None,
            defaults to a single file frequency (typically 1 day) (default=None)

        Raises
        ------
        ValueError
            If `start` and `stop` don't have the same type, or if too many
            input argument supplied, or unequal number of elements in
            `start`/`stop`, or if bounds aren't in increasing order, or if
            the input type for `start` or `stop` isn't recognized

        Note
        ----
        Both start and stop must be the same type (date, or filename) or None.
        Only the year, month, and day are used for date inputs.

        Examples
        --------
        ::

            import datetime as dt
            import pandas as pds
            import pysat

            inst = pysat.Instrument(platform=platform,
                                    name=name,
                                    tag=tag)
            start = dt.datetime(2009, 1, 1)
            stop = dt.datetime(2009, 1, 31)

            # Defaults to stepping by a single day and a data loading window
            # of one day/file.
            inst.bounds = (start, stop)

            # Set bounds by file. Iterates a file at a time.
            inst.bounds = ('filename1', 'filename2')

            # Create a more complicated season, multiple start and stop dates.
            start2 = dt.datetetime(2010,1,1)
            stop2 = dt.datetime(2010,2,14)
            inst.bounds = ([start, start2], [stop, stop2])

            # Iterate via a non-standard step size of two days
            inst.bounds = ([start, start2], [stop, stop2], '2D')

            # Load more than a single day/file at a time when iterating
            inst.bounds = ([start, start2], [stop, stop2], '2D',
                           dt.timedelta(days=3))


List of variables for the loaded data.


List of variables for the loaded data, excluding time index.


Create a deep copy of the entire Instrument object.

        Returns
        -------
        pysat.Instrument


Concatonate data to self.data for xarray or pandas as needed.

        Parameters
        ----------
        new_data : pandas.DataFrame, xarray.Dataset, or list of such objects
            New data objects to be concatonated
        prepend : bool
            If True, assign new data before existing data; if False append new
            data (default=False)
        include : int or NoneType
            Index at which `self.data` should be included in `new_data` or None
            to use `prepend` (default=None)
        **kwargs : dict
            Optional keyword arguments passed to pds.concat or xr.concat

        Note
        ----
        For pandas, sort=False is passed along to the underlying
        `pandas.concat` method. If sort is supplied as a keyword, the
        user provided value is used instead.  Recall that sort orders the
        data columns, not the data values or the index.

        For xarray, `dim=Instrument.index.name` is passed along to xarray.concat
        except if the user includes a value for dim as a keyword argument.

        Examples
        --------
        ::

            # Concatonate data before and after the existing Instrument data
            inst.concat_data([prev_data, next_data], include=1)


Attach a function to custom processing queue.

        Custom functions are applied automatically whenever `.load()`
        command called.

        Parameters
        ----------
        function : str or function object
            Name of function or function object to be added to queue
        at_pos : str or int
            Accepts string 'end' or a number that will be used to determine
            the insertion order if multiple custom functions are attached
            to an Instrument object (default='end')
        args : list, tuple, or NoneType
            Ordered arguments following the instrument object input that are
            required by the custom function (default=None)
        kwargs : dict or NoneType
            Dictionary of keyword arguments required by the custom function
            (default=None)

        Note
        ----
        Functions applied using `custom_attach` may add, modify, or use
        the data within Instrument inside of the function, and so should not
        return anything.


Apply all of the custom functions to the satellite data object.

        Raises
        ------
        ValueError
            Raised when function returns any value

        Note
        ----
        This method does not generally need to be invoked directly by users.


Clear the custom function list.


Drop variables from Instrument.

        Parameters
        ----------
        names : str or list-like
            String or list of strings specifying the variables names to drop

        Raises
        ------
        KeyError
            If all of the variable names provided in `names` are not found
            in the variable list. If a subset is missing, a logger warning is
            issued instead.


Get today's date (UTC), with no hour, minute, second, etc.

        Returns
        -------
        today_utc: datetime
            Today's date in UTC


Get tomorrow's date (UTC), with no hour, minute, second, etc.

        Returns
        -------
        datetime
            Tomorrow's date in UTC


Get yesterday's date (UTC), with no hour, minute, second, etc.

        Returns
        -------
        datetime
            Yesterday's date in UTC


Iterate forward through the data loaded in Instrument object.

        Bounds of iteration and iteration type (day/file) are set by
        `bounds` attribute.

        Parameters
        ----------
        verifyPad : bool
            Passed to `self.load()`. If True, then padded data within
            the load method will be retained. (default=False)

        Note
        ----
        If there were no previous calls to load then the
        first day(default)/file will be loaded.


Iterate backwards through the data in Instrument object.

        Bounds of iteration and iteration type (day/file)
        are set by `bounds` attribute.

        Parameters
        ----------
        verifyPad : bool
            Passed to `self.load()`. If True, then padded data within
            the load method will be retained. (default=False)

        Note
        ----
        If there were no previous calls to load then the first day (default) or
        file will be loaded.


Rename variables within both data and metadata.

        Parameters
        ----------
        mapper : dict or func
            Dictionary with old names as keys and new names as variables or
            a function to apply to all names
        lowercase_data_labels : bool
            If True, the labels applied to `self.data` are forced to lowercase.
            The case supplied in `mapper` is retained within `inst.meta`.

        Examples
        --------
        ::

            # Standard renaming using a dict
            new_mapper = {'old_name': 'new_name', 'old_name2':, 'new_name2'}
            inst.rename(new_mapper)

            # Standard renaming using a function
            inst.rename(str.upper)

        pysat supports differing case for variable labels across the data and
        metadata objects attached to an Instrument. Since Meta is
        case-preserving (on assignment) but case-insensitive to access, the
        labels used for data are always valid for metadata. This feature may be
        used to provide friendlier variable names within pysat while also
        maintaining external format compatibility when writing files.
        ::

            # Example with lowercase_data_labels
            inst = pysat.Instrument('pysat', 'testing')
            inst.load(2009, 1)
            mapper = {'uts': 'Pysat_UTS'}
            inst.rename(mapper, lowercase_data_labels=True)

            # Note that 'Pysat_UTS' was applied to data as 'pysat_uts'
            print(inst['pysat_uts'])

            # Case is retained within inst.meta, though data access to meta is
            # case insensitive
            print('True meta variable name is ', inst.meta['pysat_uts'].name)

            # Note that the labels in meta may be used when creating a file,
            # thus, 'Pysat_UTS' would be found in the resulting file
            inst.to_netcdf4('./test.nc', preserve_meta_case=True)

            # Load in file and check
            raw = netCDF4.Dataset('./test.nc')
            print(raw.variables['Pysat_UTS'])


Load the instrument data and metadata.

        Parameters
        ----------
        yr : int or NoneType
            Year for desired data. pysat will load all files with an
            associated date between `yr`, `doy` and `yr`, `doy` + 1.
            (default=None)
        doy : int or NoneType
            Day of year for desired data. Must be present with `yr` input.
            (default=None)
        end_yr : int or NoneType
            Used when loading a range of dates, from `yr`, `doy` to `end_yr`,
            `end_doy` based upon the dates associated with the Instrument's
            files. Date range is inclusive for `yr`, `doy` but exclusive for
            `end_yr`, `end_doy`. (default=None)
        end_doy : int or NoneType
            Used when loading a range of dates, from `yr`, `doy` to `end_yr`,
            `end_doy` based upon the dates associated with the Instrument's
            files. Date range is inclusive for `yr`, `doy` but exclusive for
            `end_yr`, `end_doy`. (default=None)
        date : dt.datetime or NoneType
            Date to load data. pysat will load all files with an associated
            date between `date` and `date` + 1 day. (default=None)
        end_date : dt.datetime or NoneType
            Used when loading a range of data from `date` to `end_date` based
            upon the dates associated with the Instrument's files. Date range
            is inclusive for `date` but exclusive for `end_date`. (default=None)
        fname : str or NoneType
            Filename to be loaded (default=None)
        stop_fname : str or NoneType
            Used when loading a range of filenames from `fname` to `stop_fname`,
            inclusive. (default=None)
        verifyPad : bool
            If True, padding data not removed for debugging. Padding
            parameters are provided at Instrument instantiation. (default=False)
        **kwargs : dict
            Dictionary of keywords that may be options for specific instruments.

        Raises
        ------
        TypeError
            For incomplete or incorrect input
        ValueError
            For input incompatible with Instrument set-up

        Note
        ----
        Loads data for a chosen instrument into `.data`. Any functions chosen
        by the user and added to the custom processing queue (`.custom.attach`)
        are automatically applied to the data before it is available to
        user in `.data`.

        A mixed combination of `.load()` keywords such as `yr` and `date` are
        not allowed.

        `end` kwargs have exclusive ranges (stop before the condition is
        reached), while `stop` kwargs have inclusive ranges (stop once the
        condition is reached).

        Examples
        --------
        ::

            import datetime as dt
            import pysat

            inst = pysat.Instrument('pysat', 'testing')

            # Load a single day by year and day of year
            inst.load(2009, 1)

            # Load a single day by date
            date = dt.datetime(2009, 1, 1)
            inst.load(date=date)

            # Load a single file, first file in this example
            inst.load(fname=inst.files[0])

            # Load a range of days, data between
            # Jan. 1st (inclusive) - Jan. 3rd (exclusive)
            inst.load(2009, 1, 2009, 3)

            # Load a range of days using datetimes
            date = dt.datetime(2009, 1, 1)
            end_date = dt.datetime(2009, 1, 3)
            inst.load(date=date, end_date=end_date)

            # Load several files by filename. Note the change in index due to
            # inclusive slicing on filenames!
            inst.load(fname=inst.files[0], stop_fname=inst.files[1])


Retrieve a time-series of remote files for chosen instrument.

        Parameters
        ----------
        start : dt.datetime or NoneType
            Starting time for file list. A None value will start with the first
            file found. (default=None)
        stop : dt.datetime or NoneType
            Ending time for the file list.  A None value will stop with the last
            file found. (default=None)
        **kwargs : dict
            Dictionary of keywords that may be options for specific instruments.
            The keyword arguments 'user' and 'password' are expected for remote
            databases requiring sign in or registration.

        Returns
        -------
        pds.Series
            pandas Series of filenames indexed by date and time

        Note
        ----
        Default behaviour is to return all files.  User may additionally
        specify a given year, year/month, or year/month/day combination to
        return a subset of available files.


Determine first and last available dates for remote data.

        Parameters
        ----------
        start : dt.datetime or NoneType
            Starting time for file list. A None value will start with the first
            file found. (default=None)
        stop : dt.datetime or NoneType
            Ending time for the file list.  A None value will stop with the last
            file found. (default=None)
        **kwargs : dict
            Dictionary of keywords that may be options for specific instruments.
            The keyword arguments 'user' and 'password' are expected for remote
            databases requiring sign in or registration.

        Returns
        -------
        List
            First and last datetimes obtained from `remote_file_list`

        Note
        ----
        Default behaviour is to search all files.  User may additionally
        specify a given year, year/month, or year/month/day combination to
        return a subset of available files.


Download new files after comparing available remote and local files.

        Parameters
        ----------
        **kwargs : dict
            Dictionary of keywords that may be options for specific instruments

        Note
        ----
        Data will be downloaded to `self.files.data_path`

        If Instrument bounds are set to defaults they are updated
        after files are downloaded.

        If no remote file listing method is available, existing local files are
        assumed to be up-to-date and gaps are assumed to be missing files.

        If `start`, `stop`, or `date_array` are provided, only files at/between
        these times are considered for updating.  If no times are provided and
        a remote listing method is available, all new files will be downloaded.
        If no remote listing method is available, the current file limits are
        used as the starting and ending times.


Download data for given Instrument object from start to stop.

        Parameters
        ----------
        start : pandas.datetime or NoneType
            Start date to download data, or yesterday if None is provided.
            (default=None)
        stop : pandas.datetime or NoneType
            Stop date (inclusive) to download data, or tomorrow if None is
            provided (default=None)
        date_array : list-like or NoneType
            Sequence of dates to download date for. Takes precedence over
            start and stop inputs (default=None)
        **kwargs : dict
            Dictionary of keywords that may be options for specific instruments.
            The keyword arguments 'user' and 'password' are expected for remote
            databases requiring sign in or registration. 'freq' temporarily
            ingested through this input option.

        Raises
        ------
        ValueError
            Raised if there is an issue creating `self.files.data_path`

        Note
        ----
        Data will be downloaded to `self.files.data_path`

        If Instrument bounds are set to defaults they are updated
        after files are downloaded.

        See Also
        --------
        pandas.DatetimeIndex


Store loaded data into a netCDF4 file.

        Parameters
        ----------
        fname : str
            Full path to save instrument object to netCDF
        base_instrument : pysat.Instrument or NoneType
            Class used as a comparison, only attributes that are present with
            self and not on base_instrument are written to netCDF. Using None
            assigns an unmodified pysat.Instrument object. (default=None)
        epoch_name : str or NoneType
            Label in file for datetime index of Instrument object
            (default=None)
        zlib : bool
            Flag for engaging zlib compression (True - compression on)
            (default=False)
        complevel : int
            An integer flag between 1 and 9 describing the level of compression
            desired. Ignored if `zlib=False`. (default=4)
        shuffle : bool
            The HDF5 shuffle filter will be applied before compressing the data.
            This significantly improves compression. Ignored if `zlib=False`.
            (default=True)
        preserve_meta_case : bool
            Flag specifying the case of the meta data variable strings. If True,
            then the variable strings within the MetaData object (which
            preserves case) are used to name variables in the written netCDF
            file. If False, then the variable strings used to access data from
            the pysat.Instrument object are used instead. (default=False)
        export_nan : list or NoneType
             By default, the metadata variables where a value of NaN is allowed
             and written to the netCDF4 file is maintained by the Meta object
             attached to the pysat.Instrument object. A list supplied here
             will override the settings provided by Meta, and all parameters
             included will be written to the file. If not listed
             and a value is NaN then that attribute simply won't be included in
             the netCDF4 file. (default=None)
        export_pysat_info : bool
            If True, platform, name, tag, inst_id, acknowledgements, and
            references will be appended to the metadata.  For some operational
            uses (e.g., conversion of Level 1 to Level 2 data), it may be
            desirable to set this to false to avoid conflicting versions of
            these parameters. (default=True)
        unlimited_time : bool
             Flag specifying whether or not the epoch/time dimension should be
             unlimited; it is when the flag is True. (default=True)
        modify : bool
             Flag specifying whether or not the changes made to the Instrument
             object needed to prepare it for writing should also be made to
             this object.  If False, the current Instrument object will remain
             unchanged. (default=False)

        Raises
        ------
        ValueError
            If required kwargs are not given values

        See Also
        --------
        pysat.utils.io.to_netcdf


Update the data types in pysat.Meta object.

        Parameters
        ----------
        key : str or list-like
            Data variable or list of these data variables for which the data
            type should be updated.


Convert from `self.kwargs` key name to the function or method name.

    Parameters
    ----------
    kwargs_key : str
        Key from `self.kwargs` dictionary

    Returns
    -------
    func_name : str
        Name of method or function associated with the input key


Get a dict of supported keywords.

    Parameters
    ----------
    local_func : function or method
        Method used to load data within pysat

    Returns
    -------
    out_dict : dict
        dict of supported keywords and default values

    Note
    ----
    If the input is a partial function then the list of keywords returned only
    includes keywords that have not already been set as part of the
    functools.partial instantiation.


Ensure all arguments are None.

    Parameters
    ----------
    args : iterable object
        Variables that are to checked to ensure None
    raise_error : bool
        A flag that if True, will raise a ValueError if any one value in `args`
        is not None (default=False)

    Returns
    -------
    all_none : bool
        Flag that is True if all `args` values are None and False otherwise

    Raises
    ------
    ValueError
        If any one value in `args` is not None and `raise_error` is True

    Note
    ----
    Used to support `.load` method checks that arguments that should be
    None are None, while also keeping the `.load` method readable


Load the test files.

    Parameters
    ----------
    fnames : list
        List of filenames.
    tag : str
        Tag name used to identify particular data set to be loaded.
        This input is nominally provided by pysat itself. (default='')
    inst_id : str
        Instrument ID used to identify particular data set to be loaded.
        This input is nominally provided by pysat itself. (default='')
    start_time : dt.timedelta or NoneType
        Offset time of start time since midnight UT. If None, instrument data
        will begin at midnight. (default=None)
    num_samples : int
        Maximum number of times to generate.  Data points will not go beyond the
        current day. (default=96)
    test_load_kwarg : any
        Keyword used for pysat unit testing to ensure that functionality for
        custom keywords defined in instrument support functions is working
        correctly. (default=None)

    Returns
    -------
    data : xr.Dataset
        Testing data
    meta : pysat.Meta
        Metadata


Load the test files.

    Parameters
    ----------
    fnames : list
        List of filenames.
    tag : str
        Tag name used to identify particular data set to be loaded.
        This input is nominally provided by pysat itself. (default='')
    inst_id : str
        Instrument ID used to identify particular data set to be loaded.
        This input is nominally provided by pysat itself. (default='')
    sim_multi_file_right : bool
        Adjusts date range to be 12 hours in the future or twelve hours beyond
        `root_date`. (default=False)
    sim_multi_file_left : bool
        Adjusts date range to be 12 hours in the past or twelve hours before
        `root_date`. (default=False)
    root_date : NoneType
        Optional central date, uses _test_dates if not specified.
        (default=None)
    non_monotonic_index : bool
        If True, time index will be non-monotonic (default=False)
    non_unique_index : bool
        If True, time index will be non-unique (default=False)
    start_time : dt.timedelta or NoneType
        Offset time of start time since midnight UT. If None, instrument data
        will begin at midnight. (default=None)
    num_samples : int
        Maximum number of times to generate.  Data points will not go beyond the
        current day. (default=864)
    sample_rate : str
        Frequency of data points, using pandas conventions. (default='100s')
    test_load_kwarg : any
        Keyword used for pysat unit testing to ensure that functionality for
        custom keywords defined in instrument support functions is working
        correctly. (default=None)
    max_latitude : float
        Latitude simulated as `max_latitude` * cos(theta(t))`, where
        theta is a linear periodic signal bounded by [0, 2 * pi) (default=90.0)
    num_extra_time_coords : int
        Number of extra time coordinates to include. (default=0)

    Returns
    -------
    data : xr.Dataset
        Testing data
    meta : pysat.Meta
        Testing metadata


Load the test files.

    Parameters
    ----------
    fnames : list
        List of filenames.
    tag : str
        Tag name used to identify particular data set to be loaded.
        This input is nominally provided by pysat itself. (default='')
    inst_id : str
        Instrument ID used to identify particular data set to be loaded.
        This input is nominally provided by pysat itself. (default='')
    sim_multi_file_right : bool
        Adjusts date range to be 12 hours in the future or twelve hours beyond
        `root_date`. (default=False)
    sim_multi_file_left : bool
        Adjusts date range to be 12 hours in the past or twelve hours before
        `root_date`. (default=False)
    root_date : NoneType
        Optional central date, uses _test_dates if not specified.
        (default=None)
    non_monotonic_index : bool
        If True, time index will be non-monotonic (default=False)
    non_unique_index : bool
        If True, time index will be non-unique (default=False)
    start_time : dt.timedelta or NoneType
        Offset time of start time since midnight UT. If None, instrument data
        will begin at midnight. (default=None)
    num_samples : int
        Maximum number of times to generate.  Data points will not go beyond the
        current day. (default=86400)
    test_load_kwarg : any
        Keyword used for pysat unit testing to ensure that functionality for
        custom keywords defined in instrument support functions is working
        correctly. (default=None)
    max_latitude : float
        Latitude simulated as `max_latitude` * cos(theta(t))`, where
        theta is a linear periodic signal bounded by [0, 2 * pi) (default=90.).

    Returns
    -------
    data : pds.DataFrame
        Testing data
    meta : pysat.Meta
        Metadata


Initialize the Instrument object with instrument specific values.


Extract Instrument attrs from file attrs loaded to `Meta.header`.