---
title: "Introduction to the rgnoisefilt package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{rgnoisefilt}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

getInfo <- function(what = "Suggests") {
  text <- packageDescription("rgnoisefilt")[what][[1]]
  text <- gsub("\n", ", ", text, fixed = TRUE)
  text <- gsub(">=", "$\\\\ge$", text, fixed = TRUE)
  eachPkg <- strsplit(text, ", ", fixed = TRUE)[[1]]
  eachPkg <- gsub(",", "", eachPkg, fixed = TRUE)
  #out <- paste("\\\**", eachPkg[order(tolower(eachPkg))], "}", sep = "")
  #paste(out, collapse = ", ")
  length(eachPkg)
}
```

<p style="text-align:justify;">

The **rgnoisefilt** package contains filtering techniques to remove noisy samples in regression datasets. It adapts classic and recent filtering techniques for use in regression problems, and it also incorporates methods specifically designed for regression data. In order to do this, it uses approaches proposed in the specialized literature, such as <a href="https://ieeexplore.ieee.org/document/9585469">Martín <i>et al.</i> (2021)</a> and <a href="https://doi.org/10.1016/j.eswa.2015.12.046">Arnaiz-González <i>et al.</i> (2016)</a>.

</p>

## Instalation

<p style="text-align:justify;">

The **rgnoisefilt** package can be installed in R from **CRAN** servers using the command:

</p>

```{r install1}
#install.packages("rgnoisefilt")
```

<p style="text-align:justify;">

This command installs all the dependencies of the package as well as all the regression algorithms necessary for the operation of the noise filters. In order to access all the functions of the package, it is necessary to use the R command:

</p>

```{r install2}
library(rgnoisefilt)
```

## Documentation

<p style="text-align:justify;">

All the information corresponding to each noise filter can be consulted from the **CRAN** website. Additionally, the help() command can be used. For example, in order to check the documentation of the <i>regIPF</i> noise filter, we can use:

</p>

```{r document1}
help(regIPF)
```

## Usage of regression noise filters

<p style="text-align:justify;">

For processing noisy regression data, each noise filter in the **rgnoisefilt** package provides two standard ways of use:

</p>

<p style="text-align:justify;">

<ul>

<li><i>Default method</i>. It receives a data frame with the input attributes in the <i>x</i> argument, whereas the output variable is received through the <i>y</i> argument (a double vector).</li>

<li><i>Formula class method</i>. This method allows passing the whole data frame (attributes and response variable) in the <i>data</i> argument. In addition, the attributes along with the output regressand must be indicated in the <i>formula</i> argument.</li>

</ul>

</p>

<p style="text-align:justify;">

An example on how to use these two methods for filtering out the <i>rock</i> dataset with the <i>regCNN</i> noise filter is shown below:

</p>

```{r example 1}
data(rock)
head(rock)
# Using the default method:
set.seed(9)
out.def <- regCNN(x = rock[,-ncol(rock)], y = rock[,ncol(rock)])
# Using the formula method:
set.seed(9)
out.frm <- regCNN(formula = perm ~ ., data = rock)
# Check the match of noisy indices:
all(out.def$idnoise == out.frm$idnoise)
```

<p style="text-align:justify;">

Note that, the $\$$ operator is used to access the elements returned by the filter in the objects $out.def$ and $out.frm$.

</p>

## Output values

<p style="text-align:justify;">

All regression noise filters return an object of <i>rfdata</i> class. It is designed to unify the output value of the methods included in the **rgnoisefilt** package. The <i>rfdata</i> class is a list of elements with the most relevant information of the noise filtering process:

</p>

<ul>

<li><i>xclean:</i> a data frame with the input attributes of clean samples (without errors).</li>

<li><i>yclean:</i> a double vector with the output regressand of clean samples (without errors).</li>

<li><i>numclean:</i> an integer with the amount of clean samples.</li>

<li><i>idclean:</i> an integer vector with the indices of clean samples.</li>

<li><i>xnoise:</i> a data frame with the input attributes of noisy samples (with errors).</li>

<li><i>ynoise:</i> a double vector with the output regressand of noisy samples (with errors).</li>

<li><i>numnoise:</i> an integer with the amount of noisy samples.</li>

<li><i>idnoise:</i> an integer vector with the indices of noisy samples.</li>

<li><i>filter:</i> the full name of the noise filter used.</li>

<li><i>param:</i> a list of the argument values.</li>

<li><i>call:</i> the function call.</li>

</ul>

As an example, the structure of the <i>rfdata</i> object returned using the <i>regCNN</i> noise filter is shown below:

```{r example 2}
str(out.def)
```

<p style="text-align:justify;">

In order to display the results of the <i>rfdata</i> class in a friendly way in the R console, two specific <i>print</i> and <i>summary</i> functions are implemented. The <i>print</i> function presents the basic information of the noise filtering process:

</p>

```{r example 3}
print(out.def)
```

<p style="text-align:justify;">

The information offered by <i>print</i> is as follows:

<ul>

<li>The name of the regression noise filter.</li>

<li>The parameters associated with the noise filter.</li>

<li>The number of noisy and clean samples in the dataset.</li>

</ul>

</p>

<p style="text-align:justify;">

On the other hand, the <i>summary</i> function displays the information of the dataset processed with the noise filter along with other additional details. This function can be called by typing the following R command:

</p>

```{r example 4}
summary(out.frm, showid = TRUE)
```

<p style="text-align:justify;">

The information offered by this function is as follows:

</p>

<p style="text-align:justify;">

<ul>

<li>The function call.</li>

<li>The name of the regression noise filter.</li>

<li>The parameters associated with the noise filter.</li>

<li>The indices of the noisy and clean samples (if <i>showid = TRUE</i>).</li>

</ul>

</p>