Updated documentation.

README.rst

@@ -76,6 +76,7 @@ issue`_.
 
 .. _open an issue: https://github.com/m3wolf/xanespy/issues
 
+- 32-ID-C - Advanced Photon Source
 - 8-BM-B - Advanced Photon Source
 - 6-2c - Stanford Synchrotron Radiation Lightsource
 - 5.3.2.1 - Advanced Light Source (ptychography)
@@ -89,15 +90,6 @@ Xanespy has support for ptychography data from ALS beamline
 files and ``xanespy.PtychoFrameset`` to load the data.
 
 
-Extended X-ray Absorbance Fine Structure (EXAFS)
-------------------------------------------------
-
-Currently EXAFS analysis is NOT supported. While it would be nice to
-someday include this, this technique generally requires heavy user
-involvement and does not lend itself to batch processing; if you have
-expertise in automated analysis of EXAFS data, please get in touch.
-
-
 License
 -------
 

VERSION

@@ -1 +1 @@
-0.1.6
+0.1.7

docs/analysis.rst

@@ -52,12 +52,15 @@ Forking the Data
 ================
 
 After long computations it can be helpful to create a copy of the
-dataset as a sort of checkpoint. To enable this, xanespy includes the
-``fork_data_group()`` method: it creates a copy of the HDF group. The
-active set can be changed by setting the ``data_name`` attribute on a
-``XanesFrameset`` object. Most operations enabled by the
-``XanesFrameset()`` class are not idempotent, so starting from a clean
-dataset may be necessary:
+dataset as a sort of checkpoint. To enable this, the
+:py:class:`xanespy.xanes_frameset.XanesFrameset` class includes the
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.fork_data_group()`
+method: it creates a copy of the HDF group. The active set can be
+changed by setting the ``data_name`` attribute on a
+:py:class:`~xanespy.xanes_frameset.XanesFrameset()` object. Most
+operations enabled by the
+:py:class:`~xanespy.xanes_frameset.XanesFrameset` class are not
+idempotent, so starting from a clean dataset may be necessary:
 
 .. code:: python
 
@@ -93,7 +96,11 @@ damage and imperfect microscope alignment can all cause frames to be
 misaligned. **It is often necessary to align the frames before
 performing any of the subsequent steps.**
 
-This is done with the ``xanespy.XanesFrameset().align_frames()`` method::
+This is done with the
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.align_frames()`
+method:
+
+.. code:: python
 
   import xanespy
   # Select an imported hdf file to use
@@ -113,12 +120,17 @@ The alignments are generally done with subpixel resolution, which
 gives improved accuracy, but requires interpolation. To avoid problems
 with accumulated error, a cumulative translation matrix is kept and
 applied at the end to the original data. You can add your own
-translation manually using the ``stage_transformations()`` method. If
-``align_frames()`` is called with ``commit=False``, then the alignment
-parameters are added to ``stage_transformations`` but not
-applied. Once all transformations are staged, the
-``apply_transformations()`` method will apply the cumulative
-transformation matrix and (by default) save the result to disk.
+translation manually using the
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.stage_transformations()`
+method. If
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.align_frames()` is
+called with ``commit=False``, then the alignment parameters are added
+to
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.stage_transformations()`
+but not applied. Once all transformations are staged, the
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.apply_transformations()`
+method will apply the cumulative transformation matrix and (by
+default) save the result to disk.
 
 If the starting alignment is particularly sporadic, a false minimum
 can result in an exception or a very small image that doesn't provide
@@ -148,11 +160,11 @@ Filter When Importing
 ---------------------
 
 Area detectors often have some number of **bad pixels**, either hot
-pixels or dead pixels. Applying a mild median filter during import
-time to the raw data can fix most of these problems. Some beamline
-importers apply this by default. The **3D filter** can also include
-the energy dimension, but this is not recommended since the frames
-haven't been aligned yet:
+pixels or dead pixels. Applying a mild median filter when using one of
+the importers in :py:mod:`xanespy.importers`, the raw data can fix
+most of these problems. Some beamline importers apply this by
+default. The **3D filter** can also include the energy dimension, but
+this is not recommended since the frames haven't been aligned yet:
 
 .. code:: python
 
@@ -164,10 +176,12 @@ haven't been aligned yet:
 Filter When Aligning
 --------------------
 
-When aligning frames it may be helpful to apply an **aggressive median
-filter to blur each image** before registration so that noise and fine
-details have less impact. This **2D filter** is only applied to the
-images in memory, so does not apply to the final result.
+When aligning frames with
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.align_frames()`, it
+may be helpful to apply an **aggressive median filter to blur each
+image** before registration so that noise and fine details have less
+impact. This **2D filter** is only applied to the images in memory, so
+does not apply to the final result.
 
 .. code:: python
 
