
\documentclass{article}

\usepackage{url}
\usepackage{natbib}
\usepackage{graphics}
\usepackage{amsmath}
\usepackage{indentfirst}
\usepackage[utf8]{inputenc}
\usepackage{fullpage}

% \VignetteIndexEntry{Display-cell-images}

\begin{document}

\SweaveOpts{eps = FALSE, pdf = TRUE}
\SweaveOpts{prefix.string=fig/cimage}
<<include=FALSE,echo=FALSE>>=
  if(!file.exists("fig")) dir.create("fig")  
@
\setkeys{Gin}{width=1\textwidth}

<<foo,include=FALSE,echo=FALSE>>=
options(keep.source = TRUE, width = 100)
foo <- packageDescription("Rcell")
@

\title{Display cell images with Rcell (Version \Sexpr{foo$Version})}
\author{Alan Bush}
\maketitle

\section{Introduction}

\textbf{Rcell} uses the functions of \textbf{EBImage} package to manipulate and display the images processed by Cell-ID. The main purpose of the functions described in this document is to get a quick look at cells in different conditions, channels and times. \verb@cimage@ function crops images from single cells and displays them according to a user define order. 

If you haven't done so, read the ``Getting Started with Rcell'' document before proceeding.

<<eval=FALSE,echo=TRUE>>=
vignette('Rcell')
@

