From 1df434357600bcae9d11f20a3062cb915704979a Mon Sep 17 00:00:00 2001
From: Blaise Thompson <blaise@untzag.com>
Date: Sun, 15 Apr 2018 22:54:59 -0500
Subject: 2018-04-15 22:54

---
 processing/chapter.tex | 154 +++++++++++++++++++++++++------------------------
 1 file changed, 80 insertions(+), 74 deletions(-)

(limited to 'processing/chapter.tex')

diff --git a/processing/chapter.tex b/processing/chapter.tex
index 0d2e6ae..0d89055 100644
--- a/processing/chapter.tex
+++ b/processing/chapter.tex
@@ -307,7 +307,7 @@ These are the principle multidimensional array containers, and each instance of
 corresponds to exactly one multidimensional array.  %
 These two classes share a large amount of functionality, and they both inherit from the parent
 WrightTools \python{Dataset} class, which itself is a child of \python{h5py.Dataset}.  %
-See section ... to understand the concept of inheritance.  %
+See \autoref{sof:sec:oop} to understand the concept of inheritance.  %
 
 % TODO: consider demonstrating slicing
 
@@ -324,7 +324,8 @@ with the null idea.  %
 
 These classes also have basic mathematical manipulation methods, such as \python{log},
 \python{normalize}, and \python{symmetric_sqrt}.  %
-Other operations are supported by in-place operations, as described in section ....  %
+Other operations are supported by in-place operations, as described in
+\autoref{pro:sec:in_place}.  %
 
 Channels and variables inherit from h5py, so they support partial access through slicing
 (\python{__getitem__} syntax).  %
@@ -345,26 +346,26 @@ array.  %
     \texttt{chunkwise} & method & both & Execute a function for each chunk in the dataset. \\ \hline
     \texttt{clip} & method & both & Clip values outside of a desired range. \\ \hline
     \texttt{convert} & method & both & Convert units, writing to disk. \\ \hline
-    \texttt{full} & attribute & both & \\ \hline
-    \texttt{fullpath} & attribute & both & \\ \hline
-    \texttt{label} & attribute & variable & \\ \hline
+    \texttt{full} & attribute & both & Content array expanded to full shape. \\ \hline
+    \texttt{fullpath} & attribute & both & External and internal path to dataset. \\ \hline
+    \texttt{label} & attribute & variable & Label to appear in subscript. \\ \hline
     \texttt{log} & method & both & Take the log of the entire dataset, with choice of base. \\ \hline
     \texttt{log10} & method & both & Take the base 10 log of the entire dataset. \\ \hline
     \texttt{log2} & method & both & Take the base 2 log of the entire dataset. \\ \hline
-    \texttt{mag} & method & channel & \\ \hline
-    \texttt{major\_extent} & attribute & channel & \\ \hline
+    \texttt{mag} & method & channel & Alias for \texttt{major\_extent}. \\ \hline
+    \texttt{major\_extent} & attribute & channel & Maximum deviation from null. \\ \hline
     \texttt{max} & method & both & Maximum, ignoring nans. \\ \hline
     \texttt{min} & method & both & Minimum, ignoring nans. \\ \hline
-    \texttt{minor\_extent} & attribute & channel & \\ \hline
-    \texttt{natural\_name} & attribute & both & \\ \hline
-    \texttt{normalize} & method & channel & \\ \hline
-    \texttt{null} & attribute & channel & \\ \hline
-    \texttt{parent} & attribute & both & \\ \hline
-    \texttt{points} & attribute & both & \\ \hline
-    \texttt{signed} & attribute & channel & \\ \hline
+    \texttt{minor\_extent} & attribute & channel & Minimum deviation from null. \\ \hline
+    \texttt{natural\_name} & attribute & both & Natural name. \\ \hline
+    \texttt{normalize} & method & channel & Zero out znull, divide such that mag is 1. \\ \hline
+    \texttt{null} & attribute & channel & Null value. \\ \hline
+    \texttt{parent} & attribute & both & Parent data object. \\ \hline
+    \texttt{points} & attribute & both & Squeezed content array. \\ \hline
+    \texttt{signed} & attribute & channel & Flag to indicate data is signed. \\ \hline
     \texttt{slices} & method & both & Returns a generator yielding tuple of slice objects. \\ \hline
