diffpy.utils 3.6.1rc1__py3-none-any.whl → 3.7.0rc0__py3-none-any.whl

diffpy/utils/parsers/loaddata.py

@@ -13,15 +13,205 @@
 #
 ##############################################################################
 
-import os
+from pathlib import Path
 
 import numpy
 
 from diffpy.utils import validators
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
 
+base = "diffpy.utils.parsers.loaddata"
+removal_version = "4.0.0"
 
+loaddata_deprecation_msg = build_deprecation_message(
+    base,
+    "loadData",
+    "load_data",
+    removal_version,
+    new_base="diffpy.utils.parsers",
+)
+
+
+@deprecated(loaddata_deprecation_msg)
 def loadData(
     filename, minrows=10, headers=False, hdel="=", hignore=None, **kwargs
+):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.utils.parsers.load_data instead.
+    """
+    return load_data(filename, minrows, headers, hdel, hignore, **kwargs)
+
+
+class TextDataLoader(object):
+    """Smart loading of a text data with possibly multiple datasets.
+
+    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=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
+        self._reset()
+        return
+
+    def _reset(self):
+        self.filename = ""
+        self.headers = []
+        self.datasets = []
+        self._resetvars()
+        return
+
+    def _resetvars(self):
+        self._filename = ""
+        self._lines = None
+        self._splitlines = None
+        self._words = None
+        self._linerecs = None
+        self._wordrecs = None
+        return
+
+    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 load_data.
+         *  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()
+        # and if good, assign filename
+        self.filename = getattr(fp, "name", "")
+        self._words = "".join(self._lines).split()
+        self._splitlines = [line.split() for line in self._lines]
+        self._findDataBlocks()
+        return
+
+    def _findDataBlocks(self):
+        mincols = 1
+        if self.usecols is not None and len(self.usecols):
+            mincols = max(mincols, max(self.usecols) + 1)
+            mincols = max(mincols, abs(min(self.usecols)))
+        nlines = len(self._lines)
+        nwords = len(self._words)
+        # idx - line index, nw0, nw1 - index of the first and last word,
+        # nf - number of words, ok - has data
+        self._linerecs = numpy.recarray(
+            (nlines,),
+            dtype=[
+                ("idx", int),
+                ("nw0", int),
+                ("nw1", int),
+                ("nf", int),
+                ("ok", bool),
+            ],
+        )
+        lr = self._linerecs
+        lr.idx = numpy.arange(nlines)
+        lr.nf = [len(sl) for sl in self._splitlines]
+        lr.nw1 = lr.nf.cumsum()
+        lr.nw0 = lr.nw1 - lr.nf
+        lr.ok = True
+        # word records
+        lw = self._wordrecs = numpy.recarray(
+            (nwords,),
+            dtype=[
+                ("idx", int),
+                ("line", int),
+                ("col", int),
+                ("ok", bool),
+                ("value", float),
+            ],
+        )
+        lw.idx = numpy.arange(nwords)
+        n1 = numpy.zeros(nwords, dtype=bool)
+        n1[lr.nw1[:-1]] = True
+        lw.line = n1.cumsum()
+        lw.col = lw.idx - lr.nw0[lw.line]
+        lw.ok = True
+        values = nwords * [0.0]
+        for i, w in enumerate(self._words):
+            try:
+                values[i] = float(w)
+            except ValueError:
+                lw.ok[i] = False
+        # prune lines that have a non-float values:
+        lw.values = values
+        if self.usecols is None:
+            badlines = lw.line[~lw.ok]
+            lr.ok[badlines] = False
+        else:
+            for col in self.usecols:
+                badlines = lw.line[(lw.col == col) & ~lw.ok]
+                lr.ok[badlines] = False
+        lr1 = lr[lr.nf >= mincols]
+        okb = numpy.r_[lr1.ok[:1], lr1.ok[1:] & ~lr1.ok[:-1], False]
+        oke = numpy.r_[False, ~lr1.ok[1:] & lr1.ok[:-1], lr1.ok[-1:]]
+        blockb = numpy.r_[True, lr1.nf[1:] != lr1.nf[:-1], False]
+        blocke = numpy.r_[False, blockb[1:-1], True]
+        beg = numpy.nonzero(okb | blockb)[0]
+        end = numpy.nonzero(oke | blocke)[0]
+        rowcounts = end - beg
+        assert not numpy.any(rowcounts < 0)
+        goodrows = rowcounts >= self.minrows
+        begend = numpy.transpose([beg, end - 1])[goodrows]
+        hbeg = 0
+        for dbeg, dend in begend:
+            bb1 = lr1[dbeg]
+            ee1 = lr1[dend]
+            hend = bb1.idx
+            header = "".join(self._lines[hbeg:hend])
+            hbeg = ee1.idx + 1
+            if self.usecols is None:
+                data = numpy.reshape(lw.value[bb1.nw0 : ee1.nw1], (-1, bb1.nf))
+            else:
+                tdata = numpy.empty(
+                    (len(self.usecols), dend - dbeg), dtype=float
+                )
+                for j, trow in zip(self.usecols, tdata):
+                    j %= bb1.nf
+                    trow[:] = lw.value[bb1.nw0 + j : ee1.nw1 : bb1.nf]
+                data = tdata.transpose()
+            self.headers.append(header)
+            self.datasets.append(data)
+        # finish reading to a last header and empty dataset
+        if hbeg < len(self._lines):
+            header = "".join(self._lines[hbeg:])
+            data = numpy.empty(0, dtype=float)
+            self.headers.append(header)
+            self.datasets.append(data)
+        return
+
+
+def load_data(
+    filename, minrows=10, headers=False, hdel="=", hignore=None, **kwargs
 ):
     """Find and load data from a text file.
 
@@ -31,7 +221,7 @@ def loadData(
 
     Parameters
     ----------
-    filename
+    filename: Path or string
         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
@@ -66,8 +256,8 @@ def loadData(
         comma-separated data blocks, set delimiter to ','.
     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.
+        as x, y = load_data(FILENAME, unpack=True). Note transposing the
+        loaded array as load_data(FILENAME).T has the same effect.
     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-
@@ -115,10 +305,11 @@ def loadData(
         return nc, nv
 
     # Check if file exists before trying to open
-    if not os.path.exists(filename):
+    filename = Path(filename)
+    if not filename.is_file():
         raise IOError(
             (
-                f"File {filename} cannot be found. "
+                f"File {str(filename)} cannot be found. "
                 "Please rerun the program specifying a valid filename."
             )
         )
@@ -196,169 +387,3 @@ def loadData(
             kwargs.setdefault("usecols", list(range(ncvblock[0])))
             data_block = loadtxt(fid, **kwargs)
     return data_block
-
-
-class TextDataLoader(object):
-    """Smart loading of a text data with possibly multiple datasets.
-
-    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=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
-        self._reset()
-        return
-
-    def _reset(self):
-        self.filename = ""
-        self.headers = []
-        self.datasets = []
-        self._resetvars()
-        return
-
-    def _resetvars(self):
-        self._filename = ""
-        self._lines = None
-        self._splitlines = None
-        self._words = None
-        self._linerecs = None
-        self._wordrecs = None
-        return
-
-    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()
-        # and if good, assign filename
-        self.filename = getattr(fp, "name", "")
-        self._words = "".join(self._lines).split()
-        self._splitlines = [line.split() for line in self._lines]
-        self._findDataBlocks()
-        return
-
-    def _findDataBlocks(self):
-        mincols = 1
-        if self.usecols is not None and len(self.usecols):
-            mincols = max(mincols, max(self.usecols) + 1)
-            mincols = max(mincols, abs(min(self.usecols)))
-        nlines = len(self._lines)
-        nwords = len(self._words)
-        # idx - line index, nw0, nw1 - index of the first and last word,
-        # nf - number of words, ok - has data
-        self._linerecs = numpy.recarray(
-            (nlines,),
-            dtype=[
-                ("idx", int),
-                ("nw0", int),
-                ("nw1", int),
-                ("nf", int),
-                ("ok", bool),
-            ],
-        )
-        lr = self._linerecs
-        lr.idx = numpy.arange(nlines)
-        lr.nf = [len(sl) for sl in self._splitlines]
-        lr.nw1 = lr.nf.cumsum()
-        lr.nw0 = lr.nw1 - lr.nf
-        lr.ok = True
-        # word records
-        lw = self._wordrecs = numpy.recarray(
-            (nwords,),
-            dtype=[
-                ("idx", int),
-                ("line", int),
-                ("col", int),
-                ("ok", bool),
-                ("value", float),
-            ],
-        )
-        lw.idx = numpy.arange(nwords)
-        n1 = numpy.zeros(nwords, dtype=bool)
-        n1[lr.nw1[:-1]] = True
-        lw.line = n1.cumsum()
-        lw.col = lw.idx - lr.nw0[lw.line]
-        lw.ok = True
-        values = nwords * [0.0]
-        for i, w in enumerate(self._words):
-            try:
-                values[i] = float(w)
-            except ValueError:
-                lw.ok[i] = False
-        # prune lines that have a non-float values:
-        lw.values = values
-        if self.usecols is None:
-            badlines = lw.line[~lw.ok]
-            lr.ok[badlines] = False
-        else:
-            for col in self.usecols:
-                badlines = lw.line[(lw.col == col) & ~lw.ok]
-                lr.ok[badlines] = False
-        lr1 = lr[lr.nf >= mincols]
-        okb = numpy.r_[lr1.ok[:1], lr1.ok[1:] & ~lr1.ok[:-1], False]
-        oke = numpy.r_[False, ~lr1.ok[1:] & lr1.ok[:-1], lr1.ok[-1:]]
-        blockb = numpy.r_[True, lr1.nf[1:] != lr1.nf[:-1], False]
-        blocke = numpy.r_[False, blockb[1:-1], True]
-        beg = numpy.nonzero(okb | blockb)[0]
-        end = numpy.nonzero(oke | blocke)[0]
-        rowcounts = end - beg
-        assert not numpy.any(rowcounts < 0)
-        goodrows = rowcounts >= self.minrows
-        begend = numpy.transpose([beg, end - 1])[goodrows]
-        hbeg = 0
-        for dbeg, dend in begend:
-            bb1 = lr1[dbeg]
-            ee1 = lr1[dend]
-            hend = bb1.idx
-            header = "".join(self._lines[hbeg:hend])
-            hbeg = ee1.idx + 1
-            if self.usecols is None:
-                data = numpy.reshape(lw.value[bb1.nw0 : ee1.nw1], (-1, bb1.nf))
-            else:
-                tdata = numpy.empty(
-                    (len(self.usecols), dend - dbeg), dtype=float
-                )
-                for j, trow in zip(self.usecols, tdata):
-                    j %= bb1.nf
-                    trow[:] = lw.value[bb1.nw0 + j : ee1.nw1 : bb1.nf]
-                data = tdata.transpose()
-            self.headers.append(header)
-            self.datasets.append(data)
-        # finish reading to a last header and empty dataset
-        if hbeg < len(self._lines):
-            header = "".join(self._lines[hbeg:])
-            data = numpy.empty(0, dtype=float)
-            self.headers.append(header)
-            self.datasets.append(data)
-        return

