This package contains a set of functions related to exploratory data analysis, data preparation, and model performance. It is used by people coming from business, research, and teaching (professors and students).

`funModeling`

is intimately related to the *Data Science Live Book* -Open Source- (2017) in the sense that most of its functionality is used to explain different topics addressed by the book.

Some functions have in-line comments so the user can open the black-box and learn how it was developed, or to tune or improve any of them.

All the functions are well documented, explaining all the parameters with the help of many short examples. R documentation can be accessed by: `help("name_of_the_function")`

.

**Important changes from latest version 1.6.7**, (relevant only if you were using previous versions):

From the latest version, 1.6.7 (Jan 21-2018), the parameters `str_input`

, `str_target`

and `str_score`

will be renamed to `input`

, `target`

and `score`

respectively. The functionality remains the same. If you were using these parameters names on production, they will be still working until next release. this means that for now, you can use for example `str_input`

or `input`

.

The other importat change was in `discretize_get_bins`

, which is detailed later in this document.

This quick-start is focused only on the functions. All explanations around them, and the how and when to use them, can be accessed by following the “* Read more here.*” links below each section, which redirect you to the book.

Below there are most of the `funModeling`

functions divided by category.

`df_status`

: Dataset health statusUse case: analyze the zeros, missing values (`NA`

), infinity, data type, and number of unique values for a given dataset.

```
library(funModeling)
df_status(heart_disease)
```

```
## variable q_zeros p_zeros q_na p_na q_inf p_inf type
## 1 age 0 0.00 0 0.00 0 0 integer
## 2 gender 0 0.00 0 0.00 0 0 factor
## 3 chest_pain 0 0.00 0 0.00 0 0 factor
## 4 resting_blood_pressure 0 0.00 0 0.00 0 0 integer
## 5 serum_cholestoral 0 0.00 0 0.00 0 0 integer
## 6 fasting_blood_sugar 258 85.15 0 0.00 0 0 factor
## 7 resting_electro 151 49.83 0 0.00 0 0 factor
## 8 max_heart_rate 0 0.00 0 0.00 0 0 integer
## 9 exer_angina 204 67.33 0 0.00 0 0 integer
## 10 oldpeak 99 32.67 0 0.00 0 0 numeric
## 11 slope 0 0.00 0 0.00 0 0 integer
## 12 num_vessels_flour 176 58.09 4 1.32 0 0 integer
## 13 thal 0 0.00 2 0.66 0 0 factor
## 14 heart_disease_severity 164 54.13 0 0.00 0 0 integer
## 15 exter_angina 204 67.33 0 0.00 0 0 factor
## 16 has_heart_disease 0 0.00 0 0.00 0 0 factor
## unique
## 1 41
## 2 2
## 3 4
## 4 50
## 5 152
## 6 2
## 7 3
## 8 91
## 9 2
## 10 40
## 11 3
## 12 4
## 13 3
## 14 5
## 15 2
## 16 2
```

`plot_num`

: Plotting distributions for numerical variablesPlots only numeric variables.

```
plot_num(heart_disease)
```

Notes:

`bins`

: Sets the number of bins (10 by default).`path_out`

indicates the path directory; if it has a value, then the plot is exported in jpeg. To save in current directory path must be dot: “.”

`profiling_num`

: Calculating several statistics for numerical variablesRetrieves several statistics for numerical variables.

```
profiling_num(heart_disease)
```

```
## variable mean std_dev variation_coef p_01 p_05 p_25
## 1 age 54.44 9.04 0.17 35 40 48
## 2 resting_blood_pressure 131.69 17.60 0.13 100 108 120
## 3 serum_cholestoral 246.69 51.78 0.21 149 175 211
## 4 max_heart_rate 149.61 22.88 0.15 95 108 134
## 5 exer_angina 0.33 0.47 1.44 0 0 0
## 6 oldpeak 1.04 1.16 1.12 0 0 0
## 7 slope 1.60 0.62 0.38 1 1 1
## 8 num_vessels_flour 0.67 0.94 1.39 0 0 0
## 9 heart_disease_severity 0.94 1.23 1.31 0 0 0
## p_50 p_75 p_95 p_99 skewness kurtosis iqr range_98
## 1 56.0 61.0 68.0 71.0 -0.21 2.5 13.0 [35, 71]
## 2 130.0 140.0 160.0 180.0 0.70 3.8 20.0 [100, 180]
## 3 241.0 275.0 326.9 406.7 1.13 7.4 64.0 [149, 406.74]
## 4 153.0 166.0 181.9 192.0 -0.53 2.9 32.5 [95.02, 191.96]
## 5 0.0 1.0 1.0 1.0 0.74 1.5 1.0 [0, 1]
## 6 0.8 1.6 3.4 4.2 1.26 4.5 1.6 [0, 4.2]
## 7 2.0 2.0 3.0 3.0 0.51 2.4 1.0 [1, 3]
## 8 0.0 1.0 3.0 3.0 1.18 3.2 1.0 [0, 3]
## 9 0.0 2.0 3.0 4.0 1.05 2.8 2.0 [0, 4]
## range_80
## 1 [42, 66]
## 2 [110, 152]
## 3 [188.8, 308.8]
## 4 [116, 176.6]
## 5 [0, 1]
## 6 [0, 2.8]
## 7 [1, 2]
## 8 [0, 2]
## 9 [0, 3]
```

