slides-wtd-2017.Rmd

---
title: "Intelligent Documents and the Verifiability Crisis in Science, Tech Writing, and Life"
author: Carl Parker
date: May 14, 2017
output: 
  ioslides_presentation:
    css: styles.css
    widescreen: true
---

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.2/jquery.min.js"></script>

<script>
    $(document).ready(function() {
    $('slide:not(.title-slide, .backdrop, .segue)').append('<footer></footer>');    
    $('footer').attr('label', "Copyright 2017 Home Box Office, Inc. All Rights Reserved.");

  })
</script>

<style>
  footer:after {
    font-size: 12pt;
    content: attr(label);
    position: absolute;
    bottom: 20px;
    left: 60px;
    line-height: 1.9;
    display: block;
  }
</style>


# Part 1: The Replication Crisis in Science

<div class="notes">
Carl, don't race through your slides.
</div>


## The Experiment Experiment   

In 2008, a team of investigators led by Brian Nosek set out to replicate
the findings from a <b>hundred</b> peer-reviewed published research
papers in the area of psychology.

NPR later referred to Nosek's work as <em>The Experiment Experiment</em>.


## {.vertical}

![](images/experiment-experiment.png)


## The Experiment Experiment 

![](images/science-experiment.png)

<div class = "notes">
<http://science.sciencemag.org/content/349/6251/aac4716>
</div>


## The Experiment Experiment  {.embiggen}

Of the 100 experiments that Nosek investigated . . .

. . . <b>61</b> could <b>not</b> be replicated.


## Further Studies...Similar Results

According to a 2016 poll of 1,500 scientists reported in the journal
Nature, <b>70%</b> of them had failed to reproduce at least one other
scientist's experiment and <b>50%</b> had failed to reproduce one of
their own experiments. 

<https://en.wikipedia.org/wiki/Replication_crisis>


## Replication Crisis

The <b>replication crisis</b> refers to a crisis in science in which the
results of many scientific experiments are difficult or impossible to
replicate, either by independent researchers or _by the original
researchers themselves_.

<https://en.wikipedia.org/wiki/Replication_crisis>


## Reproducible Research 

Roger Peng (Johns Hopkins) proposed the idea of Reproducible Research.

- <em>Replication</em>, the ability to re-enact the experiment was too high a bar.
- <em>Reproducibility</em>, the ability to reach the same conclusions given the same data and computational software.

<div class = "notes">
Reproducible Research in Computational Science, Science, Dec, 2011
</div>


## Reproducible Research 

Reproducibility requires that any published research make available both data that was collected and the code that processed the data.


## Enabling Reproducible Research

A barrier to reproducible research is that the code gets out of sync
with the published paper or the code is simply lost.

The solution was to find a way to _keep the research paper and the code
together and in sync_.


## {.embiggen-really .vertical-high}

<div class = "centered">
R
</div>


## RMarkdown and Knitr   

<b>RMarkdown</b></br>
Extensions to enable Markdown to embed executable code.

<b>Knitr</b></br>
Tool that builds the RMarkdown to various output formats.


## RMarkdown and Knitr 

![](images/knitr-process.png)


##  {.embiggen-more .vertical-high} 

<div class = "centered">
GitHub
</div>

<div class="notes">

When it is time to publish, upload the RMarkdown document and the data
a GitHub repository and reference that repository in the published
document.

</div>


## Reproducibility Ecosystem  {.embiggen}   

- RMarkdown 
- Knitr
- GitHub


## {.embiggen}

Code that supports the document is embedded in the document and is
executed when the document is built.


# Part 2: Tech Writing, Reproducibility, and Code

## A long time ago at a company not far away . . . Code Samples   

- Intel Tech Support
- Hillsboro, OR
- Year: 1988
- Email: No
- Code samples: Yes


##  Transitioning the i386 to Protected Mode

![](images/i386.png)


## Documentation and Sample Code

- Verify that the code snippets in the docs work.
- Keep the code snippets in the docs sync'd with the actual code.
- Provide the customer with enough information to <em>reproduce</em> the result.


## Definition: Byzantine

![](images/byzantine-defn-resize-150.png)


##  {.embiggen-more}

The solution is to bring the technical writing and the sample code into
a single document.


## Example: R {.codefont-med}

```{r}
n <- 5

for( i in 1:n ) {
    print( i ^ 2 )
}
```


## Language Support in Knitr  

- R
- C / C++
- Python
- Ruby
- Perl
- Bash
- And others . . .


<div class = "notes">
**Complete list of supported languages**

<http://rmarkdown.rstudio.com/authoring_knitr_engines.html#rcpp>
</div>


##  {.embiggen-more .vertical-high} 

<div class = "centered">
Knitpy
</div>


<div class="notes">

