@@ -1,8 +1,8 @@

 Package: OncoSimulR

 Type: Package

 Title: Forward Genetic Simulation of Cancer Progression with Epistasis 

-Version: 2.5.4

-Date: 2016-12-12

+Version: 2.5.5

+Date: 2016-12-14

 Authors@R: c(person("Ramon", "Diaz-Uriarte", role = c("aut", "cre"),

 		     email = "rdiaz02@gmail.com"),

 	      person("Mark", "Taylor", role = "ctb", email = "ningkiling@gmail.com"))

@@ -1,3 +1,6 @@

+Changes in version 2.5.5 (2016-12-14):

+	- Vignette: miscell changes (typos, etc)

+	

 Changes in version 2.5.4 (2016-12-12):

 	- Vignette: miscell changes (order of examples, typos, etc)

@@ -160,11 +160,11 @@ mutator effects.

-OncoSimulR was originally developed to simulate tumor progression using

-several models of tumor progression with emphasis on allowing users to set

-restrictions in the accumulation of mutations as specified, for example, by

-Oncogenetic Trees [OT: @Desper1999JCB; @Szabo2008] or Conjunctive Bayesian

-Networks [CBN: @Beerenwinkel2007; @Gerstung2009; @Gerstung2011], with the

+OncoSimulR was originally developed to simulate tumor progression with

+emphasis on allowing users to set restrictions in the accumulation of

+mutations as specified, for example, by Oncogenetic Trees

+[OT: @Desper1999JCB; @Szabo2008] or Conjunctive Bayesian Networks

+[CBN: @Beerenwinkel2007; @Gerstung2009; @Gerstung2011], with the

 possibility of adding passenger mutations to the simulations and allowing

 for several types of sampling.

@@ -195,22 +195,24 @@ of genes in a module. In addition, arbitrary numbers of genes without

 interactions (and with fitness effects coming from any distribution you

 might want) are also possible.

-Mutator/antimutator genes, genes that alter the mutation rate of other genes

-[@gerrish_complete_2007, @tomlinson_mutation_1996], can also be simulated

-with OncoSimulR and specified with most of the mechanisms above (you can

-have, for instance, interactions between mutator genes). And, with regards

-to mutation rates, different genes can have different mutation rates

-(regardless of the presence or not of other mutator/antimutator genes).

+Mutator/antimutator genes, genes that alter the mutation rate of

+other genes [@gerrish_complete_2007; @tomlinson_mutation_1996], can

+also be simulated with OncoSimulR and specified with most of the

+mechanisms above (you can have, for instance, interactions between

+mutator genes). And, regardless of the presence or not of other

+mutator/antimutator genes, different genes can have different

+mutation rates.

-Simulations can be stopped as a function of total population size, number of

-mutated driver genes, or number of time periods. Simulations can also be

-stopped with a stochastic detection mechanism where the probability of

+Simulations can be stopped as a function of total population size, number

+of mutated driver genes, or number of time periods. Simulations can also

+be stopped with a stochastic detection mechanism where the probability of

 detecting a tumor increases with total population size. Simulations return

-the number of cells of every genotype/clone at each of the sampling periods

-and the genealogical relationships of all clones generated during the

-simulation. We can take samples from those data with single-cell or whole-

-tumor resolution, adding noise if we want.

+the number of cells of every genotype/clone at each of the sampling

+periods and we can take samples from the former with single-cell or whole-

+tumor resolution, adding noise if we want. If we ask for them, simulations

+also store and return the genealogical relationships of all clones

+generated during the simulation.

 The models so far implemented are all continuous time models, which are

@@ -219,7 +221,7 @@ implemented in C++, providing for fast execution.  To help with simulation

 studies, code to simulate random graphs of the kind often seen in CBNs, OTs,

 etc, is also available. Finally, OncoSimulR also allows for the generation

 of random fitness landscapes and the representation of fitness landscapes

-and provides some statistics of of evolutionary predictability.

+and provides statistics of evolutionary predictability.

@@ -228,7 +230,7 @@ and provides some statistics of of evolutionary predictability.

 As mentioned above, OncoSimulR is now a very general package for forward

 genetic simulation, with applicability well beyond tumor progression. This

-is a summary of some of the key features:

+is a summary of some of its key features:

 <!-- FIXME: add the tables of the poster -->

@@ -240,14 +242,14 @@ is a summary of some of the key features:

       Oncogenetic Trees (OTs), Conjunctive Bayesian Networks (CBNs),

       semimonotone progression networks, and XOR relationships.

-    - Epistatic interactions, including, but not limited to, synthetic

+    - Epistatic interactions including, but not limited to, synthetic

        viability and synthetic lethality.

     - Order effects.

 * You can add passenger mutations.

 * You can add mutator/antimutator effects.

 * Fitness and mutation rates can be gene-specific.

-* More generally, you can add arbitrary numbers of non-interacting

+* You can add arbitrary numbers of non-interacting

       genes with arbitrary fitness effects.

 * you can allow for deviations from the OT, CBN, semimonotone, and

