numpy format

Author: Sparks29032

src/diffpy/utils/__init__.py

@@ -13,11 +13,7 @@
 #
 ##############################################################################
 
-"""Smalled shared functions for use by other diffpy packages.
-
-Subpackages:
-
-parsers  -- various utilities related to data parsing and manipulation.
+"""Smaller shared functions for use by other diffpy packages.
 """
 
 # package version

src/diffpy/utils/parsers/custom_exceptions.py

@@ -16,9 +16,14 @@
 class UnsupportedTypeError(Exception):
     """For file types not supported by our parsers.
 
-    supported_types     -- List of supported types.
-    file                -- file triggering the error.
-    message             -- for writing a custom message.
+    Parameters
+    ----------
+    file
+        Name of file triggering the error.
+    supported_types: list
+        Supported file types.
+    message: str
+        Overwrites default message.
     """
 
     def __init__(self, file, supported_types=None, message=None):
@@ -35,8 +40,12 @@ def __init__(self, file, supported_types=None, message=None):
 class ImproperSizeError(Exception):
     """When the size of an object does not match expectations.
 
-    bad_object          -- Object with improper size.
-    message             -- for writing a custom message.
+    Parameters
+    ----------
+    bad_object
+        Object with improper size.
+    message: str
+        Overwrites default message.
     """
 
     def __init__(self, bad_object, message=None):

src/diffpy/utils/parsers/loaddata.py

@@ -19,40 +19,49 @@
 def loadData(filename, minrows=10, headers=False, hdel='=', hignore=None, **kwargs):
     """Find and load data from a text file.
 
-    The data block is identified as the first matrix block of at least minrows rows
-    and constant number of columns. This seems to work for most of the datafiles including
-    those generated by diffpy programs.
+    The data block is identified as the first matrix block of at least minrows rows and constant number of columns.
+    This seems to work for most of the datafiles including those generated by diffpy programs.
 
-    filename    -- name of the file we want to load data from.
-    minrows     -- minimum number of rows in the first data block.
-                   All rows must have the same number of floating point values.
-    headers     -- when False (defualt), the function returns a numpy array of the
-                   data in the data block. When True, the function instead returns a
-                   dictionary of parameters and their corresponding values parsed from
-                   header (information prior the data block). See hdel and hignore for
-                   options to help with parsing header information.
-    hdel        -- (only used when headers enabled) delimiter for parsing header
-                   information (default '='). e.g. using default hdel, the line
-                   'parameter = p_value' is put into the dictionary as
-                   {parameter: p_value}.
-    hignore     -- (only used when headers enabled) ignore header rows beginning
-                   with any elements in the hignore list. e.g. hignore=['# ', '[']
-                   means the following lines are skipped: '# qmax=10', '[defaults]'.
-    kwargs      -- keyword arguments that are passed to numpy.loadtxt including
-                   the following arguments below. (See also numpy.loadtxt for more
-                   details.)
-    delimiter   -- delimiter for the data in the block (default use whitespace).
-                   For comma-separated data blocks, set delimiter to ','.
-    usecols     -- zero-based index of columns to be loaded, by default use
-                   all detected columns. The reading skips data blocks that
-                   do not have the usecols-specified columns.
-    unpack      -- return data as a sequence of columns that allows tuple
-                   unpacking such as  x, y = loadData(FILENAME, unpack=True).
-                   Note transposing the loaded array as loadData(FILENAME).T
-                   has the same effect.
+    Parameters
+    ----------
+    filename
+        Name of the file we want to load data from.
+    minrows: int
+        Minimum number of rows in the first data block. All rows must have the same number of floating point values.
+    headers: bool
+     when False (defualt), the function returns a numpy array of the data in the data block.
+        When True, the function instead returns a dictionary of parameters and their corresponding values parsed from
+        header (information prior the data block). See hdel and hignore for options to help with parsing header
+        information.
+    hdel: str
+        (Only used when headers enabled.) Delimiter for parsing header information (default '='). e.g. using
+        default hdel, the line 'parameter = p_value' is put into the dictionary as {parameter: p_value}.
+    hignore: list
+        (Only used when headers enabled.) Ignore header rows beginning with any elements in hignore.
+        e.g. hignore=['# ', '['] causes the following lines to be skipped: '# qmax=10', '[defaults]'.
+    kwargs:
+        Keyword arguments that are passed to numpy.loadtxt including the following arguments below. (See
+        numpy.loadtxt for more details.) Only pass kwargs used by numpy.loadtxt.
 