[knitpy](https://github.com/janschulz/knitpy/blob/master/README.md) 

[stitch](https://github.com/pystitch/stitch/blob/master/README.rst)

</div>


##  {.embiggen-more .vertical-high} 

<div class = "centered">
Jupyter Notebooks  
</div>


##  {.embiggen-more .vertical-high} 

<div class = "centered">
CWEB
</div>


# Part 3: Social Discourse, Misinformation, and Fake News


## {.embiggen-more .embolden .vertical-high}

Lies, Fake News, and Statistics


<div class="notes">
In recent times, I have started to feel as though I am swimming in an
ocean of misinformation.

Whenver I did in...I find the information is contaminated with spin,
misrepresentations, distortions, and just plain inaccuracies.

It becomes so frustrating.
</div>


## Lies, Fake News, and Statistics

![](images/kirk-59029681247aa891782881.gif)


## {.embiggen-more  .embolden}

<div class = "centered">
<p>Fake News</p> 
<p>vs</p> 
<p>Verifiable News</p>
</div>


## Verifiable News  {.embiggen}

- Call web services
- Access online databases 
- Scrape a website


## Example: How close was the election <em>really</em>?

What if 1% of those who votes for Donald Trump--on a state-by-state
basis had voted for Hillary Clinton instead?

We have all the information we need to answer the question and publish
the result.


```{r warning = FALSE, message = FALSE, echo = FALSE}
library(maps)
id.state <- c( 1:19, 20, 20, 20, 21, 21, 22:30, 31, 31, 31, 31, 32, 32, 32, 33:44, 45, 45, 45, 46, 46, 46, 46, 46, 47, 48, 49 )
col.state <- ifelse( id.state %% 2 == 0, "red", "blue" )
```


## Get the Electoral Votes 

![](images/electoral-votes-wikipedia-20170509.png)

<div style = "font-size: 0.55em; font-weight: bold">
<https://en.wikipedia.org/wiki/Electoral_College_(United_States)#Current_electoral_vote_distribution>
</div>


## Get the Electoral Votes  {.codefont-small}

```{r warning = FALSE, message = FALSE, echo = FALSE}
library( rvest )
```

Get the electoral votes from Wikipedia.

```{r warning = FALSE, message = FALSE}
wiki.elect.votes <- paste( 
  "https://en.wikipedia.org/wiki/Electoral_College_(United_States)",
  "#Current_electoral_vote_distribution",
  sep = "" )
```
Convert the HTML table into an R dataframe.
```{r warning = FALSE, message = FALSE}
evotes.wiki.df <- read_html( wiki.elect.votes )  %>%
  html_nodes( "table.wikitable:nth-child(103)" ) %>% 
  html_table()
```
```{r warning = FALSE, message = FALSE, echo = FALSE}
evotes.wiki.df <- evotes.wiki.df[[1]]
evotes.wiki.df <- evotes.wiki.df[ -( 20 ), ] 
names( evotes.wiki.df ) <- c( "EV", "States" )
evotes.wiki.df$EV <- strsplit( evotes.wiki.df$EV, " " )
evotes.wiki.df$EV <- unlist( lapply( evotes.wiki.df$EV, function( li ) as.numeric( unlist( li )[ 1 ] ) ) )
evotes.df <- data.frame()
```
```{r warning = FALSE, message = FALSE, echo = FALSE}
for( row.idx in 1:nrow( evotes.wiki.df ) ) {
  states.vec <- trimws( unlist( strsplit( evotes.wiki.df[ row.idx, 2 ], "," ) ) )
  evotes.df  <- rbind( evotes.df, cbind( states.vec, evotes.wiki.df[ row.idx, 1] ) )
}
names( evotes.df ) <- c( "State", "Electoral Votes" )
```

## Get the Electoral Votes {.codefont-small}

Display the first few rows of the data.

```{r warning = FALSE, message = FALSE}
knitr::kable( head( evotes.df, 3 ) )
```

## Get the Popular Vote  

![](images/google-at-cook.png)

<div style = "font-size: 0.55em; font-weight: bold">
<https://docs.google.com/spreadsheets/d/133Eb4qQmOxNvtesw2hdVns073R68EZx4SfCnP4IGQf8>
</div>


## Get the Popular Vote  {.codefont-small} 

```{r warning = FALSE, message = FALSE, echo = FALSE}
#
# --- Library Dependencies ---
#
library( magrittr )
library( dplyr )
library( ggplot2 )
library( maps )
library( googlesheets )

viz_state_affiliation <- function( state.to.party.map.df ) {
  #
  # Get the vector of names from the the "state" database.
  # Some states are duplicated.
  #
  states <- map_data( "state" )
  state.map.df <- data.frame( unique( cbind( states$region, states$subregion ) )[ , 1 ] )
  names( state.map.df ) <- c( "state.name" )

  #
  # Merge in the state-to-party mapping.
  #
  state.map.party.df <- merge( state.map.df, state.party.df )
  state.map.party.df$party <- as.character( state.map.party.df$party )

  #
  # Render
  #
  states <- map(database = "state", fill = TRUE, col = state.map.party.df$party )
}

electoral.votes.df <- read.csv( 
                        "data/electoral-college.csv",
                         header = FALSE, 
                         quote="\"",
                         sep = ",", 
                         na.strings = c( "NA", "-" ),
                         allowEscapes = TRUE,
                         strip.white  = TRUE,
                         stringsAsFactors = TRUE,
                         comment.char="#" 
                       )

names( electoral.votes.df ) <- c( "Electoral.Votes", "State" )
electoral.votes.df$State    <- gsub( "\\*", "", electoral.votes.df$State )
```

Retrieve the certified popular votes from the Cook Report's Google spreadsheet.

```{r warning = FALSE, message = FALSE, echo = TRUE}
official.gs <- gs_url( paste( "https://docs.google.com/spreadsheets/d/",
                              "133Eb4qQmOxNvtesw2hdVns073R68EZx4SfCnP4IGQf8/",
                              sep = "" ) ) 
votes.df <- official.gs %>% gs_read( range = "A12:D24", col_names = FALSE )
```
```{r warning = FALSE, message = FALSE, echo = FALSE}
swing.df   <- official.gs %>% gs_read( range = "A12:D24", col_names = FALSE ) %>% data.frame()
noswing.df <- official.gs %>% gs_read( range = "A27:D64", col_names = FALSE ) %>% data.frame()
votes.df <- rbind( swing.df, noswing.df )
names( votes.df  )<- c( "State", "Clinton", "Trump", "Other" )
votes.df$State <- gsub( "\\*", "", votes.df$State )
```

## Get the Popular Vote  {.codefont-small} 

View the first few rows.

```{r warning = FALSE, message = FALSE}
knitr::kable( head( votes.df, 3 ) )
```


## Combine with the Electoral Vote  {.codefont-small} 

Merge in the electoral vote information.

```{r}
votes.df <- merge( votes.df, electoral.votes.df )
```

## Combine with the Electoral Vote  {.codefont-small} 

View the first few rows

```{r warning = FALSE, message = FALSE}
knitr::kable( head( votes.df, 3 ) )
```


## Calculate Actual Electoral Vote Totals {.codefont-med} 

**Trump**
```{r}
sum( filter( votes.df, Trump > Clinton )$Electoral.Votes ) 
```

**Clinton**
```{r}
sum( filter( votes.df, Trump < Clinton )$Electoral.Votes ) 
```


## Map the Actual Results {.vertical}

```{r warning = FALSE, message = FALSE, echo = FALSE}
red.state  <- tolower( filter( votes.df, Trump > Clinton )$State )
blue.state <- tolower( filter( votes.df, Trump < Clinton )$State )

red.state.col  <- cbind( red.state, "red" ) 
blue.state.col <- cbind( blue.state, "blue" )  
state.party.df <- ( data.frame( rbind( red.state.col, blue.state.col ) ) )
names( state.party.df ) <- c( "state.name", "party" )
```

```{r warning = FALSE, message = FALSE, echo = FALSE, fig.align = "center", fig.height = 6, fig.width = 8}
viz_state_affiliation( state.party.df )
```

```{r echo = FALSE}
attach( votes.df )

Trump.recount   <- 0
Clinton.recount <- 0
```


## Transfer 1% of Popular Vote  {.codefont-small} 

Take one percent of President Trump's popular vote from each state.
Subtract it from his total. Add it to Hillary Clinton's total.

```{r}
Trump.one.pct <- floor( Trump * 0.01 ) 

votes.df$Trump.recount   <- Trump   - Trump.one.pct 
votes.df$Clinton.recount <- Clinton + Trump.one.pct 
```

```{r echo = FALSE}
Winner <- ifelse( Trump.recount > Clinton.recount, "Trump", "Clinton" ) 

detach( votes.df )
```


## {.embiggen .vertical}

The following states flip: 

- Michigan
- Pennsylvania
- Wisconsin


## Map the Recount {.vertical}

```{r warning = FALSE, message = FALSE, echo = FALSE}
red.state  <- tolower( filter( votes.df, Trump.recount > Clinton.recount )$State )
blue.state <- tolower( filter( votes.df, Trump.recount < Clinton.recount )$State )


red.state.col  <- cbind( red.state, "red" ) 
blue.state.col <- cbind( blue.state, "blue" )  
state.party.df <- ( data.frame( rbind( red.state.col, blue.state.col ) ) )
names( state.party.df ) <- c( "state.name", "party" )
```

```{r warning = FALSE, message = FALSE, echo = FALSE, fig.align = "center", fig.height = 6, fig.width = 8}
viz_state_affiliation( state.party.df )
```


## Calculate Hypothetical Electoral Vote Totals  {.codefont-med} 


**Trump**
```{r}
sum( filter( votes.df, Trump.recount > Clinton.recount )$Electoral.Votes ) 
```

**Clinton**
```{r}
sum( filter( votes.df, Trump.recount < Clinton.recount )$Electoral.Votes ) 
```


# Epilogue

## Nate Silver & FiveThirtyEight            {.embiggen}

What A Difference 2 Percentage Points Makes 

<div style = "font-size: 0.55em; font-weight: bold">
<https://fivethirtyeight.com/features/what-a-difference-2-percentage-points-makes/>
</div>


## {.embiggen .vertical}

<div class = "centered">
The source code is real

<div style = "font-size: 0.55em">
(A.J. Rossini)
</div>
</div>