From a1bc96e82ff539ebe94aeb498ce8d00136e31b12 Mon Sep 17 00:00:00 2001 From: Blaise Thompson Date: Sun, 25 Mar 2018 18:57:16 -0500 Subject: 2018-03-25 18:57 --- processing/chapter.tex | 186 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 129 insertions(+), 57 deletions(-) (limited to 'processing') diff --git a/processing/chapter.tex b/processing/chapter.tex index 40055c4..94ef12e 100644 --- a/processing/chapter.tex +++ b/processing/chapter.tex @@ -36,6 +36,8 @@ WrightTools is a software package at the heart of all work in the Wright Group. % TODO: more intro +\section{Introduction to WrightTools} % ========================================================== + WrightTools is written in Python, and endeavors to have a ``pythonic'', explicit and ``natural'' application programming interface (API). % To use WrightTools, simply import: @@ -88,8 +90,6 @@ Within the public API are two classes, \python{Collection} \& \python{Collection} stores \textit{groups} of data objects (and other collection objects) in a hierarchical way for internal organization purposes. % -\section{Data object model} % ==================================================================== - WrightTools uses a programming strategy called object oriented programming (OOP). % % TODO: introduce HDF5 % TODO: elaborate on the concept of OOP and how it relates to WrightTools @@ -214,9 +214,9 @@ A lexicographical list of axis attributes and methods follows. \item method \python{max} \end{ditemize} % TODO: actually lexicographical -\subsection{Creating a data object} % ------------------------------------------------------------ +\section{Creating a data object} % =============================================================== -WrightTools data objects are capable of storing arbitrary multidimensional spectra, but how can we +WrightTools data objects are capable of storing arbitrary multidimensional spectra, but how can w actually get data into WrightTools? % If you start with a wt5 file, the answer is easy: \python{wt.open()}. % But what if you have data that was written using some other software? % @@ -299,7 +299,64 @@ library Qhull. % This strategy can be copied in the future if other non-self-describing data sources are added into WrightTools. % -\subsubsection{From directory} +\section{Collections} % ========================================================================== + +The WrightTools \python{Collection} class is a container class meant to organize the contents of +the wt5 file. % +It can contain other collection instances and data objects. % +Conceptually, it behaves like a folder in a traditional file-system. % +\python{wt.Collection} is a child of \python{h5py.Group} \cite{h5py.Group}. + +The primary attributes and methods of \python{Collection} are +\begin{ditemize} + \item attribute item_names + \item attribute \python{fullpath} +\end{ditemize} +% TODO: finish adding attributes and methodsd + +Collections are useful because they allow WrightTools users to ``carry around'' several associated +data objects in the same file. % +For example, a publication might contain several experiments on the same sample. % +Collections allow such experiments to be organized in a hierarchical way. % +The hierarchy of contents that a collection contains can be easily visualized using the +\python{print_tree} method. % +As an example, consider the following collection instance which contains some experiments +accomplished on neat carbon tetrachloride. % +\begin{codefragment}{bash} +>>> import WrightTools as wt +>>> root = wt.open('CCl4.wt5') +>>> root.print_tree() +CCl4 (/tmp/0tze7b8a.wt5) +├── 0: delay (111,) +│ ├── axes: d1 (fs) +│ └── channels: ai0, ai1, ai2, ai3 +└── 1: frequency + ├── 0: delay_0 (51, 51) + │ ├── axes: w2 (eV), w1=wm (eV) + │ └── channels: ai0, ai1, ai2, ai3, ai4, mc + └── 1: delay_200 (18, 20) + ├── axes: w1=wm (eV), w2 (eV) + └── channels: ai0, ai1, ai2, ai3 +\end{codefragment} +Looking at the output of \python{print_tree}, we can see that this collection (named \python{CCl4}) +contains the following: +\begin{denumerate} + \item A data object ``\python{delay}'', shape \python{(111,)}. + \item A collection object ``\python{frequency}'', containing two 2D data objects. + \begin{denumerate} + \item A data object ``\python{delay_0}'', shape \python{(51, 51)}. + \item A data object ``\python{delay_200}'', shape \python{18, 20}. + \end{denumerate} +\end{denumerate} +Since this is all contained in one file, a user of WrightTools can easily manage all three +associated datasets. % +Upon simple inspection it is obvious that two of the datasets are 2D frequency-frequency scans +while one is a 1D delay slice. % + +Like \python{Channel}, \python{Data} and \python{Variable}, \python{Collection} supports adding +arbitrary metadata through the \python{attrs} dictionary. % TODO: cite + +\subsection{From directory} % -------------------------------------------------------------------- The \python{wt.collection.from_directory} function can be used to automatically import all of the data sources in an entire directory tree. % @@ -309,7 +366,51 @@ Users can configure which files are routed to which from-function. % % TODO (also document on wright.tools) -\subsection{Variables and channels} % ------------------------------------------------------------ +\section{Visualizing a data object} % ============================================================ + +After importing and manipulating data, one typically wants to create a plot. % +The artists sub-package contains everything users need to plot their data objects. % +This includes both ``quick'' artists, which generate simple plots as quickly as possible, and a +full figure layout toolkit that allows users to generate full publication quality figures. % +It also includes ``specialty'' artists which are made to perform certain popular plotting +operations, as I will describe below. % + +Currently the artists sub-package is built on-top of the wonderful matplotlib library. % +In the future, other libraries (e.g. Mayavi \cite{Mayavi}), may be incorporated. % + +\subsection{Colormaps} % ------------------------------------------------------------------------- + +% TODO: figure like made by visualize_colormap_components + +% TODO: figure like one on wall + +% TODO: mention isoluminant + +\subsection{Interpolation} % --------------------------------------------------------------------- + +% TODO: fill types figure from wright.tools + +\subsection{Quick} % ----------------------------------------------------------------------------- + +\subsubsection{1D} + +\begin{figure} + \includegraphics[width=0.5\textwidth]{"processing/quick1D 000"} + \includepython{"processing/quick1D.py"} + \caption[CAPTION TODO] + {CAPTION TODO} +\end{figure} + +\subsubsection{2D} + +\begin{figure} + \includegraphics[width=0.5\textwidth]{"processing/quick2D 000"} + \includepython{"processing/quick2D.py"} + \caption[CAPTION TODO] + {CAPTION TODO} +\end{figure} + +\section{Variables and channels} % =============================================================== Data objects are made up of many component channels and variables, each array having the same dimensionality of its parent data. % @@ -352,6 +453,11 @@ From a quick inspection, one can see that \python{w1} and \python{wm} were scann \python{w2} and \python{d2} were the other two dimensions. % \python{w3}, \python{d0}, and \python{d1} were not moved at all, yet their coordinates are still propagated. % + + +\section{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. @@ -367,13 +473,13 @@ squeezed and broadcasted array, respectively. % \end{figure} -\subsection{Math} % ------------------------------------------------------------------------------ +\section{Math} % ================================================================================= Now that we know the basics of how the WrightTools \python{Data} class stores data, it's time to do some data manipulation. % Let's start with some elementary algebra. % -\subsubsection{In-place operators} +\subsection{In-place operators} In Python, operators are symbols that carry out some computation. % Consider the following: @@ -432,30 +538,30 @@ data.created at /tmp/tdyvfxu8.wt5::/ \end{codefragment} Variables also support in-place operators. % -\subsubsection{Clip} +\subsection{Clip} % TODO -\subsubsection{Symmetric root} +\subsection{Symmetric root} % TODO -\subsubsection{Log} +\subsection{Log} % TODO -\subsection{Dimensionality manipulation} % ------------------------------------------------------- +\section{Dimensionality manipulation} % ========================================================== 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 -\subsubsection{Chop} +\subsection{Chop} % ------------------------------------------------------------------------------ Chop is one of the most important methods of data, although it is typically not called directly by users of WrightTools. % Chop takes n-dimensional data and ``chops'' it into all of it's lower dimensional components. % -Consider a 3D dataset in \python{('wm', 'w2', 'w1')}. % -This dataset can be chopped to it's component 2D \python{('wm', 'w1')} spectra. % +Consider a 3D dataset in \python{('wm', 'w2', 'w1''''')}. % +This dataset can be chopped to it's component 2D \python{('wm'', 'w1')} spectra. % \begin{codefragment}{python, label=test_label} >>> import WrightTools as wt; from WrightTools import datasets >>> data = wt.data.from_PyCMDS(datasets.PyCMDS.wm_w2_w1_000) @@ -499,47 +605,13 @@ array([1580.0]) Note the [0]... % TODO This same syntax used in artists... % TODO -\subsubsection{Collapse} - -\subsubsection{Split} - -\subsubsection{Join} +\subsection{Collapse} % -------------------------------------------------------------------------- -\subsection{The wt5 file format} % --------------------------------------------------------------- +\subsection{Split} % ----------------------------------------------------------------------------- -Since WrightTools is based on the hdf5 file format... % TODO +\subsection{Join} % ------------------------------------------------------------------------------ -\section{Artists} % ============================================================================== - -After importing and manipulating data, one typically wants to create a plot. % -The artists sub-package contains everything users need to plot their data objects. % -This includes both ``quick'' artists, which generate simple plots as quickly as possible, and a -full figure layout toolkit that allows users to generate full publication quality figures. % -It also includes ``specialty'' artists which are made to perform certain popular plotting -operations, as I will describe below. % - -Currently the artists sub-package is built on-top of the wonderful matplotlib library. % -In the future, other libraries (e.g. mayavi), may be incorporated. % - -\subsection{Quick} % ----------------------------------------------------------------------------- - -\subsubsection{1D} - -\begin{figure} - \includegraphics[width=0.5\textwidth]{"processing/quick1D 000"} - \includepython{"processing/quick1D.py"} - \caption[CAPTION TODO] - {CAPTION TODO} -\end{figure} - -\subsubsection{2D} - -\begin{figure} - \includegraphics[width=0.5\textwidth]{"processing/quick2D 000"} - \includepython{"processing/quick2D.py"} - \caption[CAPTION TODO] - {CAPTION TODO} -\end{figure} +\section{Specialty visualizations} % ============================================================= \subsection{Specialty} % ------------------------------------------------------------------------- @@ -558,13 +630,13 @@ introduces the unique strategy that the WrightTools wrapper takes. % % TODO: finish discussion -\subsection{Colormaps} % ------------------------------------------------------------------------- +\section{Fitting} % ============================================================================== -\subsection{Interpolation} % --------------------------------------------------------------------- +\section{Construction and maintenance} % ========================================================= -\section{Fitting} % ============================================================================== +\subsection{Unit tests} % ------------------------------------------------------------------------ -\section{Distribution and licensing} \label{sec:processing_disbribution} % ======================= +\section{Distribution and licensing} \label{pro:sec:disbribution} % ============================== WrightTools is MIT licensed. % -- cgit v1.2.3