## Python & R Package – Uncovr Documentation

- April 24, 2022
- Posted by: FOYI
- Category: Technical Documentation

###### API Subscription

The first step to accessing the API is to get the subscription key. The steps to sourcing the subscription key are as follows.

1. Head over to the API developer portal at https://foyi.developer.azure-api.net.

2. Click on the *Sign up* button on the home page.

3. Enter your details such as email, password etc.

4. You will receive an email to verify your email id.

5. Once you verify your email, please head over to the *Products* section of the developer portal. You can find it on the menu at the top right hand corner of the web page.

6. Please select the product *Starter* by clicking it. It will take you to the product page where you will find the section *Your subscriptions*. Please enter a name for your subscription and hit *Subscribe*.

7. Post subscribing, on your profile page, under the *subscriptions* section, click on *show* next to the *Primary key*. That is the subscription key you will need to access the API. Congratulations!!, you now can access the API.

8. If you have any issues with the signup, please email support@foyi.co.nz

###### Access using Python

Uncovr can be accessed using an open source Python package **uncovr**. Following are the steps.

1. Install uncovr package via pip as follows.

pip install uncovr

2. The following code generates a dataframe of 100 rows with a dependent variable and 3 independent variables.

import uncovr resp = uncovr.model2data(numOfObs=100, numOfVars=3, key="<input your subscription key here>")

3. The output of the* model2data* function i.e. *resp* above has a json file structure with the following elements.**depVar** is a list of values corresponding to the dependendent variable.**slope** prefixed elements are the corresponding slope i.e. the coefficient of the independent variable. For example, if there are 3 independent variables in the *model2data* function, then there will be 3 corresponding slopes for them.**indepVars** is a list of independent variables that are requested. For example, if there are 3 independent variables in the *model2data* function, then there will be 3 corresponding elements in the list. Furthermore, it must be noted that the length of each element of the list i.e. the independent variable will be equal to the *numOfObs* in the the *model2data* function.**error** is a list of errors for every observation.

Besides the above data, model performance measurements such as mae(mean absolute error), *me*(mean error) and *rmse*(root mean squared error) are also provided.

4. The dataframe with dependent and independent variables can be extracted with the *extractDf* function as follows. The variable *dv* is the dependent variable and each of the independent variables are prefixed with *iv*.

df = uncovr.extractDf(resp) df.head(3) #The output of the top 3 rows looks as follows dv iv1 iv2 iv3 0 -110.188634 32.782591 2.283461 17.709761 1 586.319487 6.039951 22.251926 -22.349773 2 236.518037 -1.516338 25.232946 17.251830

5. The above output can be interpreted as follows.

The dependent variable *dv* can be computed as a linear function of the intercept, independent variables, slopes and error. Please note that the function supports only the linear model and other models such as non-linear will be added in future versions.

As there are 3 independent variables requested in our example above, the dependent variable can be formulated as follows.

dv = intercept + (slope1 * iv1) + (slope2 * iv2) + (slope3 * iv3) + error

The intercept, slopes and the error can be sourced as follows. Please note that there will be new functionality built into the package in future versions to make this process more user friendly.

intercept = resp.json()['intercept'] slope1 = resp.json()['slope1'] slope2 = resp.json()['slope2'] slope3 = resp.json()['slope3'] error = resp.json()['error']

Please note that the slopes and intercept are at dataframe level i.e. they are the same for every row, while the error is at the row level. Therefore, the *error* above represents all the error terms and consequently is as long as the number of rows requested. In our example above, there are 100 rows requested and therefore the *error* will have 100 elements.

Thus, the formulation of the dependent variable of the i^{th} row can be obtained as follows. It is important to remember that the dataframe is zero indexed and therefore, the *i* value for the first row is 0 and not 1.

dv = intercept + (slope1 * df['iv1'][i]) + (slope2 * df['iv2'][i]) + (slope3 * df['iv3'][i]) + error[i]

6. In order to source the overall model formula, you can simple substitute *error[i]* in the above equation with the *meanAbsoluteError* as given below. The model performance measurements can be accessed as follows.

meanAbsoluteError = resp.json()['mae'] #This averages the absolute errors across all the rows

meanError = resp.json()['me'] #This averages the errors across all the rows

rootMeanSquaredError = resp.json()['rmse'] #This averages the squared absolute errors across all the rows

###### Access using R

Uncovr can be accessed using an open source R package **conjurer**. The steps to accessing uncovr using **conjurer** are as follows.

1. Install conjurer package by using the following code.

install.packages("conjurer")

2. The following code generates 100 observations with a dependent variable and 3 independent variables.

library(conjurer)

uncovrJson <- buildModelData(numOfObs = 100, numOfVars = 3, key = "<input your subscription key here>")

df <- extractDf(uncovrJson=uncovrJson)

3. The top few rows of the data can be printed as follows

print(head(df))

4. The model performance measurements can be accessed as follows.

meanAbsoluteError <- uncovrJson$mae

meanError <- uncovrJson$me

rootMeanSquaredError <- uncovrJson$rmse

Contact Us for an introductory call to understand how we can help you.