src/aif360/aif360-r/README.Rmd

---
output: github_document
---

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

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

# AI Fairness 360 (AIF360) R Package

<!-- badges: start -->
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/aif360)](https://cran.r-project.org/package=aif360)
<!-- badges: end -->

## Overview

The AI Fairness 360 toolkit is an open-source library to help detect and mitigate bias in machine learning models.
The AI Fairness 360 R package includes a comprehensive set of metrics for datasets and models to test for biases, explanations for these metrics, and algorithms to mitigate bias in datasets and models.

## Installation

Install the CRAN version:

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

Or install the development version from GitHub:

``` r
# install.packages("devtools")
devtools::install_github("Trusted-AI/AIF360/aif360/aif360-r")
```

Then, use the install_aif360() function to install AIF360:

``` r
library(aif360)
install_aif360()
```

## Installation methods

AIF360 is distributed as a Python package and so needs to be installed within a Python environment on your system. By default, the install_aif360() function attempts to install AIF360 within an isolated Python environment (“r-reticulate”).

You can check using `reticulate::conda_python()` and `reticulate::py_config()`
 
### Suggested steps
 
 1)  Install reticulate  and check if you have miniconda installed. If you do, go to step 2.

 ```r
 install.packages("reticulate")
 reticulate::conda_list()
 ```
 If you get an error: `Error: Unable to find conda binary. Is Anaconda installed?`, please install
 miniconda
 
```r
reticulate::install_miniconda()
```
If everything worked, you should get the message: 

`* Miniconda has been successfully installed at '/home/rstudio/.local/share/r-miniconda'.` 

You can double check:

```
reticulate::conda_list()
```
You will get something like this:

```
          name                                                              python
1  r-miniconda                   /home/rstudio/.local/share/r-miniconda/bin/python
2 r-reticulate /home/rstudio/.local/share/r-miniconda/envs/r-reticulate/bin/python
```


2) You can create a new conda env and then configure which version of Python to use:

```r
reticulate::conda_create(envname = "r-test")
reticulate::use_miniconda(condaenv = "r-test", required = TRUE)
```
Check that everything is working `reticulate::py_config()`.

3) If you haven't yet, please install the aif360 package `install.packages("aif360")` and then
install aif360 dependencies

```r
aif360::install_aif360(envname = "r-test")
```
Note that this step should take a few minutes and the R session will restart.

4) You can now activate your Python environment
```r
reticulate::use_miniconda(condaenv = "r-test", required = TRUE)
```

## Getting Started

```r
library(aif360)
load_aif360_lib()
```

``` r
# load a toy dataset
data <- data.frame("feature1" = c(0,0,1,1,1,1,0,1,1,0),
                   "feature2" = c(0,1,0,1,1,0,0,0,0,1),
                   "label" = c(1,0,0,1,0,0,1,0,1,1))

# format the dataset
formatted_dataset <- aif360::binary_label_dataset(data_path = data,
                                          favor_label = 0,
                                          unfavor_label = 1,
                                          unprivileged_protected_attribute = 0,
                                          privileged_protected_attribute = 1,
                                          target_column = "label",
                                          protected_attribute = "feature1")

```

## Troubleshooting 

If you encounter any errors during the installation process, look for your issue here and try the solutions.

### Locked binding
If you get an error: `cannot change value of locked binding`, please restart the R session. Then try reactivating your Python environment and running the following commands exactly once: 
```r
library(aif360) 
load_aif360_lib()
```

## Contributing

If you'd like to contribute to the development of aif360, please read [these guidelines](CONTRIBUTING.md).

Please note that the aif360 project is released with a [Contributor Code of Conduct](CODEOFCONDUCT.md). By contributing to this project, you agree to abide by its terms.