Note:

`plot_num`

and`profiling_num`

automatically exclude non-numeric variables

`freq`

: Getting frequency distributions for categoric variables```
library(dplyr)
# Select only two variables for this example
heart_disease_2=heart_disease %>% select(chest_pain, thal)
# Frequency distribution
freq(heart_disease_2)
```

```
## chest_pain frequency percentage cumulative_perc
## 1 4 144 47.5 48
## 2 3 86 28.4 76
## 3 2 50 16.5 92
## 4 1 23 7.6 100
```

```
## thal frequency percentage cumulative_perc
## 1 3 166 54.79 55
## 2 7 117 38.61 93
## 3 6 18 5.94 99
## 4 <NA> 2 0.66 100
```

```
## [1] "Variables processed: chest_pain, thal"
```

Notes:

`freq`

only processes`factor`

and`character`

, excluding non-categorical variables.- It returns the distribution table as a data frame.
- If
`input`

is empty, then it runs for all categorical variables. `path_out`

indicates the path directory; if it has a value, then the plot is exported in jpeg. To save in current directory path must be dot: “.”`na.rm`

indicates if`NA`

values should be excluded (`FALSE`

by default).

`correlation_table`

: Calculates R statisticRetrieves R metric (or Pearson coefficient) for all numeric variables, skipping the categoric ones.

```
correlation_table(heart_disease, "has_heart_disease")
```

```
## Variable has_heart_disease
## 1 has_heart_disease 1.00
## 2 heart_disease_severity 0.83
## 3 num_vessels_flour 0.46
## 4 oldpeak 0.42
## 5 slope 0.34
## 6 age 0.23
## 7 resting_blood_pressure 0.15
## 8 serum_cholestoral 0.08
## 9 max_heart_rate -0.42
```

Notes:

- Only numeric variables are analyzed. Target variable must be numeric.
- If target is categorical, then it will be converted to numeric.

`var_rank_info`

: Correlation based on information theoryCalculates correlation based on several information theory metrics between all variables in a data frame and a target variable.

```
var_rank_info(heart_disease, "has_heart_disease")
```

```
## var en mi ig gr
## 1 heart_disease_severity 1.8 0.995 0.99508 0.53907
## 2 thal 2.0 0.209 0.20946 0.16805
## 3 exer_angina 1.8 0.139 0.13914 0.15264
## 4 exter_angina 1.8 0.139 0.13914 0.15264
## 5 chest_pain 2.5 0.205 0.20502 0.11803
## 6 num_vessels_flour 2.4 0.182 0.18152 0.11577
## 7 slope 2.2 0.112 0.11242 0.08688
## 8 serum_cholestoral 7.5 0.561 0.56056 0.07956
## 9 gender 1.8 0.057 0.05725 0.06330
## 10 oldpeak 4.9 0.249 0.24917 0.06036
## 11 max_heart_rate 6.8 0.334 0.33362 0.05407
## 12 resting_blood_pressure 5.6 0.143 0.14255 0.03024
## 13 age 5.9 0.137 0.13718 0.02705
## 14 resting_electro 2.1 0.024 0.02415 0.02219
## 15 fasting_blood_sugar 1.6 0.000 0.00046 0.00076
```

Note: It analyzes numerical and categorical variables. It is also used with the numeric discretization method as before, just as `discretize_df`

.

`cross_plot`

: Distribution plot between input and target variableRetrieves the relative and absolute distribution between an input and target variable. Useful to explain and report if a variable is important or not.

