README.qmd

---
format: gfm
---

```{r}
#| label: setup
#| echo: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

```{=markdown}
[![R-CMD-check](https://github.com/USCCANA/netdiffuseR/actions/workflows/r.yml/badge.svg)](https://github.com/USCCANA/netdiffuseR/actions/workflows/r.yml)
[![codecov.io](https://codecov.io/github/USCCANA/netdiffuseR/coverage.svg?branch=master)](https://app.codecov.io/github/USCCANA/netdiffuseR?branch=master)
[![](https://cranlogs.r-pkg.org/badges/netdiffuseR)](https://cran.r-project.org/package=netdiffuseR)
[![CRAN\_Status\_Badge](https://www.r-pkg.org/badges/version/netdiffuseR)](https://cran.r-project.org/package=netdiffuseR)
[![](https://cranlogs.r-pkg.org/badges/grand-total/netdiffuseR)](https://cran.r-project.org/package=netdiffuseR)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1039317.svg)](https://doi.org/10.5281/zenodo.1039317)
[![Dependencies](https://tinyverse.netlify.app/badge/netdiffuseR)](https://cran.r-project.org/package=netdiffuseR)
[![USC's Department of Preventive Medicine](https://raw.githubusercontent.com/USCbiostats/badges/master/tommy-uscprevmed-badge.svg)](https://keck.usc.edu/cana/)
```

<h1>netdiffuseR: Analysis of Diffusion and Contagion Processes on Networks<img src="man/figures/netdiffuser-logo.svg" style="max-width:200px;width:50%;" align="right"></h1>

This package contains functions useful for analyzing network data for diffusion of innovations applications.

The package was developed as part of the paper Thomas W. Valente, Stephanie R.
Dyal, Kar-Hai Chu, Heather Wipfli, Kayo Fujimoto, *Diffusion of innovations theory applied to global tobacco control treaty ratification*,
Social Science & Medicine, Volume 145, November 2015, Pages 89-97, ISSN 0277-9536
(available [here](https://doi.org/10.1016/j.socscimed.2015.10.001)).

From the description:

> Empirical statistical analysis, visualization and simulation
    of diffusion and contagion processes on networks. The package implements
    algorithms for calculating network diffusion statistics such as transmission
    rate, hazard rates, exposure models, network threshold levels, infectiousness
    (contagion), and susceptibility. The package is inspired by work published in
    Valente, et al., (2015); Valente (1995), Myers (2000), Iyengar and others
    (2011), Burt (1987); among
    others.
  
__Acknowledgements__:  netdiffuseR was created with the support of grant R01 CA157577 from the National Cancer Institute/National Institutes of Health. 

```{r, comment = ""}
citation(package="netdiffuseR")
```

## News

Changelog can be view [here](NEWS.md).

## Installation

### CRAN version

To get the CRAN (stable) version of the package, simple type

```r
install.packages("netdiffuseR")
```

### Bleeding edge version

If you want the latest (unstable) version of __netdiffuseR__, using the `remotes` package, you can install `netdiffuseR` dev version as follows

```r
remotes::install_github('USCCANA/netdiffuseR', build_vignettes = TRUE)
```

You can skip building vignettes by setting `build_vignettes = FALSE` (so it is not required). You can also get the package (pre-built binaries) from our R-Universe repository (recommended):

```r
install.packages(
  'epiworldR',
  repos = c(
    'https://uofuepibio.r-universe.dev',
    'https://cloud.r-project.org'
  )
)
```

## Tutorials

Since starting netdiffuseR, we have done a couple of workshops at Sunbelt and NASN. Past and current workshops can be found at <https://github.com/USCCANA/netdiffuser-workshop>

## Presentations

* ic2s2 2016 Evanston, IL: https://github.com/USCCANA/netdiffuser-ic2s22016 (poster)
* useR! 2016 Stanford, CA: https://github.com/USCCANA/netdiffuser-user2016 (slides)
* useR! 2016: https://github.com/USCCANA/netdiffuser-user2016

## Examples

This example has been taken from the package's vignettes:


```{r loading}
library(netdiffuseR)
```

### Infectiousness and Susceptibility

```{r plot_infectsuscept}
# Generating a random graph
set.seed(1234)
n <- 100
nper <- 20
graph <- rgraph_er(n, nper, .5)
toa <- sample(c(1:(1+nper-1), NA), n, TRUE)
head(toa)

# Creating a diffnet object
diffnet <- as_diffnet(graph, toa)
diffnet
summary(diffnet)

# Visualizing distribution of suscep/infect
out <- plot_infectsuscep(diffnet, bins = 20,K=5, logscale = FALSE, h=.01)
out <- plot_infectsuscep(diffnet, bins = 20,K=5, logscale = TRUE,
                         exclude.zeros = TRUE, h=1)
```

### Threshold

```{r BoringThreshold, fig.height=7}
# Generating a random graph
set.seed(123)
diffnet <- rdiffnet(500, 20,
                    seed.nodes = "random",
                    rgraph.args = list(m=3),
                    threshold.dist = function(x) runif(1, .3, .7))
diffnet

# Threshold with fixed vertex size
plot_threshold(diffnet)
```

Using more features

```{r NiceThreshold, cache=FALSE}
data("medInnovationsDiffNet")
set.seed(131)
plot_threshold(
  medInnovationsDiffNet,
  vertex.color     = viridisLite::inferno(4)[medInnovationsDiffNet[["city"]]],
  vertex.sides     = medInnovationsDiffNet[["city"]] + 2,
  sub = "Note: Vertices' sizes and shapes given by degree and city respectively",
  jitter.factor = c(1,1), jitter.amount = c(.25,.025)
)
```


### Adoption rate

```{r Adopters}
plot_adopters(diffnet)
```


### Hazard rate

```{r Hazard}
hazard_rate(diffnet)
```


### Diffusion process

```{r plot_diffnet, fig.width=7, fig.height=4, message=FALSE}
plot_diffnet(medInnovationsDiffNet, slices=c(1,9,8))
```

```{r plot_diffnet2}
diffnet.toa(brfarmersDiffNet)[brfarmersDiffNet$toa >= 1965] <- NA
plot_diffnet2(brfarmersDiffNet, vertex.size = "indegree")
```

```{r plot_diffnet2-withmap}
set.seed(1231)

# Random scale-free diffusion network
x <- rdiffnet(1000, 4, seed.graph="scale-free", seed.p.adopt = .025,
                           rewire = FALSE, seed.nodes = "central",
                           rgraph.arg=list(self=FALSE, m=4),
                           threshold.dist = function(id) runif(1,.2,.4))

# Diffusion map (no random toa)
dm0 <- diffusionMap(x, kde2d.args=list(n=150, h=1), layout=igraph::layout_with_fr)

# Random
diffnet.toa(x) <- sample(x$toa, size = nnodes(x))

# Diffusion map (random toa)
dm1 <- diffusionMap(x, layout = dm0$coords, kde2d.args=list(n=150, h=.5))

oldpar <- par(no.readonly = TRUE)
col <- viridisLite::plasma(100)
par(mfrow=c(1,2), oma=c(1,0,0,0), cex=.8)
image(dm0, col=col, main="Non-random Times of Adoption\nAdoption from the core.")
image(dm1, col=col, main="Random Times of Adoption")
par(mfrow=c(1,1))
mtext("Both networks have the same distribution on times of adoption", 1,
      outer = TRUE)
par(oldpar)
```

### Adopters classification

```{r mosaic}
out <- classify(kfamilyDiffNet, include_censored = TRUE)
ftable(out)

# Plotting 
oldpar <- par(no.readonly = TRUE)
par(xpd=TRUE)
plot(out, color=viridisLite::inferno(5), las = 2, xlab="Time of Adoption",
     ylab="Threshold", main="")

# Adding key
legend("bottom", legend = levels(out$thr), fill=viridisLite::inferno(5), horiz = TRUE,
       cex=.6, bty="n", inset=c(0,-.1))
par(oldpar)
```


### Session info

```{r Showing session info}
sessionInfo()
```


## To-do list

- Import/Export functions for interfacing other package's clases, in particular: `statnet` set (specially the packages `networkDynamic` and `ndtv`), ~~`igraph`~~ and `Rsiena`.
- Populate the tests folder.
- ~~Use spells? (`select_egoalter` would use this)~~
- ~~Classify individuals by adoption category using early adopters, adopters, and laggards, and by threshold using very low, low, high and very high threshold (Valente 95' p. 94).~~
- ~~Double check all functions using adjacency matrix values.~~
- ~~Remove dimnames from matrices and vectors. It is more efficient to use the ones stored in meta instead.~~
- Implement the Bass model
- ~~Include function to import survey data (as shown on the vignettes)~~
- Exposure based on Mahalanobis distances and also Roger Leenders on weighting exposure (internal note).
- (2016-03-30): use `xspline` for drawing polygons & edges.
- ~~(2016-04-04): Add more options to `exposure`, namely, `self` (so removes diagonal or not!).~~
- (2016-04-19): animal behaviorists.
- (2016-10-18): Review language throughout the manual (more than innovation).
- (2016-10-18): Evaluate and eventually use a standard graph format (`network` for instance?).
- (2016-10-18): Standarize graph plot methods (choose either statnet/igraph/own)