@@ -259,9 +261,9 @@ is a summary of some of the key features:

       sampling. 

 * You can stop the simulations using a flexible combination of

-      conditions, from final time to number of drivers to population

-      size, to fixation of certain genotypes, to a stochastic

-      stopping mechanism that depends on size, etc.  

+      conditions: final time, number of drivers, population

+      size, fixation of certain genotypes, and a stochastic

+      stopping mechanism that depends on population size.

 * Right now, three different models are available, two that lead

       to exponential growth, one of them loosely based on @Bozic2010, and

@@ -270,7 +272,7 @@ is a summary of some of the key features:

 <!-- * Code in C++ is available (though not yet callable from R) for -->

 <!--       using several other models, including the one from @Beerenwinkel2007b. -->

-* You can use very large numbers of genes (e.g., see an example of

+* You can use large numbers of genes (e.g., see an example of

       50000 in section \@ref(mcf50070) ).

 * Simulations are generally very fast: I use C++ to implement the BNB

@@ -288,13 +290,13 @@ is a summary of some of the key features:

 * You can plot fitness landscapes.

-* You can obtain some basic measures of evolutionary predictability

+* You can obtain statistics of evolutionary predictability

   from the simulations.

 The table below, modified from the table at the

-[Genetics Simulation Resources (GSR) page](https://popmodels.cancercontrol.cancer.gov/gsr/packages/oncosimulr/#detailed)

+[Genetics Simulation Resources (GSR) page](https://popmodels.cancercontrol.cancer.gov/gsr/packages/oncosimulr/#detailed), 

 provides a summary of the key features of OncoSimulR. (An

 explanation of the meaning of terms specific to the GSR table is

 available from

@@ -304,21 +306,21 @@ by moving the mouse over each term).

 \clearpage

-|Attribute Category     | Attribute                                     |

-|-----------------------|-----------------------------------------------|

-|**Target**             |  |

-|  Type of Simulated Data|           Haploid DNA Sequence|

-|  variations            |           Biallelic Marker, Genotype or Sequencing Error|

-|**Simulation Method**            |           Forward-time|

-|  Type of Dynamical Model | Continuous time|

-|  Entities Tracked | Clones (see \@ref(trackindivs))|

+|Attribute Category                  | Attribute                                     |

+|-------------------------------|-----------------------------------------------|

+|**Target**                           |  |

+|  Type of Simulated Data        |           Haploid DNA Sequence|

+|  Variations                    |           Biallelic Marker, Genotype or Sequencing Error|

+|**Simulation Method**                |           Forward-time|

+|  Type of Dynamical Model       | Continuous time|

+|  Entities Tracked              | Clones (see \@ref(trackindivs))|

 |**Input** | Program specific (R data frames and matrices specifying genotypes' fitness, gene effects, and starting genotype) |

 |**Output**||

 |  Data Type| Genotype or Sequence, Individual Relationship (complete parent-child relationships between clones), Demographic (populations sizes of all clones at sampling times), Diversity Measures (LOD, POM, diversity of genotypes), Fitness|

 |  Sample Type|	Random or Independent, Longitudinal, Other (proportional to population size)|

 |**Evolutionary Features**	||

 |  Mating Scheme| Asexual Reproduction |

-|  Demographic||	

+|  Demographic                   ||	

 |    Population Size Changes|	Exponential (two models), Logistic (McFarland et al., 2013)|

 |  Fitness Components||	

 |    Birth Rate|	Individually Determined from Genotype (models "Exp" and "McFL")|

@@ -345,28 +347,29 @@ found in @Diaz-Uriarte2015, where additional comments about model

 parameters and caveats are discussed.

-Are there similar programs? The Java program by @Reiter2013a offers somewhat

-similar functionality to the previous version of OncoSimulR, but it is

-restricted to at most four drivers (whereas v.1 of OncoSimulR allowed for up

-to 64), you cannot use arbitrary CBNs or OTs (or XORs or semimonotone

-graphs) to specify restrictions, there is no allowance for passengers, and a

-single type of model (a discrete time Galton-Watson process) is

-implemented. The current functionality of OncoSimulR goes well beyond the

-the previous version (and, thus, also the TPT of [@Reiter2013a]). We now

-allow you to specify all types of fitness effects in other general forward

-genetic simulators such as FFPopSim [@Zanini2012], and some that, to our

-knowledge (e.g., order effects) are not available from any genetics

-simulator. In addition, the "Lego system" to flexibly combine different

-fitness specifications is also unique; by "Lego system" I mean that we can

-combine different pieces and blocks, similarly to what we do with Lego

-bricks. (I find this an intuitive and very graphical analogy, which I have

-copied from @Hothorn_2006 and @Hothorn_2008). In a nutshell, salient

-features of OncoSimulR compared to other simulators are the unparalleled

-flexibility to specify fitness and mutator effects, with modules and order

-effects as particularly unique, and the options for sampling and stopping

-the simulations, particularly convenient in cancer evolution models. Also

-unique in this type of software is the addition of functions for simulating

-fitness landscapes and assessing evolutionary predictability.

+Are there similar programs? The Java program by @Reiter2013a, TTP, offers

+somewhat similar functionality to the previous version of OncoSimulR, but

+it is restricted to at most four drivers (whereas v.1 of OncoSimulR

+allowed for up to 64), you cannot use arbitrary CBNs or OTs (or XORs or

+semimonotone graphs) to specify restrictions, there is no allowance for

+passengers, and a single type of model (a discrete time Galton-Watson

+process) is implemented. The current functionality of OncoSimulR goes well

+beyond the the previous version (and, thus, also the TPT of

+@Reiter2013a). We now allow you to specify all types of fitness effects

+in other general forward genetic simulators such as FFPopSim

+[@Zanini2012], and some that, to our knowledge (e.g., order effects) are

+not available from any genetics simulator. In addition, the "Lego system"

+to flexibly combine different fitness specifications is also unique; by

+"Lego system" I mean that we can combine different pieces and blocks,

+similarly to what we do with Lego bricks. (I find this an intuitive and

+very graphical analogy, which I have copied from @Hothorn_2006 and

+@Hothorn_2008). In a nutshell, salient features of OncoSimulR compared to

+other simulators are the unparalleled flexibility to specify fitness and

+mutator effects, with modules and order effects as particularly unique,

+and the options for sampling and stopping the simulations, particularly

+convenient in cancer evolution models. Also unique in this type of

+software is the addition of functions for simulating fitness landscapes

+and assessing evolutionary predictability.

@@ -390,7 +393,7 @@ OncoSimulR can help address involve combinations of:

           DAGs/posets where these DAGs/posets:

 		     - Are user-specified

 	         - Generated randomly (`simOGraph`)

-        - Any mapping between genotypes and fitness:

+        - Any mapping between genotypes and fitness where this mapping is:

             - User-specified

             - Generated randomly from families of random fitness landscapes (`rfitness`)     

      - Mutation rates can:

@@ -411,12 +414,12 @@ OncoSimulR can help address involve combinations of:

     - ... and assessing the consequences of those on the observed

       genotypes and their diversity (`sampledGenotypes`) and any other

       inferences that depend on the observational process.

-	- OncoSimulR returns the genotypes at each of the sampling

-	  points, so you are not restricted by what the

-	  `samplePop` function provides.

+	- (OncoSimulR returns the abundances of all genotypes at each of

+	  the sampling points, so you are not restricted by what the

+	  `samplePop` function provides.)

-* Tracing the genealogical relationships of clones

+* Tracking the genealogical relationships of clones

   (`plotClonePhylog`) and assessing evolutionary predictability

   (`LOD`, `POM`).

@@ -428,8 +431,8 @@ OncoSimulR are discussed in section \@ref(whatfor).

 -----

 A quick overview of the main functions and their relationships is shown in

-the figure \@ref(fig:frelats), where we use italics for the type/class of R

-object and courier for the name of the functions.

+Figure \@ref(fig:frelats), where we use italics for the type/class of R

+object and courier font for the name of the functions.

 <!-- Note: figure1.png, and how to create it, explained in miscell-files -->

 <!-- in the repo -->

 <!-- ![Relationship between the main functions in OncoSimulR.](figure1.png) -->

@@ -440,21 +443,22 @@ object and courier for the name of the functions.

 knitr::include_graphics("relfunct.png")

 ```

-

+\clearpage

 ## Examples of questions that can be addressed with OncoSimulR {#whatfor}

 Most of the examples in the rest of this vignette, starting with those in

 \@ref(quickexample), focus on the mechanics. Here, we will illustrate some

-problems in cancer genomics and evolutionary genetics where OncoSimulR could

-be of help. This section does not try to provide an answer to any of these

-questions (those would be full papers by themselves) but simply to

-illustrate some kinds of questions where you can use OncoSimulR; of course,

-the possible uses of OncoSimulR are only limited by your ingenuity. Finally,

-I will only use short snippets of working code as we are limited by time of

-execution; for real work you would want to use many more scenarios and many

-more simulations, you would use appropriate statistical methods to compare

-the output of runs, etc, etc, etc.

+problems in cancer genomics and evolutionary genetics where OncoSimulR

+could be of help. This section does not try to provide an answer to any of

+these questions (those would be full papers by themselves). Instead, this

+section simply tries to illustrate some kinds of questions where you can

+use OncoSimulR; of course, the possible uses of OncoSimulR are only

+limited by your ingenuity. Here, I will only use short snippets of working

+code as we are limited by time of execution; for real work you would want

+to use many more scenarios and many more simulations, you would use

+appropriate statistical methods to compare the output of runs, etc, etc,

+etc.

 ```{r firstload}

@@ -464,10 +468,10 @@ library(OncoSimulR)

 ### Recovering restrictions in the order of accumulation of mutations {#ex-order}

-This is a question that was addressed, for instance in

+This is a question that was addressed, for instance, in

 @Diaz-Uriarte2015: do methods that try to infer restrictions in the

-order of accumulation of mutations (e.g., @Szabo2008, @Gerstung2009,

-@ramazzotti_capri_2015) work well under different evolutionary

+order of accumulation of mutations [e.g., @Szabo2008; @Gerstung2009;

+@ramazzotti_capri_2015] work well under different evolutionary

 models and with different sampling schemes? (This issue is also

 touched upon in section \@ref(sample-1)).

@@ -486,52 +490,55 @@ RNGkind("L'Ecuyer-CMRG")

 ```

 ```{r ex-dag-inf}

-## 1. Simulate a DAG

+## For reproducibility

+set.seed(2)

+RNGkind("L'Ecuyer-CMRG")

+

+## Simulate a DAG

 g1 <- simOGraph(4, out = "rT")

-## 2. Simulate two evolutionary trajectories

+## Simulate 10 evolutionary trajectories

 s1 <- oncoSimulPop(10, allFitnessEffects(g1, drvNames = 1:4),

                    mc.cores = 2, ## adapt to your hardware

                    seed = NULL) ## for reproducibility of vignette

-## 3. Sample those data uniformly, and add noise

+## Sample those data uniformly, and add noise

 d1 <- samplePop(s1, timeSample = "unif", propError = 0.1)

-## 4. You would now run the appropriate inferential method and

-## compare observed and true

+## You would now run the appropriate inferential method and

+## compare observed and true. For example

-require(Oncotree)

-fit1 <- oncotree.fit(d1)

+## require(Oncotree)

+## fit1 <- oncotree.fit(d1)

-## Now, compare fitted and original. This is well beyond the

-## scope of this document (and OncoSimulR itself).

+## Now, you'd compare fitted and original. This is well beyond 

+## the scope of this document (and OncoSimulR itself).

 ```

-```{r, echo=FALSE}

-set.seed(7)

-RNGkind("L'Ecuyer-CMRG")

+```{r hidden-rng-exochs, echo = FALSE}

+set.seed(NULL)

 ```

+

+

 ### Sign epistasis and probability of crossing fitness valleys {#ex-ochs}

-These questions, together with the next one (\@ref(ex-predict)),

-encompass a wide range of specific issues that have been addressed

-in evolutionary genetics studies and which include from detailed

-analysis of simple models with a few uphill paths and valleys as in

-@Weissman2009 or @Ochs2015, to questions that refer to larger, more

-complex fitness landscapes as in @szendro_predictability_2013 or

-@franke_evolutionary_2011 (see below).

-

-

-Using as an example @Ochs2015, we could specify the fitness

-landscape and run simulations until fixation (with argument

-`fixation` to `oncoSimulPop` ---see more details in section

-\@ref(fixation) where we also use this same model). We would then

-examine the proportion of genotypes fixed under different

-scenarios. For instance, we can use the example from @Ochs2015 (we

-will see this example also in section \@ref(ochsdesai), where we

-cover different ways of specifying fitness). And we can extend this

+This question, and the question in the next section (\@ref(ex-predict)),

+encompass a wide range of issues that have been addressed in evolutionary

+genetics studies and which include from detailed analysis of simple models

+with a few uphill paths and valleys as in @Weissman2009 or @Ochs2015, to

+questions that refer to larger, more complex fitness landscapes as in

+@szendro_predictability_2013 or @franke_evolutionary_2011 (see below).

+

+

+Using as an example @Ochs2015 (we will see this example again in

+section \@ref(ochsdesai), where we cover different ways of

+specifying fitness), we could specify the fitness landscape and run

+simulations until fixation (with argument `fixation` to

+`oncoSimulPop` ---see more details in section \@ref(fixation), again

+with this example). We would then examine the proportion

+of genotypes fixed under different scenarios. And we can extend this

 example by adding mutator genes:

@@ -541,6 +548,10 @@ RNGkind("L'Ecuyer-CMRG")

 ```

 ```{r exochs}

+## For reproducibility

+set.seed(2)

+RNGkind("L'Ecuyer-CMRG")

+

 ## Specify fitness effects. 

 ## Numeric values arbitrary, but set the intermediate genotype en

@@ -578,7 +589,8 @@ initS <- 10

 od_sim <- oncoSimulPop(10, od, muEF = odm,

                        fixation = c("u", "i, v"), initSize = initS,

                        model = "McFL",

-                       mu = 1e-4, detectionDrivers = NA, finalTime = NA,

+                       mu = 1e-4, detectionDrivers = NA, 

+					   finalTime = NA,

                        detectionSize = NA, detectionProb = NA,

                        onlyCancer = TRUE, 

 					   mc.cores = 2, ## adapt to your hardware

@@ -587,7 +599,7 @@ od_sim <- oncoSimulPop(10, od, muEF = odm,

 sampledGenotypes(samplePop(od_sim))

 ```

-```{r hidden-rng-exochs, echo = FALSE}

+```{r hidden-rng-exochs33, echo = FALSE}

 set.seed(NULL)

 ```

@@ -598,7 +610,8 @@ we would run simulations under random fitness landscapes with varied

 ruggedness, and would then examine the evolutionary predictability

 of the trajectories with measures such as "Lines of Descent" and

 "Path of the Maximum" [@szendro_predictability_2013] and the

-diversity of the sampled genotypes under different sampling regimes.

+diversity of the sampled genotypes under different sampling regimes (see

+details in section \@ref(evolpredszend)).

@@ -608,17 +621,22 @@ RNGkind("L'Ecuyer-CMRG")

 ```

 ```{r exszendro}

+## For reproducibility

+set.seed(7)

+RNGkind("L'Ecuyer-CMRG")

+

 ## Repeat the following loop for different combinations of whatever

 ## interests you, such as number of genes, or distribution of the

 ## c and sd (which affect how rugged the landscape is), or 

-## reference genotype or evolutionary model, or stopping criterion, 

-## sampling procedure, or ...

+## reference genotype, or evolutionary model, or stopping criterion, 

+## or sampling procedure, or ...

-## 1. Generate a random fitness landscape, from the Rough Mount

-##    Fuji model, with g genes, and c ("slope" constant) and

-##    reference chosen randomly. Ask for a minimal number of

-##    accessible genotypes

+##  Generate a random fitness landscape, from the Rough Mount

+##  Fuji model, with g genes, and c ("slope" constant) and

+##  reference chosen randomly (reference is random by default and 

+##  thus not specified below). Require a minimal number of  

+##  accessible genotypes

 g <- 6

 c <- runif(1, 1/5, 5)

@@ -632,20 +650,19 @@ rl <- rfitness(g, c = c, min_accessible_genotypes = g)

 ## Obtain landscape measures from Magellan. Export to Magellan

 to_Magellan(rl, file = "rl1.txt")

-## (Getting the statistics requires you to install Magellan,

-## and that requires either calling the web app 

-## (http://wwwabi.snv.jussieu.fr/public/Magellan/) or

-## asking Magellan's authors for the software. This is of course

-## beyond the scope of the example and the package.

+## (Getting the statistics from Magellan requires either 

+## calling the web app (http://wwwabi.snv.jussieu.fr/public/Magellan/) 

+## or asking Magellan's authors for the software. This is of course

+## beyond the scope of the example and the package.)

-## 3. Simulate evolution in that landscape many times (here just 5)

+## Simulate evolution in that landscape many times (here just 10)

 simulrl <- oncoSimulPop(10, allFitnessEffects(genotFitness = rl),

                         keepPhylog = TRUE, keepEvery = 1,

                         initSize = 4000,

                         seed = NULL, ## for reproducibility

                         mc.cores = 2) ## adapt to your hardware

-## 4. Obtain measures of evolutionary predictability

+## Obtain measures of evolutionary predictability

 diversityLOD(LOD(simulrl))

 diversityPOM(POM(simulrl))

 sampledGenotypes(samplePop(simulrl, typeSample = "whole"))

@@ -657,10 +674,10 @@ set.seed(NULL)

-### Mutator and antimutator genes {#ex-mut-antimut}

+### Mutator and antimutator genes {#exmutantimut}

 The effects of mutator and antimutator genes have been examined both

-in cancer genetics [@nowak_evolutionary_2006,

+in cancer genetics [@nowak_evolutionary_2006;

 @tomlinson_mutation_1996] and in evolutionary genetics

 [@gerrish_complete_2007], and are related to wider issues such as

 Muller's ratchet and the evolution of sex. There are, thus, a large

@@ -675,17 +692,17 @@ in driver genes needed to reach cancer is large and if the mutator effect is

 large.

-We might want to ask, then, how long it takes before we reach

-cancer. This is stored in the component `FinalTime` of the

-output. We would specify different numbers and effects of mutator

-genes (argument `muEF`). We would also change the criteria for

+We might want to ask, then, how long it takes before to reach cancer under

+different scenarios. Time to reach cancer is stored in the component

+`FinalTime` of the output. We would specify different numbers and effects

+of mutator genes (argument `muEF`). We would also change the criteria for

 reaching cancer and in our case we can easily do that by specifying

-different numbers in `detectionDrivers`. Of course, we would also

-want to examine the effects of varying numbers of mutators, drivers,

-and possibly fitness consequences of mutators (below we assume

-mutators are neutral and we assume there are no additional genes

-with deleterious mutations, but this need not be so, of course; see

-also [@tomlinson_mutation_1996, @gerrish_complete_2007, @McFarland2014]).

+different numbers in `detectionDrivers`. Of course, we would also want to

+examine the effects of varying numbers of mutators, drivers, and possibly

+fitness consequences of mutators. Below we assume mutators are neutral and

+we assume there are no additional genes with deleterious mutations, but

+this need not be so, of course [see also

+@tomlinson_mutation_1996; @gerrish_complete_2007; @McFarland2014].

 Let us run an example. For the sake of simplicity, we assume no

@@ -721,6 +738,11 @@ RNGkind("L'Ecuyer-CMRG")

 ```

 ```{r ex-tomlin2}

+## For reproducibility

+set.seed(2)

+RNGkind("L'Ecuyer-CMRG")

+

+

 ddr <- 4

 st <- oncoSimulPop(4, ft, muEF = mt,

                    detectionDrivers = ddr,

@@ -743,9 +765,46 @@ set.seed(NULL)

 (Incidentally, notice that it is easy to get OncoSimulR to throw an

-exception if you do not think twice about the mutator effects you are using

-and specify a huge mutation rate if all mutator genes are mutated: see

-\@(tomlin-except).)

+exception if you accidentally specify a huge mutation rate when all

+mutator genes are mutated: see section \@ref(tomlinexcept).)

+

+

+<!-- More complex example where we look at accumulation of deleterious -->

+

+<!-- ```{r r ex-tomlin3} -->

+<!-- set.seed(2) ## for reproducibility -->

+<!-- RNGkind("L'Ecuyer-CMRG") -->

+

+<!-- sd <- 0.1 ## fitness effect of drivers -->

+<!-- sp <- -0.01 ## fitness effect of mildly deleterious passengers -->

+<!-- sm <- 0 ## fitness effect of mutator -->

+<!-- nd <- 20 ## number of drivers -->

+<!-- nm <- 5  ## number of mutators -->

+<!-- np <- 50 -->

+<!-- mut <- 5 ## mutator effect -->

+

+<!-- fitnessGenesVector <- c(rep(sd, nd), rep(sm, nm), rep(sp, np)) -->

+<!-- names(fitnessGenesVector) <- 1:(nd + nm + np) -->

+<!-- mutatorGenesVector <- rep(mut, nm) -->

+<!-- names(mutatorGenesVector) <- (nd + np + 1):(nd + np + nm) -->

+

+<!-- ft <- allFitnessEffects(noIntGenes = fitnessGenesVector, -->

+<!--                         drvNames = 1:nd) -->

+<!-- mt <- allMutatorEffects(noIntGenes = mutatorGenesVector) -->

+

+<!-- ddr <- 4 -->

+<!-- st <- oncoSimulPop(4, ft, muEF = mt, -->

+<!--                    detectionDrivers = ddr, -->

+<!--                    finalTime = NA, -->

+<!--                    detectionSize = NA, -->

+<!--                    detectionProb = NA, -->

+<!--                    onlyCancer = FALSE, -->

+<!--                    keepEvery = NA,  -->

+<!--                    mc.cores = 2, ## adapt to your hardware -->

+<!--                    seed = NULL) ## for reproducibility -->

+<!-- colSums(samplePop(st, timeSample = "last", typeSample = "single"), na.rm = TRUE) -->

+<!-- ``` -->

+

@@ -787,10 +846,13 @@ fbauer <- allFitnessEffects(bauer)

 plot(b1, use_ggrepel = TRUE) ## avoid overlapping labels

 ```

-Now run simulations and examine how frequently the runs do not end

-up in extinction (for real, you would of course increase the number

-of total populations, the range of initial population sizes, model,

-mutation rate, etc):

+Now run simulations and examine how frequently the runs end up with

+population sizes larger than a pre-specified threshold; for

+instance, below we look at increasing population size 4x in the

+default maximum number of 2281 time periods (for real, you would of

+course increase the number of total populations, the range of

+initial population sizes, model, mutation rate, required population

+size or number of drivers, etc):

 ```{r hiddenbau, echo=FALSE}

@@ -799,14 +861,20 @@ RNGkind("L'Ecuyer-CMRG")

 ```

 ```{r exusagebau2}

+## For reproducibility

+set.seed(2)

+RNGkind("L'Ecuyer-CMRG")

+

 totalpops <- 5

+initSize <- 100

 sb1 <- oncoSimulPop(totalpops, fbauer, model = "Exp",

-                    initSize = 100,

+                    initSize = initSize,

                     onlyCancer = FALSE, 

 					mc.cores = 2, ## adapt to your hardware

                     seed = NULL) ## for reproducibility

-## What proportion of the simulations do not end up extinct?

-sum(summary(sb1)[, "TotalPopSize"] > 0)/totalpops

+					

+## What proportion of the simulations reach 4x initSize?

+sum(summary(sb1)[, "TotalPopSize"] > (4 * initSize))/totalpops

 ```

 ```{r hidden-rng-exbau, echo = FALSE}

@@ -814,6 +882,36 @@ set.seed(NULL)

 ```

+Alternatively, to examine how long it takes to reach cancer for a

+pre-specified size, you could look at the value of `FinalTime` as we

+did above (section \@ref(exmutantimut)) after running simulations

+with `onlyCancer = TRUE` and `detectionSize` set to some reasonable value:

+

+

+```{r hiddenbau22, echo=FALSE}

+set.seed(2)

+RNGkind("L'Ecuyer-CMRG")

+```

+

+```{r hhhhbbbb22}

+

+totalpops <- 5

+initSize <- 100

+sb2 <- oncoSimulPop(totalpops, fbauer, model = "Exp",

+                    initSize = initSize,

+                    onlyCancer = TRUE,

+					detectionSize = 10 * initSize,

+					mc.cores = 2, ## adapt to your hardware

+                    seed = NULL) ## for reproducibility

+				

+## How long did it take to reach cancer?

+unlist(lapply(sb2, function(x) x$FinalTime))

+```

+

+```{r hidden-rng-exbau22, echo = FALSE}

+set.seed(NULL)

+```

+

 #### Consequences of order effects for cancer initiation {#exorder1intro}

 Instead of focusing on different models for epistatic interactions,

@@ -829,12 +927,13 @@ order effects):

 ```{r oex1intro}

 ## Order effects involving three genes.

-## Genotype D, M has different fitness effects

+## Genotype "D, M" has different fitness effects

 ## depending on whether M or D mutated first.

+## Ditto for genotype "F, D, M".

+

+## Meaning of specification: X > Y means

+## that X is mutated before Y.

-## Genotype F, D, M has different fitness

-## depending on which of the order in which the genes

-## mutated.

 o3 <- allFitnessEffects(orderEffects = c(

                             "F > D > M" = -0.3,

@@ -863,6 +962,10 @@ RNGkind("L'Ecuyer-CMRG")

 ```

 ```{r exusageoe2}

+## For reproducibility

+set.seed(2)

+RNGkind("L'Ecuyer-CMRG")

+

 totalpops <- 5

 soe1 <- oncoSimulPop(totalpops, o3, model = "Exp",

                     initSize = 500,

@@ -880,6 +983,10 @@ set.seed(NULL)

 ```

+As we just said, alternatively, to examine how long it takes to

+reach cancer you could run simulations with `onlyCancer = TRUE` and

+look at the value of `FinalTime` as we did above (section

+\@ref(exmutantimut)).

@@ -893,27 +1000,29 @@ and \@ref(whatfor) and running time and space consumption of OncoSimulR are

 addressed in section \@ref(timings). You should be aware that **coalescent

 simulations**, sometimes also called backward-time simulations, are much

 more efficient for simulating neutral data as well as some special selection

-scenarios [@Yuan2012,@Carvajal-Rodriguez2010,@Hoban2011].  

-

-In addition, since OncoSimulR allows you to specify fitness with arbitrary

-epistatic and order effects, as well as mutator effects, you need to learn

-the syntax of how to specify those effects and you might be paying a

-performance penalty if your scenario does not require this complexity. For

-instance, in the models in @Beerenwinkel2007b or @Bozic2010, the fitness of

-a genotype depends only on the total number of drivers mutated, but not on

-which drivers are mutated (and, thus, not on the epistatic interactions nor

-the order of accumulation of the drivers). This means that the syntax for

-specifying those fitness models could probably be a lot simpler (e.g.,

-specify $s$ per driver). 

-

-But it also means that code written for just that case could probably run

-much faster. First, because fitness evaluation is easier. Second, and

-possibly much more important, because what we need to keep track of leads to

-much simpler and economic structures: we do not need to keep track of clones

-(where two cells are regarded as different clones if they differ anywhere in

-their genotype), but only of clone types as defined by the number of mutated

-drivers, and keeping track of clones can be expensive ---see sections

-\@ref(timings) and \@ref(trackindivs). 

+scenarios [@Yuan2012; @Carvajal-Rodriguez2010; @Hoban2011].  

+

+In addition, since OncoSimulR allows you to specify fitness with

+arbitrary epistatic and order effects, as well as mutator effects,

+you need to learn the syntax of how to specify those effects and you

+might be paying a performance penalty if your scenario does not

+require this complexity. For instance, in the model of

+@Beerenwinkel2007b, the fitness of a genotype depends only on the

+total number of drivers mutated, but not on which drivers are

+mutated (and, thus, not on the epistatic interactions nor the order

+of accumulation of the drivers). This means that the syntax for

+specifying that model could probably be a lot simpler

+(e.g., specify $s$ per driver).

+

+But it also means that code written for just that case could

+probably run much faster. First, because fitness evaluation is

+easier. Second, and possibly much more important, because what we

+need to keep track of leads to much simpler and economic structures:

+we do not need to keep track of clones (where two cells are regarded

+as different clones if they differ anywhere in their genotype), but

+only of clone types or clone classes as defined by the number of

+mutated drivers, and keeping track of clones can be expensive ---see

+sections \@ref(timings) and \@ref(trackindivs).

 So for those cases where you do not need the full flexibility of OncoSimulR,

 special purpose software might be easier to use and faster to run. Of

@@ -923,16 +1032,17 @@ be available, though.

-## Steps in using OncoSimulR {#steps}

+## Steps for using OncoSimulR {#steps}

 Using this package will often involve the following steps:

-1. Specify the fitness effects: sections \@ref(specfit) and \@ref(litex).

+1. Specify fitness effects: sections \@ref(specfit) and \@ref(litex).

-2. Simulate cancer progression: section \@ref(simul). You can simulate

-  for a single subject or for a set of subjects. You will need to:

+2. Simulate cancer progression: section \@ref(simul). You can

+  simulate for a single individual or subject or for a set of

+  subjects. You will need to:

     - Decide on a model. This basically amounts to choosing a model with

     exponential growth ("Exp" or "Bozic") or a model with carrying capacity

@@ -1012,7 +1122,7 @@ sv2 <- allFitnessEffects(epistasis = c("-A : B" = sb,

 evalAllGenotypes(sv2, addwt = TRUE)

 ## 2. Simulate the data. Here we use the "McFL" model and set

-##    explicitly parameters for mutation rate, initial size and size

+##    explicitly parameters for mutation rate, initial size, size

 ##    of the population that will end the simulations, etc

 RNGkind("Mersenne-Twister")

@@ -1071,7 +1181,7 @@ ep1 <- oncoSimulIndiv(sv2, model = "McFL",

 <!-- %% @  -->

-```{r iep1x1,fig.width=6.5, fig.height=4.5, fig.cap="Plot of drivers of an epistasis simulation"}

+```{r iep1x1,fig.width=6.5, fig.height=4.5, fig.cap="Plot of drivers of an epistasis simulation."}

 ## 3. We will not analyze those data any further. We will only plot

 ## them.  For the sake of a small plot, we thin the data.

 plot(ep1, show = "drivers", xlim = c(0, 1500),

@@ -1093,7 +1203,7 @@ DAG** with the

 pancreatic cancer poset in @Gerstung2011 (see more

 details in section \@ref(pancreas)):

-```{r, fig.width=5}

+```{r fepancr1, fig.width=5}

 ## 1. Fitness effects: 

 pancr <- allFitnessEffects(

     data.frame(parent = c("Root", rep("KRAS", 4), 

@@ -1107,10 +1217,14 @@ pancr <- allFitnessEffects(

                typeDep = "MN"),

     drvNames = c("KRAS", "SMAD4", "CDNK2A", "TP53", 

 	             "MLL3", "TGFBR2", "PXDN"))

+```

+```{r figfpancr1, fig.width=5, fig.cap="Plot of DAG corresponding to fitnessEffects object."}

 ## Plot the DAG of the fitnessEffects object

 plot(pancr)

 ``` 

+

+

 ```{r}

 ## 2. Simulate from it. We change several possible options. 

@@ -1172,7 +1286,7 @@ paper:

 A PDF version of this vignette is available

 from <https://rdiaz02.github.io/OncoSimul/pdfs/OncoSimulR.pdf>.  And an HTML

 version from <https://rdiaz02.github.io/OncoSimul/OncoSimulR.html>. These

-files should correspond to the most recent, github version, of the package

+files should correspond to the most recent, GitHub version, of the package

 (i.e., they might include changes not yet available from the BioConductor

 package).

@@ -1201,18 +1315,17 @@ of "experiment before launching a large number of simulations"

 applies, but here we will walk through several cases to get a

 feeling for the major factors that affect speed and size. Many of

 the comments on this section need to use ideas discussed in other

-places of this document. If you read this section first, you might

+places of this document; if you read this section first, you might

 want to come back after reading the relevant parts.

 Speed will depend on:

 * Your hardware, of course.

-* The evolutionary model: using the "McFL" model is often slower

-  (this model includes density dependence and is more complex).

+* The evolutionary model.

 * The granularity of how often you keep data (`keepEvery`

   argument). Note that the default, which is to keep as often as you

-  sample (so that we preserve all history) can lead to very slow execution

+  sample (so that we preserve all history) can lead to slow execution

   times.

 * The mutation rate, because higher mutation rates lead to more

   clones, and more clones means we need to iterate over, well, more clones,

@@ -1224,6 +1337,7 @@ Speed will depend on:

 * The stopping conditions (`detectionProb`, `detectionDrivers`,

   `detectionSize` arguments) and whether or not simulations are run until

   cancer is reached (`onlyCancer` argument).

+* Most of the above factors can interact in complex ways.

 Size of returned objects will depend on:

@@ -1430,7 +1544,7 @@ t_mc2 <- system.time(

 ``` 

-And we can obtain times, sizes of objects, and summaries of numbers

+We can obtain times, sizes of objects, and summaries of numbers

 of clones, iterations, and final times doing, for instance:

@@ -1458,7 +1572,9 @@ panderOptions("table.split.cells", 900)  ## For HTML

 ## panderOptions("table.split.cells", 8) ## For PDF

 set.alignment('right')

-panderOptions('round', 3)

+panderOptions('round', 2)

+panderOptions('big.mark', ',')

+panderOptions('digits', 2)

 pander(benchmark_1[1:4, c("Elapsed Time, average per simulation (s)", 

  	              "Object Size, average per simulation (MB)",

@@ -1468,6 +1584,7 @@ pander(benchmark_1[1:4, c("Elapsed Time, average per simulation (s)",

  				  "Total Population Size, median",

  				  "Total Population Size, max.",

  				  "keepEvery")],

+				  justify = c('left', rep('right', 8)), ##  o.w. hlines not right

 				  ## caption = "\\label{tab:bench1}Benchmarks of Exp and McFL  models using the default `detectionProb` with two settings of `keepEvery`."

 				  )

 ```

@@ -1494,16 +1611,17 @@ a sharp decrease in number of iterations and, thus, running time.