@@ -180,10 +194,12 @@ Filter After Aligning
 ---------------------
 
 Depending on the scientific question being addressed, a **final median
-filter after aligning** maybe desireable. This **4D filter** provides
-a trade-off between temporal, spatial and energy resolutions: The
-larger the kernel along one dimension, the less resolution you'll be
-able to see but the higher the signal-to-noise in the other
+filter after aligning** maybe desireable. This **4D filter**, applied
+with
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.apply_median_filter()`,
+provides a trade-off between temporal, spatial and energy resolutions:
+The larger the kernel along one dimension, the less resolution you'll
+be able to see but the higher the signal-to-noise in the other
 dimensions.
 
 .. code:: python
@@ -199,17 +215,23 @@ dimensions.
 Subtracting Surroundings
 ========================
 
-Some microscopes show differences in the absorbance of the whole
-frame, including background material. This can be removed from each
-frame, giving a better spectrum::
+Sometimes there are differences in the absorbance of the whole frame,
+including background material. This can be removed from each frame
+using
+:py:meth:`~xanespy.xanes_frameset.XanesFrameset.subtract_surroundings`,
+giving a better spectrum:
 
+.. code:: python
+  	  
   fs = XanesFrameset(hdf_filename="...")
   fs.subtract_surroundings()
 
 .. figure:: images/subtract-surroundings.svg
    :alt: Spectrum showing before and after subtract_surroundings
 
-   The effect of the ``subtract_surroundings()`` method.
+   The effect of the
+   :py:meth:`~xanespy.xanes_frameset.XanesFrameset.subtract_surroundings()`
+   method.
 
 Calculating Maps
 ================

docs/conf.py

@@ -16,7 +16,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+
 import os
 import sys
 sys.path.insert(0, os.path.abspath('../'))
@@ -65,7 +65,7 @@ def read(fname):
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = read("VERSION")
 # The full version, including alpha/beta/rc tags.
 release = read("VERSION")
 

docs/fitting.rst

@@ -5,12 +5,13 @@ Fitting X-ray Absorbance Spectra
 
 When numerical methods are insufficient, it may be necessary to fit
 the pixel spectra with a model function and extract parameters from
-the model. The core `~xanespy.xanes_frameset.XanesFrameset` class has
-methods for common fitting-related use-cases, such as using curves to
-approximate L_3 and K edges, and linear combination fitting of
-standard spectra. If the pre-rolled options are not enough, arbitary
-callables can be created and fit against the data. The following is an
-example for fitting a single L-edge spectrum:
+the model. The core :py:class:`~xanespy.xanes_frameset.XanesFrameset`
+class has methods for common fitting-related use-cases, such as using
+curves to approximate L\ :sub:`3` and K edges, and linear
+combination fitting of standard spectra. If the pre-rolled options are
+not enough, arbitary callables can be created and fit against the
+data. The following is an example for fitting a single L-edge
+spectrum:
 
 .. code:: python
 
@@ -75,8 +76,8 @@ The naming prefix can be controlled by passing the ``name`` parameter
 to
 :py:func:`~xanespy.xanes_frameset.XanesFrameset.fit_linear_combinations`
 method. If more control is needed, the
-:py:class:`xanespy.fitting.LinearCombination` can be subclassed and
-given to the
+:py:class:`xanespy.fitting.LinearCombination` class can be subclassed
+and given to the
 :py:meth:`~xanespy.xanes_frameset.XanesFrameset.fit_spectra` method as
 described :ref:`below<roll-your-own>`.
 

docs/importing.rst

@@ -25,7 +25,7 @@ The camera at the beamline captures micrographs of 2048x2448. In most
 cases this is over-kill since the focusing power of the 60 nm
 zone-plate is not strong enough to take advantage of this. The extra
 pixel density can be converted into an improved contrast-to-noise
-ratio by the **``downsample``** parameter. This parameter controls how
+ratio by the ``downsample`` parameter. This parameter controls how
 many pixels (to a power of two) are combined. In the previous example,
 ``downsample=1`` combines to :math:`2^1 = 2\times2` blocks and results
 in a (1024, 1224) image. ``downsample=2`` combines :math:`2^2 =