-    Return a numpy array of the data (data_block). If headers enabled, instead returns a
-    dictionary of parameters read from the header (hddata).
+    Useful kwargs
+    =============
+    delimiter: str
+        Delimiter for the data in the block (default use whitespace). For comma-separated data blocks,
+        set delimiter to ','.
+    usecols:
+        Zero-based index of columns to be loaded, by default use all detected columns. The reading skips
+        data blocks that do not have the usecols-specified columns.
+    unpack: bool
+        Return data as a sequence of columns that allows tuple unpacking such as x, y =
+        loadData(FILENAME, unpack=True). Note transposing the loaded array as loadData(FILENAME).T has the same
+        effect.
+
+    Returns
+    -------
+    data_block: ndarray
+        A numpy array containing the found data block. (This is not returned if headers is enabled.)
+    hdata: dict
+        If headers are enabled, return a dictionary of parameters read from the header.
     """
     from numpy import array, loadtxt
     # for storing header data
@@ -156,18 +165,24 @@ def countcolumnsvalues(line):
 
 
 class TextDataLoader(object):
-    '''Smart loading of a text data with possibly multiple datasets.
-    '''
+    """Smart loading of a text data with possibly multiple datasets.
 
-    minrows = 10
-    usecols = None
-    skiprows = None
+    Parameters
+    ----------
+    minrows: int
+        Minimum number of rows in the first data block. (Default 10.)
+    usecols: tuple
+        Which columns in our dataset to use. Ignores all other columns. If None (default), use all columns.
+    skiprows
+        Rows in dataset to skip. (Currently not functional.)
+    """
 
-    def __init__(self, minrows=None, usecols=None, skiprows=None):
+    def __init__(self, minrows=10, usecols=None, skiprows=None):
         if minrows is not None:
             self.minrows = minrows
         if usecols is not None:
             self.usecols = tuple(usecols)
+        # FIXME: implement usage in _findDataBlocks
         if skiprows is not None:
             self.skiprows = skiprows
         # data items
@@ -194,12 +209,23 @@ def _resetvars(self):
 
 
     def read(self, filename):
+        """Open a file and run readfp.
+
+        Use if file is not already open for read byte.
+        """
         with open(filename, 'rb') as fp:
             self.readfp(fp)
         return
 
 
     def readfp(self, fp, append=False):
+        """Get file details.
+
+        File details include:
+         *  File name.
+         *  All data blocks findable by loadData.
+         *  Headers (if present) for each data block. (Generally the headers contain column name information).
+        """
         self._reset()
         # try to read lines from fp first
         self._lines = fp.readlines()

src/diffpy/utils/parsers/resample.py

@@ -17,17 +17,34 @@
 
 import numpy
 
+
 # NOTE - this should be faster than resample below and conforms more closely to
 # numpy.interp. I'm keeping resample for legacy reasons.
-def wsinterp(x, xp, fp, left = None, right = None):
+def wsinterp(x, xp, fp, left=None, right=None):
     """One-dimensional Whittaker-Shannon interpolation.
 
-    This uses the Whittaker-Shannon interpolation formula to interpolate the
-    value of fp (array), which is defined over xp (array), at x (array or
-    float).
-
-    Returns the interpolated array with dimensions of x.
-
+    This uses the Whittaker-Shannon interpolation formula to interpolate the value of fp (array), which is defined over
+    xp (array), at x (array or float).
+
+    Paramaters
+    ----------
+    x: ndarray
+        Desired range for interpolation.
+    xp: ndarray
+        Defined range for fp.
+    fp: ndarray
+        Function to be interpolated.
+    left: float
+        If given, set fp for x < xp[0] to left. Otherwise, if left is None (default) or not given, set fp for x < xp[0]
+        to fp evaluated at xp[-1].
+    right: float
+        If given, set fp for x > xp[-1] to right. Otherwise, if right is None (default) or not given, set fp for
+        x > xp[-1] to fp evaluated at xp[-1].
+
+    Returns
+    -------
+    ndarray:
+        Returns the interpolated array with dimensions of x.
     """
     scalar = numpy.isscalar(x)
     if scalar:
@@ -50,23 +67,30 @@ def wsinterp(x, xp, fp, left = None, right = None):
     fp_at_x[x > xp[-1]] = right
 
     # Return a float if we got a float
-    if scalar: return float(fp_at_x)
+    if scalar:
+        return float(fp_at_x)
 
     return fp_at_x
 
+
 def resample(r, s, dr):
     """Resample a PDF on a new grid.
 
