% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
  letterpaper,
  DIV=11,
  numbers=noendperiod]{scrreprt}

\usepackage{amsmath,amssymb}
\usepackage{iftex}
\ifPDFTeX
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
  \usepackage{unicode-math}
  \defaultfontfeatures{Scale=MatchLowercase}
  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
\usepackage{lmodern}
\ifPDFTeX\else  
    % xetex/luatex font selection
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
  \usepackage[]{microtype}
  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
  \IfFileExists{parskip.sty}{%
    \usepackage{parskip}
  }{% else
    \setlength{\parindent}{0pt}
    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
  \KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\usepackage[top=25mm,left=25mm,right=25mm,bottom=25mm]{geometry}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
% Make \paragraph and \subparagraph free-standing
\ifx\paragraph\undefined\else
  \let\oldparagraph\paragraph
  \renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
\fi
\ifx\subparagraph\undefined\else
  \let\oldsubparagraph\subparagraph
  \renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
\fi


\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}\usepackage{longtable,booktabs,array}
\usepackage{calc} % for calculating minipage widths
% Correct order of tables after \paragraph or \subparagraph
\usepackage{etoolbox}
\makeatletter
\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
\makeatother
% Allow footnotes in longtable head/foot
\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
\makesavenoteenv{longtable}
\usepackage{graphicx}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi}
\makeatother
% Scale images if necessary, so that they will not overflow the page
% margins by default, and it is still possible to overwrite the defaults
% using explicit options in \includegraphics[width, height, ...]{}
\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
% Set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother
\newlength{\cslhangindent}
\setlength{\cslhangindent}{1.5em}
\newlength{\csllabelwidth}
\setlength{\csllabelwidth}{3em}
\newlength{\cslentryspacingunit} % times entry-spacing
\setlength{\cslentryspacingunit}{\parskip}
\newenvironment{CSLReferences}[2] % #1 hanging-ident, #2 entry spacing
 {% don't indent paragraphs
  \setlength{\parindent}{0pt}
  % turn on hanging indent if param 1 is 1
  \ifodd #1
  \let\oldpar\par
  \def\par{\hangindent=\cslhangindent\oldpar}
  \fi
  % set entry spacing
  \setlength{\parskip}{#2\cslentryspacingunit}
 }%
 {}
\usepackage{calc}
\newcommand{\CSLBlock}[1]{#1\hfill\break}
\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{#1}}
\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{#1}\break}
\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1}

\KOMAoption{captions}{tableheading}
\makeatletter
\makeatother
\makeatletter
\@ifpackageloaded{bookmark}{}{\usepackage{bookmark}}
\makeatother
\makeatletter
\@ifpackageloaded{caption}{}{\usepackage{caption}}
\AtBeginDocument{%
\ifdefined\contentsname
  \renewcommand*\contentsname{Table of contents}
\else
  \newcommand\contentsname{Table of contents}
\fi
\ifdefined\listfigurename
  \renewcommand*\listfigurename{List of Figures}
\else
  \newcommand\listfigurename{List of Figures}
\fi
\ifdefined\listtablename
  \renewcommand*\listtablename{List of Tables}
\else
  \newcommand\listtablename{List of Tables}
\fi
\ifdefined\figurename
  \renewcommand*\figurename{Figure}
\else
  \newcommand\figurename{Figure}
\fi
\ifdefined\tablename
  \renewcommand*\tablename{Table}
\else
  \newcommand\tablename{Table}
\fi
}
\@ifpackageloaded{float}{}{\usepackage{float}}
\floatstyle{ruled}
\@ifundefined{c@chapter}{\newfloat{codelisting}{h}{lop}}{\newfloat{codelisting}{h}{lop}[chapter]}
\floatname{codelisting}{Listing}
\newcommand*\listoflistings{\listof{codelisting}{List of Listings}}
\makeatother
\makeatletter
\@ifpackageloaded{caption}{}{\usepackage{caption}}
\@ifpackageloaded{subcaption}{}{\usepackage{subcaption}}
\makeatother
\makeatletter
\@ifpackageloaded{tcolorbox}{}{\usepackage[skins,breakable]{tcolorbox}}
\makeatother
\makeatletter
\@ifundefined{shadecolor}{\definecolor{shadecolor}{rgb}{.97, .97, .97}}
\makeatother
\makeatletter
\makeatother
\makeatletter
\ifdefined\Shaded\renewenvironment{Shaded}{\begin{tcolorbox}[boxrule=0pt, borderline west={3pt}{0pt}{shadecolor}, frame hidden, interior hidden, sharp corners, enhanced, breakable]}{\end{tcolorbox}}\fi
\makeatother
\makeatletter
\makeatother
\ifLuaTeX
  \usepackage{selnolig}  % disable illegal ligatures
\fi
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\urlstyle{same} % disable monospaced font for URLs
\hypersetup{
  pdftitle={AnalyCyte: Simplify Your Post-Analysis Reporting for Cytometry},
  pdfauthor={Eugénie Lohmann},
  hidelinks,
  pdfcreator={LaTeX via pandoc}}

\title{AnalyCyte: Simplify Your Post-Analysis Reporting for Cytometry}
\author{Eugénie Lohmann}
\date{2024-04-03}

\begin{document}
\maketitle
\bookmarksetup{startatroot}

\hypertarget{welcome}{%
\chapter*{Welcome}\label{welcome}}
\addcontentsline{toc}{chapter}{Welcome}

\markboth{Welcome}{Welcome}

Provide a brief introduction to the app and its purpose. Include a table
of contents with links to the main sections of the book.

AnalyCyte is a web-based tool designed to streamline post-analysis
reporting for cytometry data.

With AnalyCyte, you can quickly obtain meaningful insights from your
data, enabling efficient decision-making in your research or clinical
workflows.

The AnalyCyte web application was developed by the CiBi platform at
Centre de Recherche en Cancérologie de Marseille (CRCM) in Marseille.

\bookmarksetup{startatroot}

\hypertarget{preface}{%
\chapter*{Preface}\label{preface}}
\addcontentsline{toc}{chapter}{Preface}

\markboth{Preface}{Preface}

Discuss the motivation behind creating the app and its intended
audience. Mention the commercial tools compatible with the app, such as
FlowJo and OmiQ.

\hypertarget{conventions-used-in-this-book}{%
\section*{Conventions Used in This
Book}\label{conventions-used-in-this-book}}
\addcontentsline{toc}{section}{Conventions Used in This Book}

\markright{Conventions Used in This Book}

To comment or ask technical questions about this book, please file an
issue at
\href{https://gitcrcm.marseille.inserm.fr/lohmann/analycyte.book}{gitcrcm.marseille.inserm.fr/lohmann/analycyte.book}.

\hypertarget{acknowledgments}{%
\section*{Acknowledgments}\label{acknowledgments}}
\addcontentsline{toc}{section}{Acknowledgments}

\markright{Acknowledgments}

\ldots{}

\bookmarksetup{startatroot}

\hypertarget{introduction}{%
\chapter*{Introduction}\label{introduction}}
\addcontentsline{toc}{chapter}{Introduction}

\markboth{Introduction}{Introduction}

Introduce the main features of the app, including data import,
integration with analysis software, high-dimensional data visualization,
customizable reporting, and secure access.

\bookmarksetup{startatroot}

\hypertarget{summary}{%
\chapter*{Summary}\label{summary}}
\addcontentsline{toc}{chapter}{Summary}

\markboth{Summary}{Summary}

Summarize the key benefits of using the app for cytometry data analysis
and reporting.

\hypertarget{key-features}{%
\section*{Key Features}\label{key-features}}
\addcontentsline{toc}{section}{Key Features}

\markright{Key Features}

\begin{itemize}
\item
  \textbf{Data Import}: analycyte supports the import of formatted
  output as Excel files containing extracted features and sample
  metadata (e.g., from OMIQ) or concatenated FCS files that include
  clustering columns (e.g., from FlowJo).
\item
  \textbf{Exploratory and Supervised Analyses}: analycyte facilitates
  both exploratory and supervised analyses of features, allowing you to
  gain deeper insights into your cytometry data.
\item
  \textbf{Standardized Reporting}: Generate standardized and informative
  reports quickly, ensuring consistency and clarity in your analyses.

  \begin{itemize}
  \item
    Quality Control: Assess the quality of your data and identify any
    outliers or anomalies.
  \item
    Differentially Abundant Clusters Between Groups: Identify clusters
    or groups of features showing differential abundance between
    different experimental conditions or groups.
  \item
    Differential State Analysis: Analyze the differential state of
    features across different conditions or time points
  \end{itemize}
\end{itemize}

\bookmarksetup{startatroot}

\hypertarget{sec-installation}{%
\chapter{Installation}\label{sec-installation}}

Provide detailed instructions on how to install and set up the app,
including any system requirements and dependencies.

\hypertarget{sec-docker}{%
\section{Docker}\label{sec-docker}}

The current application is provided as a Dockerfile that could be
launched on a cloud computing. As a user, the deployment section is
probably what you only need to run the application. Other sections
concerns the developpers and trainers. The base image section might
interest them.

There are two stages, the base image creation and the application image
creation. The base image freezes a Linux guest with R and all the
packages required by the application. Packages installation is done
once. It fasten the startup of an image for developing, but also for
teaching.

\hypertarget{deployment-ifb-example}{%
\subsection{Deployment (IFB example)}\label{deployment-ifb-example}}

Login to IFB, select a Shiny Server Machine, then launch it with
advanced options.

Set the following configuration:

\begin{verbatim}
APP_STACK
SHINY_REPO
\end{verbatim}

The cloud computer starts and runs the Dockerfile recipe that is based
on the analycyte\_base image available on DockerHub. This process
provides the application as a Web interface.

If you clone this repo, you can add packages to the guest using apt.txt
and to the R installation using Install.R.

\hypertarget{development}{%
\subsection{Development}\label{development}}

To develop and test new features in the application, use a Linux host
with Docker installed and mimic the Dockerfile recipe.

Start analycyte with the base image and a port for shiny web service.
The base image is run in interactive mode, otherwise a shiny server is
executed (see the FROM item). The base image is pulled from DockerHub on
the first run because it does not exist in the local host cache.

\begin{verbatim}
docker run -it -p 3838:3838 eugloh/analycyte_base:0.3 bash
\end{verbatim}

Then install the latest version of the analycyte packages.

\begin{verbatim}
R -e "
Sys.setenv(R_REMOTES_UPGRADE = 'never')  # do not update packages from CRAN
remotes::install_gitlab('lohmann/analycyte.projects', host = 'https://gitcrcm.marseille.inserm.fr')
remotes::install_gitlab('lohmann/analycyte.utils', host = 'https://gitcrcm.marseille.inserm.fr')
remotes::install_gitlab('lohmann/analycyte', host = 'https://gitcrcm.marseille.inserm.fr')
"
\end{verbatim}

Finally, launch the shiny process (with a log file).

\begin{verbatim}
R -e "options('shiny.port'=3838,shiny.host='0.0.0.0');library(analycyte);analycyte::run_app()" 2>&1 | tee 3838.log
\end{verbatim}

Once done, exit the guest.

\begin{verbatim}
exit  # or Ctrl-D
\end{verbatim}

\hypertarget{teaching}{%
\subsection{Teaching}\label{teaching}}

In the guest, we can run many processes at once. Ports must be created
before on the host. Run the guest in interactive mode, otherwise a shiny
server is executed (see the FROM item).

\begin{verbatim}
docker run -it -p 3838:3838 -p 3839:3839 analycyte_base bash
\end{verbatim}

Install the latest packages of analycyte.

Launch many processes.

\begin{verbatim}
R -e "options('shiny.port'=3838,shiny.host='0.0.0.0');library(analycyte);analycyte::run_app()" 2>&1 | tee 3838.log &
R -e "options('shiny.port'=3839,shiny.host='0.0.0.0');library(analycyte);analycyte::run_app()" 2>&1 | tee 3839.log &
\end{verbatim}

\hypertarget{base-image}{%
\subsection{Base image}\label{base-image}}

The base image freezes a Linux guest with R and all the packages
required by the application. Packages installation is done once, which
fasten the startup. The base image is also pushed on DockerHub for
resuse. Here is how to create it.

Open a bash shell, clone the repo and build the base image.

\begin{verbatim}
git clone https://gitcrcm.marseille.inserm.fr/lohmann/deploy
cd deploy
\end{verbatim}

Build the base image.

\begin{verbatim}
docker build -f Dockerfile_base -t analycyte_base .
\end{verbatim}

Tag the build.

\begin{verbatim}
docker tag analycyte_base eugloh/analycyte_base:0.3
\end{verbatim}

Login dockerhub, then push the image (you must have an account on
DockerHub).

\begin{verbatim}
docker login
docker push eugloh/analycyte_base:0.3
\end{verbatim}

\hypertarget{helping-knowledge}{%
\subsection{Helping knowledge}\label{helping-knowledge}}

\hypertarget{connecting-app-and-log-directories-to-host}{%
\subsubsection{Connecting app and log directories to
host}\label{connecting-app-and-log-directories-to-host}}

To expose a directory on the host to the container, use -v :. The
following command will use one /srv/shinyapps as the Shiny app directory
and /srv/shinylog as the directory for Shiny app logs. Note that if the
directories on the host don't already exist, they will be created
automatically.:

\begin{verbatim}
docker run --rm -it -p 3838:3838 \
    -v /srv/shinyapps/:/srv/shiny-server/ \
    -v /srv/shinylog/:/var/log/shiny-server/ \
    rocker/shiny
\end{verbatim}

If you have an app in /srv/shinyapps/appdir, you can run the app by
visiting http://localhost:3838/appdir/. (If using boot2docker, visit
http://192.168.59.103:3838/appdir/)

In a real deployment scenario, you will probably want to run the
container in detached mode (-d) and listening on the host's port 80 (-p
80:3838):

\begin{verbatim}
docker run -d -p 80:3838 \
    -v /srv/shinyapps/:/srv/shiny-server/ \
    -v /srv/shinylog/:/var/log/shiny-server/ \
    rocker/shiny
\end{verbatim}

\begin{verbatim}
-d detached mode
-p 80:3838 redirect the guest port 3838 to the host 80
--rm run a temporary container
--user shiny run as user shiny
\end{verbatim}

\part{User's Guide}

\hypertarget{how-to-start}{%
\chapter{How to Start}\label{how-to-start}}

Offer a step-by-step guide for users to get started with the app,
including how to create an account, log in, and navigate the interface.

\hypertarget{sec-shiny-workflow}{%
\chapter{Shiny workflow}\label{sec-shiny-workflow}}

Describe the Shiny framework used in the app and its benefits for
creating interactive web applications.

\hypertarget{sec-action-list}{%
\chapter{Module list}\label{sec-action-list}}

List and explain the different Shiny actions available in the app, along
with their functions and usage.

\part{}

\hypertarget{sec-mod-deploy-ifb}{%
\chapter{Deploying with IFB}\label{sec-mod-deploy-ifb}}

To deploy AnalyCyte using the IFB (Institut Français de Bioinformatique)
platform, you will first need to create an account and be affiliated
with a group.

The IFB is an institutional platform in France, making the account
creation process straightforward. Once you are affiliated with a group,
you can open a virtual machine (VM) with your app in approximately 15
minutes.

\hypertarget{process}{%
\section{Process}\label{process}}

To deploy your R Shiny app using the IFB platform, follow these steps:

Create an IFB account: Register for an account on the IFB platform. This
process is straightforward, as the IFB is an institutional platform in
France.

Join a group: Affiliate yourself with a group on the IFB platform. This
will grant you access to the necessary resources for deploying your app.

Open a virtual machine (VM): Once you are affiliated with a group, you
can open a VM with your app. Choose an ``R Shiny'' VM and add the
shiny\_repo ``https://gitcrcm.marseille.inserm.fr/lohmann/deploy''. This
process typically takes approximately 15 minutes.

By following these steps, you can easily deploy your R Shiny app on the
IFB platform. This method allows you to leverage the benefits of cloud
deployment while simplifying the process with a user-friendly,
institutional platform.

\part{Import data}

\hypertarget{sec-import_concat}{%
\chapter{Import Concatened FCS}\label{sec-import_concat}}

In order to load and concatenate cytometry data in the app, you will be
working with specific file types or formats. The app supports the use of
a single FCS file containing all the cells, along with additional
columns for initial FCS ID, clustering, and possible dimension reduction
information (e.g., t-SNE, UMAP). This file will be linked to a metadata
file generated by the user, which contains FCS ID information to
identify the different initial sample IDs and groups of interest. To
load and concatenate data in the app, follow these steps:

\begin{verbatim}
Prepare your FCS file: Ensure that your FCS file contains all the cells and the necessary additional columns for initial FCS ID, clustering, and possible dimension reduction information.
Create a metadata file: Generate a metadata file that contains FCS ID information to identify the different initial sample IDs and groups of interest. This file should be in a compatible format, such as CSV or TSV.
Load the data: Use the app's import functionality to load both the FCS file and the metadata file. Ensure that the files are correctly linked during the import process.
Concatenate the data: Once the data is loaded, use the app's concatenation feature to combine the data from the different samples and groups. This will create a single dataset that can be used for further analysis and visualization.
\end{verbatim}

\hypertarget{sec-import_features}{%
\chapter{Import Features tables}\label{sec-import_features}}

\hypertarget{sec-import_rds}{%
\chapter{Import R files}\label{sec-import_rds}}

\part{Loaded data}

\hypertarget{sec-dataset}{%
\chapter{Dataset Visualisation}\label{sec-dataset}}

\bookmarksetup{startatroot}

\hypertarget{sec-extract_sce}{%
\chapter{Clustering Selection}\label{sec-extract_sce}}

\part{Report Generation}

\hypertarget{sec-QC}{%
\chapter{control quality of features}\label{sec-QC}}

\hypertarget{sec-da}{%
\chapter{analyse abundancy of clusters - univar}\label{sec-da}}

\hypertarget{sec-ds}{%
\chapter{analyse intensity of clusters - univar}\label{sec-ds}}

\part{Export}

\hypertarget{sec-ph}{%
\chapter{Phantasus Table}\label{sec-ph}}

\hypertarget{sec-export_projects}{%
\chapter{Export Analysis to disk}\label{sec-export_projects}}

\bookmarksetup{startatroot}

\hypertarget{sec-glossary}{%
\chapter{Glossary}\label{sec-glossary}}

\begin{itemize}
\item
  counts
\item
  perCellCounts
\item
  perCellCountsNorm
\end{itemize}

\bookmarksetup{startatroot}

\hypertarget{references}{%
\chapter*{References}\label{references}}
\addcontentsline{toc}{chapter}{References}

\markboth{References}{References}

\hypertarget{refs}{}
\begin{CSLReferences}{0}{0}
\end{CSLReferences}

\cleardoublepage
\phantomsection
\addcontentsline{toc}{part}{Appendices}
\appendix

\hypertarget{sec-appendix-flowjo}{%
\chapter{Import data from Flowjo}\label{sec-appendix-flowjo}}

\hypertarget{sec-appendix-omiq}{%
\chapter{Import data from OmiQ}\label{sec-appendix-omiq}}

\hypertarget{sec-a3}{%
\chapter{Analycyte verse}\label{sec-a3}}

analycyte.projects, analycyte.utils, analycyte, analycyte.book



\end{document}