@@ -41,7 +41,9 @@ discarding the corner artifacts.
  the above approach would continually overwrite the imported data,
  leaving only the last scan in the import data store. To overcome
  this, the ``timestep`` and ``total_timesteps`` parameters should be
- used, or the related ``import_aps32idc_xanes_files`` function.
+ used with :py:func:`~xanespy.importers.import_aps32idc_xanes_file`,
+ or the related
+ :py:func:`~xanespy.importers.import_aps32idc_xanes_files` function.
 
 Option 1: Loop through the files explicitly:
 

docs/xanespy.rst

@@ -28,6 +28,15 @@ xanespy.exceptions module
     :undoc-members:
     :show-inheritance:
 
+xanespy.fitting module
+-------------------------
+
+.. automodule:: xanespy.fitting
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 xanespy.importers module
 ------------------------
 

requirements-docs.txt

@@ -0,0 +1,14 @@
+numpy>=1.13.3
+h5py>=2.6
+matplotlib>=2.1
+pandas>=0.19.1
+pillow>=3.4.2
+olefile>=0.44
+PyQt5>=5.7
+pytz>=2016.10
+scikit-image>=0.12.3
+scikit-learn>=0.18.1
+scipy>=0.18.1
+tqdm>=4.10.0
+jinja2
+imageio

xanespy/fitting.py

@@ -33,6 +33,10 @@
 from utilities import prog
 
 
+__all__ = ('prepare_p0', 'fit_spectra', 'Curve', 'Line',
+           'LinearCombination', 'Gaussian', 'L3Curve', 'KCurve')
+
+
 def prepare_p0(p0, frame_shape, num_timesteps=1):
     """Create an initial parameter guess for fitting.
     
@@ -225,8 +229,8 @@ class Gaussian(Curve):
     Mathematically:
     
     .. math::
-        a e^{\frac{-(x-b)**2}{2c^2)}
-    
+        y = a e^{\\frac{-(x-b)**2}{2c^2}}
+
     Parameters
     ----------
     x : np.ndarray
@@ -246,7 +250,6 @@ def __call__(self, height, center, width):
 
 
 class L3Curve(Curve):
-
     """An L_3 absorption edge.
     
     This function is a combination of two Gaussian peaks and a step
@@ -305,8 +308,8 @@ def param_names(self):
 class KCurve(Curve):
     """A K absorption edge.
     
-    Fit Parameters
-    --------------
+    **Fit Parameters:**
+    
     scale
       Overall scale factor for curve
     voffset

xanespy/xanes_frameset.py

@@ -492,11 +492,6 @@ def apply_transformations(self, crop=True, commit=True, quiet=False):
         and apply them. If commit is truthy, the staged
         transformations are reset.
         
-        Returns
-        -------
-        out : np.ndarray
-          Transformed array of the optical depth frames.
-        
         Arguments
         ---------
         crop : bool, optional
@@ -511,6 +506,11 @@ def apply_transformations(self, crop=True, commit=True, quiet=False):
         quiet : bool, optional
           Whether to suppress the progress bar, etc.
         
+        Returns
+        -------
+        out : np.ndarray
+          Transformed array of the optical depth frames.
+        
         """
         # First, see if there's anything to do
         if self._transformations is None:
@@ -1784,7 +1784,7 @@ def subtract_surroundings(self, sensitivity: float=1.):
         subtract the average surrounding optical_depth from each
         frame. This effectively removes effects where the entire frame
         is brighter from one energy to the next.
-
+        
         Parameters
         ----------
         sensitivity : optional