-    This uses the Whittaker-Shannon interpolation formula to put s1 on a new
-    grid if dr is less than the sampling interval of r1, or linear
-    interpolation if dr is greater than the sampling interval of r1.
-
-    r       --  The r-grid used for s1
-    s       --  The signal to be resampled
-    dr      --  The new sampling interval
-
-    Returns resampled (r, s)
-
+    This uses the Whittaker-Shannon interpolation formula to put s1 on a new grid if dr is less than the sampling
+    interval of r1, or linear interpolation if dr is greater than the sampling interval of r1.
+
+    Parameters
+    ----------
+    r
+        The r-grid used for s1.
+    s
+        The signal to be resampled.
+    dr
+        The new sampling interval.
+
+    Returns
+    -------
+    Returns resampled (r, s).
     """
 
     dr0 = r[1] - r[0]

src/diffpy/utils/parsers/serialization.py

@@ -23,26 +23,34 @@
 
 
 def serialize_data(filename, hdata: dict, data_table: list, show_path=True, dt_colnames=None, serial_file=None):
-    """Serialize file data into a dictionary. Can also save dictionary into a serial language file.
-    Dictionary is formatted as {filename: data}.
-
-    Requires hdata and data_table generated from loadData.
-
-    filename        -- name of the file whose data is being serialized.
-    hdata          -- Dictionary of PDF metadata generated by loadData.
-    data_table      -- List storing  parsed by loadData.
-    dt_colnames     -- List containing names of each column in data_table. Every name in
-                       data_table_cols will be put into the Dictionary as a key with a value
-                       of that column in data_table (stored as a List). Put None for
-                       columns without names. If dt_cols has less non-None entries
-                       than columns in data_table, the pair {'data table': data_table} will be put
-                       in the dictionary. (Default None: only entry {'data table': data_table}
-                       will be added to dictionary.)
-    show_path       -- include a path element in the database entry (default True).
-                       If 'path' is not included in hddata, extract path from filename.
-    serial_file     -- serial language file to dump dictionary into.
-
-    Returns the dictionary loaded from/into the updated database file.
+    """Serialize file data into a dictionary. Can also save dictionary into a serial language file. Dictionary is
+    formatted as {filename: data}.
+
+    Requires hdata and data_table (can be generated by loadData).
+
+    Parameters
+    ----------
+    filename
+        Name of the file whose data is being serialized.
+    hdata: dict
+        File metadata (generally related to data table).
+    data_table: list
+        Data table.
+    dt_colnames: list
+        Names of each column in data_table. Every name in data_table_cols will be put into the Dictionary as a key with
+        a value of that column in data_table (stored as a List). Put None for columns without names. If dt_cols has less
+        non-None entries than columns in data_table, the pair {'data table': data_table} will be put in the dictionary.
+        (Default None: only entry {'data table': data_table} will be added to dictionary.)
+    show_path: bool
+        include a path element in the database entry (default True). If 'path' is not included in hddata, extract path
+        from filename.
+    serial_file
+        Serial language file to dump dictionary into. If None (defualt), no dumping will occur.
+
+    Returns
+    -------
+    dict:
+        Returns the dictionary loaded from/into the updated database file.
     """
 
     # compile data_table and hddata together
@@ -131,9 +139,15 @@ def serialize_data(filename, hdata: dict, data_table: list, show_path=True, dt_c
 def deserialize_data(filename):
     """Load a dictionary from a serial file.
 
-    filename    -- database file to load from.
+    Parameters
+    ----------
+    filename
+        Serial file to load from.
 
-    Returns a dictionary of database information.
+    Returns
+    -------
+    dict
+        A dictionary read from a serial file.
     """
 
     # check if supported type

src/diffpy/utils/wx/__init__.py

@@ -14,8 +14,6 @@
 ##############################################################################
 
 """Utilities related wx Python GUIs.
-
-gridutils    -- selection management in wx.grid.Grid
 """
 
 # End of file