```
cross_plot(data=heart_disease, input=c("age", "oldpeak"), target="has_heart_disease")
```

```
## [1] "Plotting transformed variable 'age' with 'equal_freq', (too many values). Disable with 'auto_binning=FALSE'"
```

```
## [1] "Plotting transformed variable 'oldpeak' with 'equal_freq', (too many values). Disable with 'auto_binning=FALSE'"
```

Notes:

`auto_binning`

:`TRUE`

by default, shows the numerical variable as categorical.`path_out`

indicates the path directory; if it has a value, then the plot is exported in jpeg.`input`

can be numeric or categoric, and`target`

must be a binary (two-class) variable.- If
`input`

is empty, then it runs for all variables.

`plotar`

: Boxplot and density histogram between input and target variablesUseful to explain and report if a variable is important or not.

**Boxplot:**

```
plotar(data=heart_disease, input = c("age", "oldpeak"), target="has_heart_disease", plot_type="boxplot")
```

**Density histograms:**

```
plotar(data=mtcars, input = "gear", target="cyl", plot_type="histdens")
```

Notes:

`path_out`

indicates the path directory; if it has a value, then the plot is exported in jpeg.- If
`input`

is empty, then it runs for all numeric variables (skipping the categorical ones). `input`

must be numeric and target must be categoric.`target`

can be multi-class (not only binary).

`categ_analysis`

: Quantitative analysis for binary outcomeProfile a binary target based on a categorical input variable, the representativeness (`perc_rows`

) and the accuracy (`perc_target`

) for each value of the input variable; for example, the rate of flu infection per country.

```
df_ca=categ_analysis(data = data_country, input = "country", target = "has_flu")
head(df_ca)
```

```
## country mean_target sum_target perc_target q_rows perc_rows
## 1 Malaysia 1.00 1 0.012 1 0.001
## 2 Mexico 0.67 2 0.024 3 0.003
## 3 Portugal 0.20 1 0.012 5 0.005
## 4 United Kingdom 0.18 8 0.096 45 0.049
## 5 Uruguay 0.17 11 0.133 63 0.069
## 6 Israel 0.17 1 0.012 6 0.007
```

Note:

`input`

variable must be categorical.`target`

variable must be binary (two-value).

This function is used to analyze data when we need to reduce variable cardinality in predictive modeling.

`discretize_get_bins`

+ `discretize_df`

: Convert numeric variables to categoricWe need two functions: `discretize_get_bins`

, which returns the thresholds for each variable, and then `discretize_df`

, which takes the result from the first function and converts the desired variables. The binning criterion is equal frequency.

Example converting only two variables from a dataset.

```
# Step 1: Getting the thresholds for the desired variables: "max_heart_rate" and "oldpeak"
d_bins=discretize_get_bins(data=heart_disease, input=c("max_heart_rate", "oldpeak"), n_bins=5)
```

```
## [1] "Variables processed: max_heart_rate, oldpeak"
```

```
# Step 2: Applying the threshold to get the final processed data frame
heart_disease_discretized=discretize_df(data=heart_disease, data_bins=d_bins, stringsAsFactors=T)
```

```
## [1] "Variables processed: max_heart_rate, oldpeak"
```

The following image illustrates the result. Please note that the variable name remains the same.

Notes:

- This two-step procedure is thought to be used in production with new data.
- Min and max values for each bin will be
`-Inf`

and`Inf`

, respectively. - A fix in the latest
`funModeling`

release (1.6.7) may change the output in certain scenarios. Please check the results if you were using version 1.6.6. More info about this change here.

`convert_df_to_categoric`

: Convert every column in a data frame to character variablesBinning, or discretization criterion for any numerical variable is equal frequency. Factor variables are directly converted to character variables.

```
iris_char=convert_df_to_categoric(data = iris, n_bins = 5)
```

```
## [1] "Variables processed: Sepal.Length, Sepal.Width, Petal.Length, Petal.Width"
## [1] "Variables processed: Sepal.Length, Sepal.Width, Petal.Length, Petal.Width"
```

```
# checking first rows
head(iris_char)
```

