the DALY Calculator
a generic tool for stochastic DALY calculation in R

The strength of the implementation of the DALY Calculator is that its results can be directly manipulated from within the R environment. This allows users to obtain virtually any possible numerical or graphical output they desire. Of course, this also requires a more advanced knowledge of the R programming language. Some examples might therefore be useful.

## Obtaining DALY Calculator output

Instead of clicking the button in the DALY Calculator main window, the DALY calculation process may also be invoked by calling the `getDALY()` function from the R console. This function initiates the Monte Carlo simulation process, and returns the simulated DALYs, YLDs, YLLs and incident cases and deaths. Of course, this will only take place if the data have been entered, as outlined before.

The `getDALY()` function takes two arguments, `aw` and `dr`, that specify the age weighting constant and time discount rate, respectively. If these values are not specified, they will be taken from the GUI.

The results of the DALY calculation process can be stored in an object, say `x`, as follows:

````x <- getDALY()`
```

Since `aw` and `dr` were not specified, these values were taken from the GUI. If you would wish to specify the social weighting values directly from the command-line, the values from the GUI will be over-ruled. For instance, you could specify to use no age weighting and a 3% time discount rate as follows:

````x <- getDALY(aw = FALSE, dr = 0.03)`
```

## Structure of the object returned by getDALY()

The `getDALY()` function returns an object of class `'DALY'`, which inherits from class `'list'`. The returned object is a list containing the following elements:

 `i` For each outcome i, an unnamed list containing simulated DALYs, YLDs, YLLs and incident cases and deaths, per age/sex class; `pop` A matrix containing the population data; `name` The name of the disease.

Each list of simulated results for a certain outcome i contains the following six elements:

 `DALY` 3-dimensional array of simulated DALYs; `YLD` 3-dimensional array of simulated YLDs; `YLL` 3-dimensional array of simulated YLLs; `cases` 3-dimensional array of simulated incident cases; `deaths` 3-dimensional array of simulated deaths; `name` The name of the outcome; `input` A list containing the simulated samples (arranged in 3-dimensional arrays) from all input distributions.

The three dimensions of `DALY`, `YLD`, `YLL`, `cases`, `deaths` and the `input` elements, are, respectively, iteration, age group, and sex.

The `input` element is a list of eight arrays, named as follows:

 `inc` incidence rate; `trt` proportion treated; `ons` age at disease onset; `dur` disease duration; `DWt` disability weight for treated cases; `DWn` disability weight for non-treated cases; `mrt` mortality rate; `dth` age at death.

To view the structure of the returned object, call the following command from the R console:

````str(x)`
```

## Methods for objects of class 'DALY'

Six methods have been made available for the objects of class `'DALY'`:

``````print(x, relative = FALSE, outcomes = FALSE,
prob = 0.95, digits = 0, ...)

summary(object, relative = FALSE, outcomes = FALSE,
digits = 0, ...)

aggregate(x, by = c("total", "class", "outcome"), ...)

hist(x, xval = c("DALY", "YLD", "YLL", "cases", "deaths"),
prob = 0.95, central = c("mean", "median"),
breaks = 25, fill = "grey95", ...)

plot(x, prob = 0.95, sort = TRUE, names = NULL,
bars = TRUE, col = c("grey90", "white"),
error_bars = TRUE, eb_col = "black",
grid = TRUE, ...)

scatterplot(x, plot = c("DALY", "YLD", "YLL"), outcomes = TRUE,
per = 1000, samples = 1000, pch = 16, col = NULL, legend = NULL,
legend_pos = c("topright", "topleft", "bottomright", "bottomleft"),
...)```
```

The `aggregate()` method is a utility function used to sum up simulated results by outcome, age/sex, or both (controlled by argument `by`). This method returns a list of aggregated DALYs, YLDs, YLLs, incident cases and deaths, as well as the population matrix and disease name.

``````# sum over outcomes and age/sex classes
aggregate(x, by = "total")

# aggregate by age/sex class, sum over outcomes
aggregate(x, by = "class")

# aggregate by outcome, sum over age/sex class
aggregate(x, by = "outcome")```
```

For more info on these methods, please visit the R help pages or consult the DALY Calculator manual.

## Handling objects of class 'DALY'

Each of the elements from `x` may be extracted using the `[[` operator. Named elements may also be extracted using the `\$` operator.

For example, we can use the following equivalent calls to view the population matrix:

``````x[["pop"]]
x\$pop```
```

Likewise, the simulated DALYs due to, for example, outcome 1, may be extracted as follows (note the double indexing):

``````x[][["DALY"]]
x[]\$DALY```
```

For more info and examples, please visit the R help pages or consult the DALY Calculator manual.