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 ith 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