Make sure you have the \textbf{EBImage} package installed in your system. This package is quite hard to install, follow instructions from \url{http://bioconductor.wustl.edu/bioc/html/EBImage.html}.

<<include=FALSE,echo=FALSE>>=
library(Rcell)
data(ACL394)
X$images$path<-factor(system.file('img', package='Rcell'))
@

\section{Display cell images}

When analyzing a dataset, you usually want to take a look at the cells images that are generating the data points. This helps interpret the data and gives you confidence on the result. To visualize a random set of cells from a image, you have to specify position a channel and a t.frame (if you are dealing with a time course). For example to visualize some BF images of cells from position 29 and t.frame 11 use the following command. 

<<img1,include=TRUE>>=
img1<-cimage(X,subset=pos==29&t.frame==11,channel="BF",bg.col="white")
@

This function displays the image shown in Figure ~\ref{fig:img1}, and returns a Image object (saved to the img1). 

<<include=FALSE,echo=FALSE>>= 
writeImage(img1, 'fig/cimage-img1.jpg', quality=80)
@

\begin{figure}
\begin{center}
\includegraphics[width=75pt]{fig/cimage-img1.jpg}
\caption{BF images of random cells selected from position 29, t.frame 11}
\label{fig:img1}
\end{center}
\end{figure}

As all \textbf{Rcell} functions, the first argument of \verb@cimage@ is the cell.data object that you wish to visualize. This function first subsets the cell.data object X according to the \emph{subset} argument, as many other \textbf{Rcell} functions. This is useful to select cells and times, but you can't use this argument to select the channel you want to see. Instead you can use the \emph{channel} argument for this. Note that you can select several channels (see below). \verb@cimage@ then takes a random sample of cells from those who passed the \emph{subset} argument. The default sample size is seven, but you can specify it with the \emph{N} argument. If you set this argument to NA, no sampling is applied and all cells are shown.
The position each cell took in the image was arbitrary in Figure ~\ref{fig:img1}, they were just tiled together to make a square arrangement. But position can have a meaning. A normal way to display cell images is to show time course strips, where different channels are stacked one over the other. \verb@cimage@ can easily produce this sort of images (Figure ~\ref{fig:img2}).

<<img2,include=TRUE>>=
img2<-cimage(X,channel~t.frame,subset=pos==29&cellID==5,channel=c("BF","YFP"),bg.col="white")
@

<<include=FALSE,echo=FALSE>>= 
writeImage(img2, 'fig/cimage-img2.jpg', quality=80)
@

\begin{figure}
\begin{center}
\includegraphics[width=0.9\textwidth]{fig/cimage-img2.jpg}
\caption{Time course strips for cell 5 of position 29}
\label{fig:img2}
\end{center}
\end{figure}

The second argument \verb@cimage@ is the \emph{formula} that specifies the position of individual images. The first term indicates the \verb@y@ variable, \verb@channel@ in this example. So different channels will have different \verb@y@ coordinates. The right term specifies which variable is going to be used as the \verb@x@ coordinate, \verb@t.frame@ in this case. In this example a single cell was explicitly selected with the \emph{subset} argument. When you select more than one cell, you have to specify how you want to layout them on the image. To specify different cells within a sample you can use dots (...), as shown in Figure~\ref{fig:img3}.  
 
<<img3,include=TRUE>>=
img3<-cimage(X,...+channel~t.frame,subset=pos==29,channel=c("BF","YFP"),N=4,bg.col="white")
@

<<include=FALSE,echo=FALSE>>= 
writeImage(img3, 'fig/cimage-img3.jpg', quality=80)
@

\begin{figure}
\begin{center}
\includegraphics[width=0.9\textwidth]{fig/cimage-img3.jpg}
\caption{Time course strips for 4 randomly chosen cells}
\label{fig:img3}
\end{center}
\end{figure}

Note that you can use more than one variable in each term of the formula, separated by the plus operator. The order matters, the last variable (to the right) varies faster. In this example (Figure ~\ref{fig:img3}) channel is anidated in each cell (you can think of the dots as different cells).

The \emph{channel.subset} argument allows you to do more complex selection of channels and t.frame. For example you might be interested in the YFP channel, but would like to see the cell boundary found by Cell-ID on a BF image, for a single time frame (Figure ~\ref{fig:img4}).

<<img4,include=TRUE>>=
img4<-cimage(X,...~channel+t.frame,subset=pos==29,channel.subset=channel=="YFP"|(channel=="BF.out"&t.frame==11),N=4,bg.col="white")
@
 
<<include=FALSE,echo=FALSE>>= 
writeImage(img4, 'fig/cimage-img4.jpg', quality=80)
@


\begin{figure}
\begin{center}
\includegraphics[width=0.9\textwidth]{fig/cimage-img4.jpg}
\caption{YFP time course strips for 4 randomly chosen cells, with a single BF image}
\label{fig:img4}
\end{center}
\end{figure}

Note that you can select the ``out'' images generated by Cell-ID by appending ``.out'' to the channel name.

\section{Faceting your image plot}

In the same way as for \verb@cplot@, you can define \emph{facets} for the image plot. The facets are specified with formula notation, just as the positions of the images within a facet. If only one term of the formula is specified, the facets will be wrapped around and the \emph{facets.nx} argument can be used to indicate the number of facets columns (Figure ~\ref{fig:img5}). 

<<img5,include=TRUE>>=
img5<-cimage(X,...~channel,facets=~pos,subset=t.frame==11&pos%in%c(1,8,15,22,29),channel=c("YFP","BF"),bg.col="white",N=3,facets.nx=5)
@

<<include=FALSE,echo=FALSE>>= 
writeImage(img5, 'fig/cimage-img5.jpg', quality=80)
@

 
\begin{figure}
\begin{center}
\includegraphics[width=250pt]{fig/cimage-img5.jpg}
\caption{sample against channel, faceted by position}
\label{fig:img5}
\end{center}
\end{figure}

\section{Plotting images against continuous variables}

An interesting plot can be obtained if we choose the position of the image according to a continuous variable. First, suitable bins of the continuous variables have to be created, we can use the  \verb@cut@ function for this.

<<cut,include=TRUE>>=
X<-transform(X,cut.fft.stat=cut(fft.stat,20))
X<-transform(X,cut.f.total.y=cut(f.total.y,20))
@

Once these variables are created we can use them to arrange the images of the cells (Figure ~\ref{fig:img6}).
 
<<img6,include=TRUE>>=
img6<-cimage(X,cut.f.total.y~cut.fft.stat,facets=~channel,subset=t.frame==11 & pos %in% c(1,8,15,22,29),channel=c("YFP","BF.out"),bg.col="white",N=1)
@

<<include=FALSE,echo=FALSE>>= 
writeImage(img6, 'fig/cimage-img6.jpg', quality=80)
@

\begin{figure}
\begin{center}
\includegraphics[width=300pt]{fig/cimage-img6.jpg}
\caption{f.total.y vs fft.stat, faceted by channel}
\label{fig:img6}
\end{center}
\end{figure}
  

\begin{thebibliography}{}

\bibitem[Pau et al. (2010)]{pau2010}
Pau, Fuchs et al. (2010).
\newblock EBImage: an R package for image processing with applications to cellular phenotypes.
\newblock \emph{Bioinformatics}, 26(7):979-981.

\bibitem[Colman-Lerner et al. (2005)]{acl2005}
Colman-Lerner, Gordon et al. (2005).
\newblock Regulated cell-to-cell variation in a cell-fate decision system.
\newblock \emph{Nature}, 437(7059):699-706.

\bibitem[Chernomoretz et al. (2008)]{cpmcb2008}
Chernomoretz, Bush et al. (2008).
\newblock Using Cell-ID 1.4 with R for Microscope-Based Cytometry.
\newblock \emph{Curr Protoc Mol Biol.}, Chapter 14:Unit 14.18.

\end{thebibliography}

\end{document}
