diff options
Diffstat (limited to 'processing/chapter.tex')
| -rw-r--r-- | processing/chapter.tex | 186 |
1 files changed, 129 insertions, 57 deletions
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(<filepath>)}. %
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. %
|