```
## Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1 [ 5.1, 5.7) [ 3.5, Inf] [-Inf, 1.6) [-Inf, 0.3) setosa
## 2 [-Inf, 5.1) [ 2.8, 3.1) [-Inf, 1.6) [-Inf, 0.3) setosa
## 3 [-Inf, 5.1) [ 3.2, 3.5) [-Inf, 1.6) [-Inf, 0.3) setosa
## 4 [-Inf, 5.1) [ 3.1, 3.2) [-Inf, 1.6) [-Inf, 0.3) setosa
## 5 [-Inf, 5.1) [ 3.5, Inf] [-Inf, 1.6) [-Inf, 0.3) setosa
## 6 [ 5.1, 5.7) [ 3.5, Inf] [ 1.6, 4.0) [ 0.3, 1.2) setosa
```

`equal_freq`

: Convert numeric variable to categoricConverts numeric vector into a factor using the equal frequency criterion.

```
new_age=equal_freq(heart_disease$age, n_bins = 5)
# checking results
Hmisc::describe(new_age)
```

```
## new_age
## n missing distinct
## 303 0 5
##
## Value [29,46) [46,54) [54,59) [59,63) [63,77]
## Frequency 63 64 71 45 60
## Proportion 0.21 0.21 0.23 0.15 0.20
```

Notes:

- Unlike
`discretize_get_bins`

, this function doesn't insert`-Inf`

and`Inf`

as the min and max value respectively.

`range01`

: Scales variable into the 0 to 1 rangeConvert a numeric vector into a scale from 0 to 1 with 0 as the minimum and 1 as the maximum.

```
age_scaled=range01(heart_disease$oldpeak)
# checking results
summary(age_scaled)
```

```
## Min. 1st Qu. Median Mean 3rd Qu. Max.
## 0.00 0.00 0.13 0.17 0.26 1.00
```

`hampel_outlier`

and `tukey_outlier`

: Gets outliers thresholdBoth functions retrieve a two-value vector that indicates the thresholds for which the values are considered as outliers.
The functions `tukey_outlier`

and `hampel_outlier`

are used internally in `prep_outliers`

.

**Using Tukey's method:**

```
tukey_outlier(heart_disease$resting_blood_pressure)
```

```
## bottom_threshold top_threshold
## 60 200
```

**Using Hampel's method:**

```
hampel_outlier(heart_disease$resting_blood_pressure)
```

```
## bottom_threshold top_threshold
## 86 174
```

`prep_outliers`

: Prepare outliers in a data frameTakes a data frame and returns the same data frame plus the transformations specified in the `input`

parameter. It also works with a single vector.

```
# Get threshold according to Hampel's method
hampel_outlier(heart_disease$max_heart_rate)
```

```
## bottom_threshold top_threshold
## 86 220
```

```
# Apply function to stop outliers at the threshold values
data_prep=prep_outliers(data = heart_disease, input = c('max_heart_rate','resting_blood_pressure'), method = "hampel", type='stop')
```

```
## bottom_threshold top_threshold
## 86 220
```

```
## [1] "Before transformation -> Min: 71; Max: 202"
```

```
## [1] "After transformation -> Min: 86.283; Max: 202"
```

The maximum value is now 174.5 (the minimum remains the same).

Notes:

`method`

can be:`bottom_top`

,`tukey`

or`hampel`

.`type`

can be:`stop`

or`set_na`

. If`stop`

all values flagged as outliers will be set to the threshold. If`set_na`

, then the flagged values will set to`NA`

.

`gain_lift`

: Gain and lift performance curveAfter computing the scores or probabilities for the class we want to predict, we pass it to the `gain_lift`

function, which returns a data frame with performance metrics.

```
# Create machine learning model and get its scores for positive case
fit_glm=glm(has_heart_disease ~ age + oldpeak, data=heart_disease, family = binomial)
heart_disease$score=predict(fit_glm, newdata=heart_disease, type='response')
# Calculate performance metrics
gain_lift(data=heart_disease, score='score', target='has_heart_disease')
```

```
## Population Gain Lift Score.Point
## 1 10 21 2.1 0.82
## 2 20 36 1.8 0.70
## 3 30 49 1.6 0.57
## 4 40 61 1.5 0.49
## 5 50 69 1.4 0.40
## 6 60 78 1.3 0.33
## 7 70 88 1.2 0.29
## 8 80 92 1.1 0.25
## 9 90 96 1.1 0.20
## 10 100 100 1.0 0.12
```

- Github repository (report bugs or improvements): https://github.com/pablo14/funModeling
- Creator and mantainer: Pablo Casas https://twitter.com/pabloc_ds / pcasas.biz
gmail.com