---
title: "Using mosaic's favstats()"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Using mosaic's favstats()}
  %\usepackage[utf8]{inputenc}
---


# Preliminaries

`favstats()` comes from the `mosaic` package and we will use some data from the `tigerstats` package, so make sure that both are loaded:

```{r, message=FALSE}
require(mosaic)
require(tigerstats)
```

In this tutorial we will work with the `m111survey` data frame from `tigerstats` package.  If you are not yet familiar with this data, then run:

```{r, eval=FALSE}
data(m111survey)
View(m111survey)
help(m111survey)
```

Remember that you can also learn about the types of each variable in the data frame with the `str()` function:

```{r}
str(m111survey)
```


# Studying One Numerical Variable

"favstats" is short for "favorite statistics":  it will give you the some of the most popular summary statistics for numerical variables.

Suppose, for example, that you want to know how fast people in the `m111survey` sample tend to drive, when they drive their fastest. The you want to study the numerical variable **fastest**:  the fastest speed each person claims to have ever driven, measured in miles per hour.  Just try `favstats()` with the usual formula-data input:

```{r}
favstats(~fastest, data = m111survey)
```

Remember what each of the statistics tells you:

* The minimum fastest speed drive by anyone in the survery was 60 mph.
* The maximum fastest speed was 190 mph.
* About 25% of the survey participants drove less than 90.5 mph (the First Quartile)
* About 75% percent of the survey participants drove less than 119.5 mph (the Third Quartile)
* About 50% of the participants drove less than 102 mph (the median)
* The mean speed for this sample of students was about 105.9 mph ...
* ... give or take about 20.9 mph or so (the standard deviation).

We also see that

* 71 people answered the question about fastest speed;
* Nobody did not answer (missing = 0).


# Studying the Relationship Between a Numerical Variable and a Factor Variable

Studying the relationship between a numerical variable and factor variable involves what is popularly known as "breaking the data into groups" based on the values of the factor variable.  More formally, we obtain the conditional distributions of the numerical variable given the various possible values of the factor variable, and look for difference between these distributions.  If we see large differences. then we know that the factor variable "makes a difference" in the likely values of the numerical variable, i.e., the two variable are related.

For example we might want to know if the fastest speed one drives might be related to one's sex.  The relevant variables in `m111survey` are then the numerical **fastest** and the factor variable **sex**.

In formula-data input for `favstats()` the formula always follows the format:

$$numerical \sim factor.$$

So we run the following command:

```{r}
favstats(fastest~sex, data = m111survey)
```

The first row of the output gives a summary of the conditional distribution of **fastest**, given that **sex** is female.

The second row summarizes the conditional distribution of **fastest**, given that **sex** is male.

The two conditional distribution are not the same.  For example, we see that on average females drove about 100 mph, whereas the guys drove about 113.4 mph.  The guys appear to drive faster than the gals:  for this sample of students, fastest speed drive does indeed appear to be related to sex.


# Limiting the Output

Sometimes you want just a few of the numbers from `favstats()`.  If you would like to display only those numbers you can do so using brackets "[" and "]", along with a list of the names of the columns you want to see.  For example, to display only the means and the standard deviations for **fastest**, ask for:

```{r}
favstats(~fastest, data=m111survey)[c("mean","sd")]
```

The brackets are R's way of locating particular parts of an object.  If you want to display more than one column, make sure to combine their names (in quotes) in a list with the `c()` function, as shown above.

When you are breaking a numerical variable into groups, you will probably also want to see the group names:  this requires the addition of the column named for the factor variable in question.  Therefore, to see just the mean and the standard deviation for **fastest** broken down by **sex**, ask for:


```{r}
favstats(fastest~sex, data = m111survey)[c("sex","mean","sd")]
```



# Warning

`favstats()` specializes in numerical variables:  it does not like being used to study a factor variable by itself.  Look what happens if you try to use it to study the factor variable **sex**:

```{r, error=TRUE, purl = FALSE}
favstats(~sex, data = m111survey)
```

`favstats()` converted the factor variable to a numeric variable and tried to give you some useful information based on that conversion, but elements of the output (especially the mean and the standard deviation) are meaningless in the context of factor variables.  In order to study a factor variable you really should look instead at functions like `xtabs()`.
