{"id":14067181,"url":"https://github.com/alteryx/promote-r-client","last_synced_at":"2025-03-17T22:09:18.386Z","repository":{"id":56937011,"uuid":"107189858","full_name":"alteryx/promote-r-client","owner":"alteryx","description":"R package for deploying models built using R to Alteryx Promote.","archived":false,"fork":false,"pushed_at":"2019-02-06T17:40:05.000Z","size":10974,"stargazers_count":5,"open_issues_count":1,"forks_count":6,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-01T09:22:17.704Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alteryx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-16T22:29:28.000Z","updated_at":"2022-02-03T22:38:23.000Z","dependencies_parsed_at":"2022-08-21T07:20:31.871Z","dependency_job_id":null,"html_url":"https://github.com/alteryx/promote-r-client","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alteryx%2Fpromote-r-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alteryx%2Fpromote-r-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alteryx%2Fpromote-r-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alteryx%2Fpromote-r-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alteryx","download_url":"https://codeload.github.com/alteryx/promote-r-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244117670,"owners_count":20400744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-13T07:05:28.285Z","updated_at":"2025-03-17T22:09:18.361Z","avatar_url":"https://github.com/alteryx.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"# Alteryx Promote R Client\nPackage for deploying R models to Alteryx Promote.\n\n### Examples:\n[Hello World](examples/helloworld) - A very simple model.\n\n[Lending](examples/lending) - Use logistic regression to classify credit applications. as good or bad.\n\n[xgboost](examples/xgboost) - Use xgboost to train a classifier on the agaricus dataset.\n\u003chr\u003e\n\n## Installation\n### Client\nTo install the promote package from CRAN, execute the following code from an active R session:\n```r\ninstall.packages(\"promote\")\n```\n\n(Please refer to the [promote-python](https://github.com/alteryx/promote-python) package for instructions on installing the Python client.)\n\n### Promote App\nPlease refer to the [installation guide](https://help.alteryx.com/promote/current/Administer/Installation.htm?tocpath=Administer%7C_____2) for instructions on installing the full Promote application.\n\u003chr\u003e\n\n## Using the Client\n### Model Directory Structure\n```\nexample-model/\n├── deploy.R\n└── promote.sh (optional)\n```\n\n- [`deploy.R`](#deployr): our primary model deployment script\n\n- [`promote.sh`](#promotesh): this file is executed before your model is built. It can be used to install low-level system packages such as Linux packages\n\u003chr\u003e\n\n## Deploying Your Model\n\nThis section will walk through the steps and key functions of a successful `deploy.r` script. \n#### Steps:\n- [Initial Setup](#setup)\n- [model.predict](#modelpredict)\n- [Test Data](#testing)\n- [promote.library](#promotelibrary)\n- [promote.metadata](#promotemetadata)\n- [promote.config](#promoteconfig)\n- [promote.deploy](#promotedeploy)\n\u003chr\u003e\n\n### \u003ca name=\"setup\"\u003e\u003c/a\u003eInitial Setup\nLoad the `promote` library that was previously installed:\n```r\nlibrary(promote)\n```\n\nImport a saved model object:\n```r\n# Previously saved model 'save(my_model, file = \"my_model.rda\")'\nload(\"my_model.rda\")\n```\n\u003chr\u003e\n\n### `model.predict`\nThe `model.predict` function is used to define the API endpoint for a model and is executed each time a model is called. **This is the core of the API endpoint**\n\n### Usage\n`model.predict(data)`\n\n### Arguments\n- `data` the data frame generated from the JSON sent to the deployed model\n\n**Example:**\n```r\nmodel.predict \u003c- function(data) {\n  # generate predictions from the model based on the incoming dataframe\n  predict(my_model, data)\n}\n```\n\n### \u003ca name=\"testing\"\u003e\u003c/a\u003eTest Data\nIt is a good practice to test the `model.predict` function as part of the deployment script to make sure it successfully produces an output. Once deployed, the `data` argument passed to the `model.predict` function will always be in the form of an R [data frame](https://stat.ethz.ch/R-manual/R-devel/library/base/html/data.frame.html). The incoming JSON will be converted to a data frame using the `fromJSON()` method available from either [jsonlite](https://cran.r-project.org/web/packages/jsonlite/jsonlite.pdf) or [rjson](https://cran.r-project.org/web/packages/rjson/rjson.pdf). Which library is used can be configured in the advanced model management section of the Promote App.\n\n**Example:**\n```r\ntestdata \u003c- '{\"X1\":[1,2,3],\"X2\":[4,5,6]}'\nmodel.predict(data.frame(jsonlite::fromJSON(testdata),stringsAsFactors=TRUE))\n\n```\n\u003chr\u003e\n\n### `promote.library`\n\n### Usage\n\n`promote.library(name, src = \"version\", version = NULL, user = NULL, install = TRUE, auth_token = NULL, url = NULL, ref = \"master\", subdir = NULL)`\n\n**Note**: Installing custom packages from git requires Promote version 2018.4.1 or higher. Installing custom packages with `subdir` parameter requires Promote version 2019.1.0 or higher.\n\n### Arguments\n\n - `name`\tname of the package to be added\n- `src`\tsource from which the package will be installed on Promote (CRAN or git)\n- `version`\tversion of the package to be added (CRAN only, use `ref` parameter for git packages)\n- `user`\tGithub username associated with the package\n- `install`\twhether the package should also be installed into the model on the Promote server; this is typically set to False when the package has already been added to the Promote base image.\n- `auth_token` Personal access token string associated with a private package's repository (only works when `src = 'github'`, recommended usage is to include PAT in the URL parameter while using `src='git'`)\n- `url` A valid URL pointing to a remote hosted git repository (recommended)\n- `ref`\tThe git branch, tag, or SHA of the package to be installed (SHA recommended)\n- `subdir` The subdirectory path of a git repository holding the package to install\n\n**Examples:**\n\nPublic Repositories:\n```r\npromote.library(\"randomforest\")\n\npromote.library(c(\"wesanderson\", \"stringr\"))\n\npromote.library(\"my_public_package\", install = FALSE)\n\npromote.library(\"my_public_package\", \n                src = \"git\", \n                url = \"https://gitlab.com/userName/rpkg.git\")\n\npromote.library(\"hilaryparker/cats\")\n\npromote.library(\"cats\", src = \"github\", user = \"hilaryparker\")\n```\n\nPrivate Repositories:\n```r\npromote.library(\"priv_pkg\", \n                src = \"git\", \n                url = \"https://x-access-token:\u003cYourToken\u003eATgithub.com/username/rpkg.git\")\n\npromote.library(\"priv_pkg\", \n                 src = \"git\", \n                 url = \"https://x-access-token:\u003cYourToken\u003eATgitlab.com/username/rpkg.git\", \n                 ref = \"i2706b2a9f0c2f80f9c2a90ac4499a80280b3f8d\")\n\npromote.library(\"priv_pkg\", \n                 src = \"git\", \n                 url = \"https://x-access-token:\u003cYourToken\u003eATgitlab.com/username/rpkg.git\", \n                 ref = \"staging\")\n\npromote.library(\"cats\", src = \"github\", user = \"hilaryparker\", auth_token = \"3HwjSeMu1ynrYtc1e4yj\") \n```\n\u003chr\u003e\n\n\n### `promote.metadata`\nStore custom metadata about a model as part of the `model.predict` call when it is sent to the Promote servers. (limited to 6 key-value pairs)\n\n### Usage\n`promote.metadata(name, value)`\n\n### Arguments\n- `name` the name of your metadata (limit 20 characters)\n- `value` a value for your metadata (will be converted to string and limited to 50 characters)\n\n**Example:**\n```r\npromote.metadata(\"one\", 1)\npromote.metadata(\"two\", \"2\")\npromote.metadata(\"list\", list(a=1,b=2))\n```\n\u003chr\u003e\n\n### `promote.config`\nTo deploy models, add a username, API key, and URL to the `promote.config` variable\n\n- `username` the username used to sign into the Promote app\n- `apikey` the random API key that is assigned to that username\n- `env` the URL that can be used to access the Promote app's frontend\n\n**Example:**\n```r\npromote.config \u003c- c(\n  username = \"username\",\n  apikey = \"apikey\",\n  env = \"http://promote.company.com/\"\n)\n```\n\u003chr\u003e\n\n### `promote.deploy`\nThe deploy function captures `model.predict` and the `promote.sh` file and sends them to the Promote servers\n\n### Usage\n`promote.deploy(model_name, confirm = TRUE, custom_image = NULL)`\n\n### Arguments\n- `model_name` the name of the model to deploy to Alteryx Promote\n- `confirm` if true, the user will be prompted to confirm deployment \n- `custom_image` the custom image tag to use when building the model\n\n**Example:**\n```r\npromote.deploy(\"MyFirstRModel\", confirm = TRUE, custom_image = NULL)\n```\n\u003chr\u003e\n\n### `promote.sh`\nThe `promote.sh` file can be included in your model directory. It is executed before your model is built and can be used to install low-level system packages such as Linux packages and other dependencies. Be aware of the current working directory for your R session when deploying to ensure the deployment finds and processes the `promote.sh` file.\n\n**Example:**\n```shell\n# Install Microsoft SQL Server RHEL7 ODBC Driver\ncurl https://packages.microsoft.com/config/rhel/7/prod.repo \u003e /etc/yum.repos.d/mssql-release.repo\n\nexit\nyum remove unixODBC-utf16 unixODBC-utf16-devel #to avoid conflicts\nACCEPT_EULA=Y yum install msodbcsql17\n# optional: for bcp and sqlcmd\nACCEPT_EULA=Y yum install mssql-tools\necho 'export PATH=\"$PATH:/opt/mssql-tools/bin\"' \u003e\u003e ~/.bash_profile\necho 'export PATH=\"$PATH:/opt/mssql-tools/bin\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\u003chr\u003e\n\n### Deployment\nThere are multiple ways to run your `deploy.R` script and deploy your model.\n1. In in an active R shell session, you can source the deploy.R file.\n```r\nsource(\"deploy.R\")\n```\n\n2. If in a console/terminal/bash session, you can use the `Rscript` utility to run the file.\n```shell\nRscript deploy.R\n```\n\n3. If using an R IDE environment like [RStudio](https://www.rstudio.com/), you can run or source the script all at once or selectively. Model deployment will once the `promote.deploy` function is called.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falteryx%2Fpromote-r-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falteryx%2Fpromote-r-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falteryx%2Fpromote-r-client/lists"}