README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

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

<!-- badges: start -->
[![Travis build status](https://travis-ci.org/f0nzie/rTorch.svg?branch=master)](https://travis-ci.org/f0nzie/rTorch)
[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/github/f0nzie/rTorch?branch=master&svg=true)](https://ci.appveyor.com/project/f0nzie/rTorch)
<!-- badges: end -->

# rTorch

The goal of `rTorch` is providing an R wrapper to [PyTorch](https://pytorch.org/. We have borrowed ideas and code used in R [tensorflow](https://github.com/rstudio/tensorflow) to implement `rTorch`.

Besides the module `torch`, which provides `PyTorch` methods, classes and functions, the package also provides `numpy` as a method called `np`, and `torchvision`, as well. The dollar sign `$` after the module will provide you access to those objects.


## Installation
`rTorch` is available in GitHub only at this moment.

Install `rTorch` with: 

`devtools::install_github("f0nzie/rTorch")`

Before start running `rTorch`, install a Python Anaconda environment first. 

1. Create a conda environment with `conda create -n myenv python=3.7`

2. Activate the new environment with `conda activate myenv`

3. Install PyTorch related packages with:  

`conda install python=3.6.6 pytorch-cpu torchvision-cpu matplotlib pandas -c pytorch`


Now, you can load `rTorch` in R or RStudio.

The automatic installation, like in `rtensorflow`, may be available later.

**Note.** `matplotlib` and `pandas` are not really necessary, but I was asked if `matplotlib` or `pandas` would in PyTorch, that I decided to put them for testing and experimentation. They both work.



## Matrices and Linear Algebra

There are five major type of Tensors in PyTorch

```{r}
library(rTorch)

bt <- torch$ByteTensor(3L, 3L)
ft <- torch$FloatTensor(3L, 3L)
dt <- torch$DoubleTensor(3L, 3L)
lt <- torch$LongTensor(3L, 3L)
Bt <- torch$BoolTensor(5L, 5L)

ft
dt
Bt
```

A 4D tensor like in MNIST hand-written digits recognition dataset:

```{r}
mnist_4d <- torch$FloatTensor(60000L, 3L, 28L, 28L)

# size
mnist_4d$size()

# length
length(mnist_4d)

# shape, like in numpy
mnist_4d$shape

# number of elements
mnist_4d$numel()
```

A 3D tensor:

```{r}
ft3d <- torch$FloatTensor(4L, 3L, 2L)
ft3d
```

```{r}
# get first element in a tensor
ft3d[1, 1, 1]
```


```{r}
bt
# [torch.ByteTensor of size 3x3]
```

```{r}
ft
# [torch.FloatTensor of size 3x3]
```


```{r}
# create a tensor with a value
torch$full(list(2L, 3L), 3.141592)
```


## Basic Tensor Operations

### Add tensors

```{r}
# add a scalar to a tensor
# 3x5 matrix uniformly distributed between 0 and 1
mat0 <- torch$FloatTensor(3L, 5L)$uniform_(0L, 1L)
mat0 + 0.1
```

> The expression ``tensor.index(m)`` is equivalent to ``tensor[m]``.

```{r}
# add an element of tensor to a tensor
# fill a 3x5 matrix with 0.1
mat1 <- torch$FloatTensor(3L, 5L)$uniform_(0.1, 0.1)
# a vector with all ones
mat2 <- torch$FloatTensor(5L)$uniform_(1, 1)
mat1[1, 1] + mat2
```

```{r}
# add two tensors
mat1 + mat0
```


```{r}
# PyTorch add two tensors
x = torch$rand(5L, 4L)
y = torch$rand(5L, 4L)

print(x$add(y))
print(x + y)
```

### Multiply tensor by scalar

```{r}
# Multiply tensor by scalar
tensor = torch$ones(4L, dtype=torch$float64)
scalar = np$float64(4.321)
print(scalar)
print(torch$scalar_tensor(scalar))
(prod = torch$mul(tensor, torch$scalar_tensor(scalar)))
```

```{r}
# short version using generics
(prod = tensor * scalar)
```



## NumPy and PyTorch
`numpy` has been made available as a module in `rTorch`. We can call functions from `numpy` refrerring to it as `np$_a_function`. Examples:

```{r}
# a 2D numpy array  
syn0 <- np$random$rand(3L, 5L)
syn0
```


```{r}
# numpy arrays of zeros
syn1 <- np$zeros(c(5L, 10L))
syn1
```

```{r}
# add a scalar to a numpy array
syn1 = syn1 + 0.1
syn1
```


```{r}
# in numpy a multidimensional array needs to be defined with a tuple
# in R we do it with a vector
l1 <- np$ones(c(5L, 5L))
l1
```


```{r}
# vector-matrix multiplication
np$dot(syn0, syn1)
```

```{r}
# build a numpy array from three R vectors
X <- np$array(rbind(c(1,2,3), c(4,5,6), c(7,8,9)))
X
```

```{r}
# transpose the array
np$transpose(X)
```

```{r}
# as_tensor. Modifying tensor modifies numpy object as well
a = np$array(list(1, 2, 3))
t = torch$as_tensor(a)
print(t)

torch$tensor(list( 1,  2,  3))
t[1L]$fill_(-1)
print(a)
```


## Create tensors

```{r}
# a random 1D tensor
ft1 <- torch$FloatTensor(np$random$rand(5L))
ft1
```

```{r}
# tensor as a float of 64-bits
ft2 <- torch$as_tensor(np$random$rand(5L), dtype= torch$float64)
ft2
```


```{r}
# convert tensor to float 16-bits
ft2_dbl <- torch$as_tensor(ft2, dtype = torch$float16)
ft2_dbl
```


Create a tensor of size (5 x 7) with uninitialized memory:

```{r}
a <- torch$FloatTensor(5L, 7L)
print(a)
```

```{r}
# using arange to create tensor. starts from 0
v = torch$arange(9L)
(v = v$view(3L, 3L))
```


## Distributions

Initialize a tensor randomized with a normal distribution with mean=0, var=1:

```{r}
a  <- torch$randn(5L, 7L)
print(a)
print(a$size())
```

### Uniform matrix

```{r}
library(rTorch)

# 3x5 matrix uniformly distributed between 0 and 1
mat0 <- torch$FloatTensor(3L, 5L)$uniform_(0L, 1L)

# fill a 3x5 matrix with 0.1
mat1 <- torch$FloatTensor(3L, 5L)$uniform_(0.1, 0.1)

# a vector with all ones
mat2 <- torch$FloatTensor(5L)$uniform_(1, 1)

mat0
mat1
```

### Binomial distribution

```{r}
Binomial <- torch$distributions$binomial$Binomial

m = Binomial(100, torch$tensor(list(0 , .2, .8, 1)))
(x = m$sample())
```

```{r}
m = Binomial(torch$tensor(list(list(5.), list(10.))), 
             torch$tensor(list(0.5, 0.8)))
(x = m$sample())
```

### Exponential distribution

```{r}
Exponential <- torch$distributions$exponential$Exponential

m = Exponential(torch$tensor(list(1.0)))
m$sample()  # Exponential distributed with rate=1
```

### Weibull distribution

```{r}
Weibull <- torch$distributions$weibull$Weibull

m = Weibull(torch$tensor(list(1.0)), torch$tensor(list(1.0)))
m$sample()  # sample from a Weibull distribution with scale=1, concentration=1

```


## Tensor data types

```{r}
# Default data type
torch$tensor(list(1.2, 3))$dtype  # default for floating point is torch.float32
```

```{r}
# change default data type to float64
torch$set_default_dtype(torch$float64)
torch$tensor(list(1.2, 3))$dtype         # a new floating point tensor
```



This is a very common operation in machine learning:

```{r}
# convert tensor to a numpy array
a = torch$rand(5L, 4L)
b = a$numpy()
print(b)
```

```{r}
# convert a numpy array to a tensor
np_a = np$array(c(c(3, 4), c(3, 6)))
t_a = torch$from_numpy(np_a)
print(t_a)
```


## Tensor resizing

```{r}
x = torch$randn(2L, 3L)            # Size 2x3
y = x$view(6L)                    # Resize x to size 6
z = x$view(-1L, 2L)                # Size 3x2
print(y)
print(z)
```

### concatenate tensors

```{r}
# concatenate tensors
x = torch$randn(2L, 3L)
print(x)

# concatenate tensors by dim=0"
torch$cat(list(x, x, x), 0L)

# concatenate tensors by dim=1
torch$cat(list(x, x, x), 1L)
```


```{r}
# 0 1 2
# 3 4 5
# 6 7 8
v = torch$arange(9L)
(v = v$view(3L, 3L))
```


### Reshape tensors

```{r}
# ----- Reshape tensors -----
img <- torch$ones(3L, 28L, 28L)
print(img$size())

img_chunks <- torch$chunk(img, chunks = 3L, dim = 0L)
print(length(img_chunks))

# 1st chunk member
img_chunk_1 <- img_chunks[[1]]
print(img_chunk_1$size())
print(img_chunk_1$sum())

# 2nd chunk member
img_chunk_1 <- img_chunks[[2]]
print(img_chunk_1$size())
print(img_chunk_1$sum())


# index_select. get layer 1
indices = torch$tensor(c(0L))
img2 <- torch$index_select(img, dim = 0L, index = indices)
print(img2$size())
print(img2$sum())

# index_select. get layer 2
indices = torch$tensor(c(1L))
img2 <- torch$index_select(img, dim = 0L, index = indices)
print(img2$size())
print(img2$sum())

# index_select. get layer 3
indices = torch$tensor(c(2L))
img2 <- torch$index_select(img, dim = 0L, index = indices)
print(img2$size())
print(img2$sum())
```



## Special tensors

### Identity matrix

```{r}
# identity matrix
eye = torch$eye(3L)              # Create an identity 3x3 tensor
print(eye)
```

### Ones

```{r}
(v = torch$ones(10L))              # A tensor of size 10 containing all ones
(v = torch$ones(2L, 1L, 2L, 1L))      # Size 2x1x2x1

```

```{r}
v = torch$ones_like(eye)     # A tensor with same shape as eye. Fill it with 1.
v
```

### Zeros

```{r}
(z = torch$zeros(10L))             # A tensor of size 10 containing all zeros
```


## Tensor fill

```{r}
(v = torch$ones(3L, 3L))
v[1L, ]$fill_(2L)         # fill row 1 with 2s
v[2L, ]$fill_(3L)         # fill row 2 with 3s
print(v)
```

```{r}
# Initialize Tensor with a range of value
v = torch$arange(10L)             # similar to range(5) but creating a Tensor
(v = torch$arange(0L, 10L, step = 1L))  # Size 5. Similar to range(0, 5, 1)
```


### Initialize a linear or log scale Tensor

```{r}
# Initialize a linear or log scale Tensor

# Create a Tensor with 10 linear points for (1, 10) inclusively
(v = torch$linspace(1L, 10L, steps = 10L)) 

# Size 5: 1.0e-10 1.0e-05 1.0e+00, 1.0e+05, 1.0e+10
(v = torch$logspace(start=-10L, end = 10L, steps = 5L)) 
```


### Inplace / Out-of-place

```{r}
a$fill_(3.5)
# a has now been filled with the value 3.5

# add a scalar to a tensor
b <- a$add(4.0)

# a is still filled with 3.5
# new tensor b is returned with values 3.5 + 4.0 = 7.5

print(a)
print(b)
```

```{r, eval=FALSE}
# this will throw an error because we don't still have a function for assignment
a[1, 1] <- 7.7
print(a)
# Error in a[1, 1] <- 7.7 : object of type 'environment' is not subsettable
```


Some operations like`narrow` do not have in-place versions, and hence, `.narrow_` does not exist. Similarly, some operations like `fill_` do not have an out-of-place version, so `.fill` does not exist.

```{r}
# a[[0L, 3L]]
a[1, 4]
```

## Access to tensor elements

```{r}
# replace an element at position 0, 0
(new_tensor = torch$Tensor(list(list(1, 2), list(3, 4))))

print(new_tensor[1L, 1L])
new_tensor[1L, 1L]$fill_(5)
print(new_tensor)   # tensor([[ 5.,  2.],[ 3.,  4.]])
```

```{r}
# access an element at position 1, 0
print(new_tensor[2L, 1L])           # tensor([ 3.])
print(new_tensor[2L, 1L]$item())    # 3.
```

```{r}
# Select indices
x = torch$randn(3L, 4L)
print(x)

# Select indices, dim=0
indices = torch$tensor(list(0L, 2L))
torch$index_select(x, 0L, indices)

# "Select indices, dim=1
torch$index_select(x, 1L, indices)
```


```{r}
# Take by indices
src = torch$tensor(list(list(4, 3, 5),
                        list(6, 7, 8)) )
print(src)
print( torch$take(src, torch$tensor(list(0L, 2L, 5L))) )
```

## Tensor operations

### cross product
```{r}
m1 = torch$ones(3L, 5L)
m2 = torch$ones(3L, 5L)
v1 = torch$ones(3L)
# Cross product
# Size 3x5
(r = torch$cross(m1, m2))
```

### Dot product

```{r}
# Dot product of 2 tensors
# Dot product of 2 tensors

p <- torch$Tensor(list(4L, 2L))
q <- torch$Tensor(list(3L, 1L))                   

(r = torch$dot(p, q)) # 14
(r <- p %.*% q)
```


## Logical operations

```{r}
m0 = torch$zeros(3L, 5L)
m1 = torch$ones(3L, 5L)
m2 = torch$eye(3L, 5L)

print(m1 == m0)
```

```{r}
print(m1 != m1)
```

```{r}
print(m2 == m2)
```


```{r}
# AND
m1 & m1
```

```{r}
# OR
m0 | m2
```

```{r}
# OR
m1 | m2
```

```{r}
# all_boolean <- function(x) {
#   # convert tensor of 1s and 0s to a unique boolean
#   as.logical(torch$all(x)$numpy())
# }

# tensor is less than
A <- torch$ones(60000L, 1L, 28L, 28L)
C <- A * 0.5

# is C < A
all(torch$lt(C, A))
all(C < A)
# is A < C
all(A < C)
```

```{r}
# tensor is greater than
A <- torch$ones(60000L, 1L, 28L, 28L)
D <- A * 2.0
all(torch$gt(D, A))
all(torch$gt(A, D))
```


```{r}
# tensor is less than or equal
A1 <- torch$ones(60000L, 1L, 28L, 28L)
all(torch$le(A1, A1))
all(A1 <= A1)

# tensor is greater than or equal
A0 <- torch$zeros(60000L, 1L, 28L, 28L)
all(torch$ge(A0, A0))
all(A0 >= A0)

all(A1 >= A0)
all(A1 <= A0)
```

### Logical NOT

```{r}
all_true <- torch$BoolTensor(list(TRUE, TRUE, TRUE, TRUE))
all_true

# logical NOT
not_all_true <- !all_true
not_all_true
```

```{r}
diag <- torch$eye(5L)
diag

# logical NOT
not_diag <- !diag

# convert to integer
not_diag$to(dtype=torch$uint8)
```