-    \texttt{symmetric\_root} & method & both & \\ \hline
-    \texttt{trim} & method & channel & \\ \hline
+    \texttt{symmetric\_root} & method & both & Take the root, propagating sign. \\ \hline
+    \texttt{trim} & method & channel & Remove outliers using statistical tests. \\ \hline
   \end{tabular}
   \caption[Attributes and methods of Channel and Variable.]{
     Key attributes and methods of channel and variable, lexicographically listed
@@ -393,23 +394,23 @@ In fact, axes must have the same dimensionality as their parent \python{Data}.
 The loosening of the one-dimensional axis requirement is what makes WrightTools data not fully
 structured, but ``semi-structured''.
 
-Section ... decribes the \python{Axis} class in greater detail.  %
+Section \ref{pro:sec:axes} decribes the \python{Axis} class in greater detail.  %
 
 \begin{table}
   \begin{tabular}{c | c | l}
     & type & description \\ \hline
-    \texttt{full} & & \\ \hline
-    \texttt{label} & & \\ \hline
-    \texttt{natural\_name} & & \\ \hline
-    \texttt{ndim} & & \\ \hline
-    \texttt{points} & & \\ \hline
-    \texttt{shape} & & \\ \hline
-    \texttt{size} & & \\ \hline
-    \texttt{units\_kind} & & \\ \hline
-    \texttt{variables} & & \\ \hline
-    \texttt{convert} & & \\ \hline
-    \texttt{min} & & \\ \hline
-    \texttt{max} & & \\ \hline
+    \texttt{full} & attribute & Content array expanded to full shape. \\ \hline
+    \texttt{label} & attribute & Label to appear in subscript. \\ \hline
+    \texttt{natural\_name} & attribute & Natural name. \\ \hline
+    \texttt{ndim} & attribute & Number of dimensions. \\ \hline
+    \texttt{points} & attribute & Squeezed content array. \\ \hline
+    \texttt{shape} & attribute & Shape of axis. \\ \hline
+    \texttt{size} & attribute & Number of pixels in axis. \\ \hline
+    \texttt{units} & attrbute & Units of axis. \\ \hline
+    \texttt{variables} & attribute & List of variables owned by axis. \\ \hline
+    \texttt{convert} & method & Convert the axis to a different set of units. \\ \hline
+    \texttt{min} & method & Get the axis minimum. \\ \hline
+    \texttt{max} & method & Get the axis maximum. \\ \hline
   \end{tabular}
   \caption[Attributes and methods of Axis.]{
     Key attributes and methods of axis, lexicographically listed
@@ -435,7 +436,7 @@ data sources can simply add one function to unlock the capabilities of the entir
 applied to their data.  %
 
 \autoref{pro:tab:from_functions} contains the currently supported from functions in
-WrightTools...  %
+WrightTools.  %
 
 \subsubsection{Discover dimensions}
 
@@ -497,13 +498,14 @@ WrightTools.  %
 \begin{table}
   \begin{tabular}{c | l}
     function & data source \\ \hline
-    \texttt{wt.collection.from\_CARY} & TODO \\ \hline
-    \texttt{wt.data.from\_COLORS} & TODO \\ \hline
-    \texttt{wt.data.from\_KENT} & TODO \\ \hline
-    \texttt{wt.data.from\_PyCMDS} & TODO \\ \hline
-    \texttt{wt.data.from\_OceanOptics} & TODO \\ \hline
-    \texttt{wt.data.from\_shimamdzu} & TODO \\ \hline
-    \texttt{wt.data.from\_Tensor27} & TODO \\ \hline
+    \texttt{wt.collection.from\_CARY} & Cary brand spectrometers. \\ \hline
+    \texttt{wt.data.from\_COLORS} & COLORS. \cite{KainSchuyler2017a} \\ \hline
+    \texttt{wt.data.from\_JASCO} & JASCO brand spectrometers \\ \hline
+    \texttt{wt.data.from\_KENT} & ps\_control. \cite{MeyerKentA2004a} \\ \hline
+    \texttt{wt.data.from\_PyCMDS} & PyCMDS (\autoref{cha:acq}). \\ \hline
+    \texttt{wt.data.from\_OceanOptics} & Ocean Optics brand spectrometers. \\ \hline
+    \texttt{wt.data.from\_shimamdzu} & Shimadzu brand spectrometers. \\ \hline
+    \texttt{wt.data.from\_Tensor27} & Tensor 27 FT-IR. \\ \hline
   \end{tabular}
   \caption[CAPTION TODO]{
     CAPTION TODO
@@ -600,6 +602,34 @@ There are better and worse choices of colormap... % TODO: elaborate
 
 \subsubsection{Colormap}
 
+\autoref{pro:fig:cmaps} shows the red, green, and blue components of four different colormaps.  %
+The black line is the net brightness of each color (larger value means lighter color).  %
+Below each figure is a gray-scale representation of the corresponding colormap.  %
+The r, g, and b components are scaled according to human perception.  % TODO: values, from where
+The traditional Wright Group colormap (derived from jet) is shown first.  %
+Following are two perceptual colormaps, cubehelix from \texcite{GreenDA2009a}, and viridis, the new
+matplotlib default.
+WrightTools uses the algorithm from \textcite{GreenDA2009a} to define a custom cubehelix colormap
+with good perceptual properties and familiar Wright Group coloration.  %
+
+\subsubsection{Interpolation type}
+
+WrightTools data is defined at discrete points, but an entire 2D surface must be defined in order
+to make a full colored surface.  %
+Defining this surface requires \emph{interpolation}, and there are various strategies that have
+different advantages and disadvantages.  %
+Choosing the wrong type of interpolation can be misleading.  %
+
+\autoref{pro:fig:fill_types} represents different kinds of plot-type interpolation.  %
+Each is labeled according to the corresponding matplotlib method call.  %
+In the multidimensional spectroscopy community, the most popular form of interpolation is
+``contourf'' and ``contour'', both based on Delaunay triangulation.  %
+In \autoref{pro:fig:fill_types} the edges of the Delaunay triangles are drawn for clarity.  %
+Such interpolation methods result in \emph{smoother} looking spectra, but they can look strange and
+cause visual artifacts.  %
+``pcolor'' is a much more direct approach that results in \emph{blocky} but honest two-dimensional
+plots.  % 
+
 \begin{figure}
   \includegraphics[scale=0.5]{"processing/wright_cmap"}
   \includegraphics[scale=0.5]{"processing/cubehelix_cmap"}
@@ -617,28 +647,6 @@ There are better and worse choices of colormap... % TODO: elaborate
   \label{pro:fig:cmap_comparison}
 \end{figure}
 
-\autoref{pro:fig:cmaps} shows the red, green, and blue components of four different colormaps.  %
-The black line is the net intensity of each color (larger value means lighter color).  %
-Below each figure is a gray-scale representation of the corresponding colormap.  %
-The r, g, and b components are scaled according to human perception.  % TODO: values, from where
-The traditional Wright Group colormap (derived from jet) is shown first.  % TODO: cite jet
-It is not perceptual...  % TODO: define perceptual
-Following are two perceptual colormaps, cubehelix from Green  % TODO: cite
-and viridis, the new matplotlib default  % TODO: cite
-WrightTools uses the algorithm from Green to define a custom cubehelix colormap with good
-perceptual properties and familiar Wright Group coloration.  %
-
-\subsubsection{Interpolation type}
-
-WrightTools data is defined at discrete points, but an entire 2D surface must be defined in order
-to make a full colored surface.  %
-Defining this surface requires \emph{interpolation}, and there are various strategies that have
-different advantages and disadvantages.  %
-Choosing the wrong type of interpolation can be misleading.  %
-
-In the multidimensional spectroscopy community, the most popular form of interpolation is based on
-deulaney...
-
 \begin{figure}
   \includegraphics[width=\textwidth]{"processing/fill_types"}
   \caption[CAPTION TODO]{
@@ -670,7 +678,8 @@ Any axis not plotted against will be iterated over such that an image will be ge
 coordinate in that axis.  %
 Users may also provide a dictionary with entries of the form
 \python{{axis_name: [position, units]}} to choose a single coordinate along non-plotted axes.  %
-These functionalities are derived from \python{wt.Data.chop}, discussed further in...  % TODO: link
+These functionalities are derived from \python{wt.Data.chop}, discussed further in
+\autoref{pro:sec:chop}.  %
 
 \begin{figure}
   \includegraphics[width=0.5\textwidth]{"processing/quick1D 000"}
@@ -685,13 +694,11 @@ These functionalities are derived from \python{wt.Data.chop}, discussed further
   \includepython{"processing/quick2D.py"}
   \caption[CAPTION TODO]{
     CAPTION TODO}
-  \label{pro:fig:quick1D}
+  \label{pro:fig:quick2D}
 \end{figure}
 
 % TODO: signed data (with and without dynamic_range=True)
 
-\subsection{Specialty}   % ------------------------------------------------------------------------
-
 \subsection{API}  % -------------------------------------------------------------------------------
 
 The artists sub-package offers a thin wrapper on the default matplotlib object-oriented figure
@@ -705,7 +712,7 @@ Each of these is meant to lower the barrier to plotting data.  %
 Without going into every detail of matplotlib figure generation capabilities, this section
 introduces the unique strategy that the WrightTools wrapper takes.  %
 
-\subsection{Gotchas}  % ---------------------------------------------------------------------------
+% \subsection{Gotchas}  % -------------------------------------------------------------------------
 
 % TODO: mention gotcha of apparently narrowing linewidths with wigners (how to READ colormaps)
 
@@ -754,8 +761,7 @@ From a quick inspection, one can see that \python{w1} and \python{wm} were scann
 \python{w3}, \python{d0}, and \python{d1} were not moved at all, yet their coordinates are still
 propagated.  %
 
-\clearpage
-\section{Axes}  % =================================================================================
+\section{Axes} \label{pro:sec:axes}  % ============================================================
 
 The axes have the joint shape of their component variables.  %
 Although not shown in this example, channels also may have axes with length 1.
@@ -779,7 +785,7 @@ Let's start with some elementary algebra.  %
 
 % TODO: mention chunkwise strategy
 
-\subsection{In-place operators}  % ----------------------------------------------------------------
+\subsection{In-place operators} \label{pro:sec:in_place}  % ---------------------------------------
 
 In Python, operators are symbols that carry out some computation.  %
 Consider the following:
@@ -924,7 +930,7 @@ applied on the very high resolution raw data.  %
 WrightTools offers several strategies for reducing the dimensionality of a data object.  %
 Also consider using the fit sub-package.  % TODO: more info, link to section
 
-\subsection{Chop}  % ------------------------------------------------------------------------------
+\subsection{Chop} \label{pro:sec:chop}  % ---------------------------------------------------------
 
 Chop is one of the most important methods of data, although it is typically not called directly by
 users of WrightTools.  %
@@ -1308,13 +1314,13 @@ Built and hosted by readthedocs
 
 Both master and development versions...
 
-\clearpage
-\section{Future directions}  % ====================================================================
+% \clearpage
+% \section{Future directions}  % ====================================================================
 
-Single variable decomposition.  %
+% Single variable decomposition.  %
 
-Usage in next-generation simulation packages.  %
+% Usage in next-generation simulation packages.  %
 
-More tests.  %
+% More tests.  %
 
-Usage by multiple groups.  %
\ No newline at end of file
+% Usage by multiple groups.  %
\ No newline at end of file
-- 
cgit v1.2.3