diffpy/utils/parsers/serialization.py

@@ -33,10 +33,11 @@ def serialize_data(
     show_path=True,
     serial_file=None,
 ):
-    """Serialize file data into a dictionary. Can also save dictionary into a
-    serial language file. Dictionary is formatted as {filename: data}.
+    """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).
+    Requires hdata and data_table (can be generated by load_data).
 
     Parameters
     ----------

diffpy/utils/resampler.py

@@ -30,15 +30,15 @@ def wsinterp(x, xp, fp, left=None, right=None):
 
     Parameters
     ----------
-    x: ndarray
+    x: ``ndarray``
         The x values at which interpolation is computed.
-    xp: ndarray
+    xp: ``ndarray``
         The array of known x values.
-    fp: ndarray
+    fp: ``ndarray``
         The array of y values associated with xp.
     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].
+        (default) or not given, set fp for x < xp[0] to fp evaluated at xp[0].
     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
@@ -46,7 +46,7 @@ def wsinterp(x, xp, fp, left=None, right=None):
 
     Returns
     -------
-    ndarray or float
+    ``ndarray`` or float
         The interpolated values at points x. Returns a single float if x is a
         scalar, otherwise returns a numpy.ndarray.
     """
@@ -80,8 +80,8 @@ def wsinterp(x, xp, fp, left=None, right=None):
 
 
 def nsinterp(xp, fp, qmin=0, qmax=25, left=None, right=None):
-    """One-dimensional Whittaker-Shannon interpolation onto the Nyquist-Shannon
-    grid.
+    """One-dimensional Whittaker-Shannon interpolation onto the Nyquist-
+    Shannon grid.
 
     Takes a band-limited function fp and original grid xp and resamples fp on
     the NS grid. Uses the minimum number of points N required by the Nyquist
@@ -91,9 +91,9 @@ def nsinterp(xp, fp, qmin=0, qmax=25, left=None, right=None):
 
     Parameters
     ----------
-    xp: ndarray
+    xp: ``ndarray``
         The array of known x values.
-    fp: ndarray
+    fp: ``ndarray``
         The array of y values associated with xp.
     qmin: float
         The lower band limit in the frequency domain.
@@ -102,7 +102,7 @@ def nsinterp(xp, fp, qmin=0, qmax=25, left=None, right=None):
 
     Returns
     -------
-    x: ndarray
+    x: ``ndarray``
         The Nyquist-Shannon grid computed for the given qmin and qmax.
     fp_at_x: ndarray
         The interpolated values at points x. Returns a single float if x is a
@@ -139,7 +139,7 @@ def resample(r, s, dr):
 
     Returns
     -------
-    Returns resampled (r, s).
+    Returns resampled ``(r, s)``.
     """
 
     warnings.warn(