R Integration Pack User

Guide

Version: 1.0
Document Number: 09600106

2014, version 1.0

To ensure that you are using the documentation that corresponds to the software you are licensed to use, compare this version number with the software
version shown in About MicroStrategy... in the Help menu of your software.
Document number: 09600106
Copyright 2014 by MicroStrategy Incorporated. All rights reserved.
If you have not executed a written or electronic agreement with MicroStrategy or any authorized MicroStrategy distributor, the following terms apply:
This software and documentation are the proprietary and confidential information of MicroStrategy Incorporated and may not be provided to any other
person. Copyright 2001-2014 by MicroStrategy Incorporated. All rights reserved.
THIS SOFTWARE AND DOCUMENTATION ARE PROVIDED AS IS AND WITHOUT EXPRESS OR LIMITED WARRANTY OF ANY KIND BY EITHER
MICROSTRATEGY INCORPORATED OR ANYONE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DISTRIBUTION OF THE
SOFTWARE OR DOCUMENTATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE, GOOD TITLE AND NONINFRINGMENT, QUALITY OR ACCURACY. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE SOFTWARE AND DOCUMENTATION IS WITH YOU. SHOULD THE SOFTWARE OR DOCUMENTATION PROVE
DEFECTIVE, YOU (AND NOT MICROSTRATEGY, INC. OR ANYONE ELSE WHO HAS BEEN INVOLVED WITH THE CREATION, PRODUCTION, OR
DISTRIBUTION OF THE SOFTWARE OR DOCUMENTATION) ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR, OR
CORRECTION. SOME STATES DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO
YOU.
In no event will MicroStrategy, Inc. or any other person involved with the creation, production, or distribution of the Software be liable to you on account
of any claim for damage, including any lost profits, lost savings, or other special, incidental, consequential, or exemplary damages, including but not limited
to any damages assessed against or paid by you to any third party, arising from the use, inability to use, quality, or performance of such Software and
Documentation, even if MicroStrategy, Inc. or any such other person or entity has been advised of the possibility of such damages, or for the claim by any
other party. In addition, MicroStrategy, Inc. or any other person involved in the creation, production, or distribution of the Software shall not be liable for
any claim by you or any other party for damages arising from the use, inability to use, quality, or performance of such Software and Documentation, based
upon principles of contract warranty, negligence, strict liability for the negligence of indemnity or contribution, the failure of any remedy to achieve its
essential purpose, or otherwise. The entire liability of MicroStrategy, Inc. and your exclusive remedy shall not exceed, at the option of MicroStrategy, Inc.,
either a full refund of the price paid, or replacement of the Software. No oral or written information given out expands the liability of MicroStrategy, Inc.
beyond that specified in the above limitation of liability. Some states do not allow the limitation or exclusion of liability for incidental or consequential
damages, so the above limitation may not apply to you.
The information contained in this manual (the Documentation) and the Software are copyrighted and all rights are reserved by MicroStrategy, Inc.
MicroStrategy, Inc. reserves the right to make periodic modifications to the Software or the Documentation without obligation to notify any person or entity
of such revision. Copying, duplicating, selling, or otherwise distributing any part of the Software or Documentation without prior written consent of an
authorized representative of MicroStrategy, Inc. are prohibited. U.S. Government Restricted Rights. It is acknowledged that the Software and
Documentation were developed at private expense, that no part is public domain, and that the Software and Documentation are Commercial Computer
Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication, or disclosure
by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer SoftwareRestricted Rights at FAR 52.227-19, as applicable.
Contractor is MicroStrategy, Inc., 1850 Towers Crescent Plaza, Tysons Corner, VA 22182. Rights are reserved under copyright laws of the United States
with respect to unpublished portions of the Software.
The following are either trademarks or registered trademarks of MicroStrategy Incorporated in the United States and certain other countries:
MicroStrategy, MicroStrategy 6, MicroStrategy 7, MicroStrategy 7i, MicroStrategy 7i Evaluation Edition, MicroStrategy 7i Olap Services, MicroStrategy 8,
MicroStrategy 9, MicroStrategy Distribution Services, MicroStrategy MultiSource Option, MicroStrategy Command Manager, MicroStrategy Enterprise
Manager, MicroStrategy Object Manager, MicroStrategy Reporting Suite, MicroStrategy Power User, MicroStrategy Analyst, MicroStrategy Consumer,
MicroStrategy Email Delivery, MicroStrategy BI Author, MicroStrategy BI Modeler, MicroStrategy Evaluation Edition, MicroStrategy Administrator,
MicroStrategy Agent, MicroStrategy Architect, MicroStrategy BI Developer Kit, MicroStrategy Broadcast Server, MicroStrategy Broadcaster,
MicroStrategy Broadcaster Server, MicroStrategy Business Intelligence Platform, MicroStrategy Consulting, MicroStrategy CRM Applications,
MicroStrategy Customer Analyzer, MicroStrategy Desktop, MicroStrategy Desktop Analyst, MicroStrategy Desktop Designer, MicroStrategy eCRM 7,
MicroStrategy Education, MicroStrategy eTrainer, MicroStrategy Executive, MicroStrategy Infocenter, MicroStrategy Intelligence Server, MicroStrategy
Intelligence Server Universal Edition, MicroStrategy MDX Adapter, MicroStrategy Narrowcast Server, MicroStrategy Objects, MicroStrategy OLAP
Provider, MicroStrategy SDK, MicroStrategy Support, MicroStrategy Telecaster, MicroStrategy Transactor, MicroStrategy Web, MicroStrategy Web
Business Analyzer, MicroStrategy World, Application Development and Sophisticated Analysis, Best In Business Intelligence, Centralized Application
Management, Information Like Water, Intelligence Through Every Phone, Intelligence To Every Decision Maker, Intelligent E-Business, Personalized
Intelligence Portal, Query Tone, Rapid Application Development, MicroStrategy Intelligent Cubes, The Foundation For Intelligent E-Business, The
Integrated Business Intelligence Platform Built For The Enterprise, The Platform For Intelligent E-Business, The Scalable Business Intelligence Platform
Built For The Internet, Office Intelligence, MicroStrategy Office, MicroStrategy Report Services, MicroStrategy Web MMT, MicroStrategy Web Services,
Pixel Perfect, Pixel-Perfect, MicroStrategy Mobile, MicroStrategy Integrity Manager and MicroStrategy Data Mining Services are all registered trademarks
or trademarks of MicroStrategy Incorporated.
All other company and product names may be trademarks of the respective companies with which they are associated. Specifications subject to change
without notice. MicroStrategy is not responsible for errors or omissions. MicroStrategy makes no warranties or commitments concerning the availability
of future products or versions that may be planned or under development.
Patent Information
This product is patented. One or more of the following patents may apply to the product sold herein: U.S. Patent Nos. 6,154,766, 6,173,310, 6,260,050,
6,263,051, 6,269,393, 6,279,033, 6,400,265, 6,567,796, 6,587,547, 6,606,596, 6,658,093, 6,658,432, 6,661,340, 6,662,195, 6,671,715, 6,691,100,
6,694,316, 6,697,808, 6,704,723, 6,741,980, 6,765,997, 6,768,788, 6,772,137, 6,788,768, 6,798,867, 6,801,910, 6,820,073, 6,829,334, 6,836,537,
6,850,603, 6,859,798, 6,873,693, 6,885,734, 6,940,953, 6,964,012, 6,977,992, 6,996,568, 6,996,569, 7,003,512, 7,010,518, 7,016,480, 7,020,251,
7,039,165, 7,082,422, 7,113,993, 7,127,403, 7,174,349, 7,181,417, 7,194,457, 7,197,461, 7,228,303, 7,260,577, 7,266,181, 7,272,212, 7,302,639,
7,324,942, 7,330,847, 7,340,040, 7,356,758, 7,356,840, 7,415,438, 7,428,302, 7,430,562, 7,440,898, 7,486,780, 7,509,671, 7,516,181, 7,559,048,
7,574,376, 7,617,201, 7,725,811, 7,801,967, 7,836,178, 7,861,161, 7,861,253, 7,881,443, 7,925,616, 7,945,584, 7,970,782, 8,005,870, 8,051,168,
8,051,369, 8,094,788, 8,130,918, 8,296,287, 8,321,411, 8,452,755, 8,521,733, and 8,522,192. Other patent applications are pending.
Various MicroStrategy products contain the copyrighted technology of third parties. This product may contain one or more of the following copyrighted
technologies:
Graph Generation Engine Copyright 1998-2014. Three D Graphics, Inc. All rights reserved.
Actuate Formula One. Copyright 1993-2014 Actuate Corporation. All rights reserved.
XML parser Copyright 2003-2014 Microsoft Corporation. All rights reserved.
Xalan XSLT processor. Copyright 1999-2014. The Apache Software Foundation. All rights reserved.
Xerces XML parser. Copyright 1999-2014. The Apache Software Foundation. All rights reserved.
FOP XSL formatting objects. Copyright 2004-2014. The Apache Software Foundation. All rights reserved.
Portions of Intelligence Server memory management Copyright 1991-2014 Compuware Corporation. All rights reserved.
ASIHTTPRequest library. Copyright 2007-2014, All-Seeing Interactive. All rights reserved.
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)

International Components for Unicode

Copyright 1999-2014 Compaq Computer Corporation
Copyright 1999-2014 Hewlett-Packard Company
Copyright 1999-2014 IBM Corporation
Copyright 1999-2014 Hummingbird Communications Ltd.
Copyright 1999-2014 Silicon Graphics, Inc.
Copyright 1999-2014 Sun Microsystems, Inc.
Copyright 1999-2014 The Open Group
All rights reserved.
Real Player and RealJukebox are included under license from Real Networks, Inc. Copyright 1999-2014. All rights reserved.

CONTENTS
Book Overview

1. Using the R
Integration Pack

Description of Guide ................................................................. vii

Whats new in this guide ........................................................ viii
Additional formats ....................................................................ix
Introduction.................................................................................. 1
R Integration Pack components and prerequisites ........................ 2
Integrating R analytics with MicroStrategy............................... 3
R environment requirements.................................................... 4
Installing and configuring the R Integration Pack .......................... 4
Installing the R script functions and supporting files ................ 5
Installing the MicroStrategyR Package for R ......................... 10
Deploying R analytics in MicroStrategy ....................................... 11
Implementing the analytic in R for deployment to
MicroStrategy......................................................................... 11
Best practices: Making the R script robust............................. 13
Using the deployR utility ........................................................ 26
R analytic deployment example ............................................. 31

Index........................................................................................................................................... 35

2014 MicroStrategy, Inc.

Contents

vi

R Integration Pack User Guide

2014 MicroStrategy, Inc.

BOOK OVERVIEW

Description of Guide
This document describes the R Integration Pack, which facilitates the
deployment of analytics from the R statistical environment to MicroStrategy.
It is intended to help MicroStrategy users extend the analytical features of
the MicroStrategy platform using the capabilities of the R platform. The R
Integration Pack requires a general understanding of the MicroStrategy
Business Intelligence environment, such as creating metrics and using them
on reports, as well as a familiarity with the R programming environment.

2014 MicroStrategy, Inc.

vii

Book Overview

R Integration Pack User Guide

Whats new in this guide

Version 1.0 update 6
In addition to various enhancements to improve the usability and clarity of
this documentation, Version 1.0 update 6 of the R Integration Pack User
Guide includes the following updates:

Requirements for the R Integration Pack have been updated to include

the support of MicroStrategy Analytics Desktop, see R Integration Pack
components and prerequisites, page 2.

Version 1.0 update 5

In addition to various enhancements to improve the usability and clarity of
this documentation, Version 1.0 update 5 of the R Integration Pack User
Guide includes the following updates:

The requirement of restarting the Intelligence Server has been added to

the steps to add or upgrade the R script functions for existing
MicroStrategy projects, provided in Post-installation requirements for
MicroStrategy Analytics Enterprise projects, page 8.

Information on how the directories utilized by R scripts are determined is

provided in Defining an R scripts file location and working directory,
page 12.

Information on installing R packages from CRAN mirror repository sites

is provided in Installing required packages, page 20.

The sample R script provided with the R Integration Pack has been
updated to include various enhancements. This updated script is
referenced in the various topics related to Best practices: Making the R
script robust, page 13 as well as R analytic deployment example,
page 31.

Version 1.0

viii

This guide was created for the R Integration Pack version 1.0.

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Book Overview

Additional formats
MicroStrategy manuals are available as electronic publications,
downloadable on the Apple iBookstore or Google Play, and can be read on
your iOS or Android device respectively. To download a book, search for the
books title in the iBookstore or Google Play respectively. To view a list of
manuals that are currently available, scan the following QR codes using your
devices camera:

For iOS devices, scan the following QR code:

For Android devices, scan the following QR code:

new MicroStrategy releases, it may take several days for the latest
For
manuals to be available on the iBookstore or Google Play.

2014 MicroStrategy, Inc.

ix

Book Overview

R Integration Pack User Guide

2014 MicroStrategy, Inc.

1
1.

USING THE R INTEGRATION

PACK

Introduction
R is the open-source, industry-leading language and environment for
statistical computing and graphics. The R Integration Pack lets you easily
integrate this statistical computing and graphics environment into
MicroStrategy by deploying R analytics as standard MicroStrategy metrics
that implement R scripts.
The R Integration Pack is part of the MicroStrategy Function Plug-in family
of approaches to adding new analytics to any MicroStrategy environment, as
shown below:

2014 MicroStrategy, Inc.

Using the R Integration Pack

R Integration Pack User Guide

The R Integration Pack deploys R analytics as MicroStrategy metrics. These

metrics can then be used directly on MicroStrategy reports and are therefore
easy to deploy and manage. Additionally, the R Integration Pack includes a
set of common R script functions, pre-compiled and ready to integrate into
any MicroStrategy project.
This document includes details about installing and using the R Integration
Pack, best practices for managing the execution flow, escalating R exceptions
to MicroStrategy, and general troubleshooting tips.
For information on MicroStrategys native analytics, review the following
MicroStrategy product documentation available at http://
www.microstrategy.com/producthelp:

MicroStrategy Functions Reference for details on MicroStrategys

built-in function library.

Basic Reporting Guide for information on deploying analytics as

MicroStrategy metrics.

Advanced Reporting Guide for information on Data Mining Services and

other analytically-focused topics.

For information on C++ Function Plug-ins, see the MicroStrategy Help for
the Function Plug-in Wizard installed with MicroStrategy.
For information on R Function Plug-ins, see the open source version of the
Function Plug-in Wizard at http://fpwizard.codeplex.com.

R Integration Pack components and

prerequisites
The R Integration Pack consists of two main components:

RScript Functions: A set of common functions that, when added to a

MicroStrategy project, allows MicroStrategy metrics to pass an R script
and its associated inputs to R for execution. Metrics using these common
R script functions also return the results from R for display and analysis
in MicroStrategy reports, Report Services documents, and Visual Insight
dashboards.
You must install these R script functions so that they are available to your
MicroStrategy environments that integrate R analytics as described in

2 R Integration Pack components and prerequisites

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

Integrating R analytics with MicroStrategy, page 3. The R environment

dependencies are discussed further in R environment requirements,
page 4.

MicroStrategyR Package for R: This package includes an R-based

utility, called deployR, that analyzes an R analytic to define its signature.
The deployR utility then adds a header comment block to the R script that
reflects the analytics signature. This signature describes the number and
nature of each input and output, along with other information related to
its execution. It includes information such as whether an input or output
is a number or string, as well as whether it is a scalar or vector variable.
This information is used by MicroStrategy to pass data to R, execute the
analytic, and then deploy the results.
The deployR utility is required during R script development to create an
R analytic for use in MicroStrategy (see Using the deployR utility,
page 26). The deployR utility is not required for the execution of an R
analytic in MicroStrategy.

Integrating R analytics with MicroStrategy

You can integrate R analytics with the following MicroStrategy offerings:

MicroStrategy Analytics Enterprise: MicroStrategy version 9.2.1 or

later must be installed. To support the deployment of a new R analytic as
a derived metric in Visual Insight, MicroStrategy version 9.3.1 or later
must be installed. Additional requirements include:
MicroStrategy Architect is necessary for the one-time addition of the
common R script functions.
The MicroStrategy Developer or MicroStrategy Web Designer
privilege is required to create metrics using the R script functions.
Any user can view and analyze the results of metrics that employ the R
script functions.
of MicroStrategy version 9.4.1, the name of MicroStrategy
AsDesktop
has been changed to MicroStrategy Developer.

MicroStrategy Analytics Desktop: Analytics Desktop version 9.4.1.3 or

later must be installed. Analytics Desktop does not have any
MicroStrategy privilege requirements to create, view, or analyze metrics
that employ R script functions.

2014 MicroStrategy, Inc.

R Integration Pack components and prerequisites

Using the R Integration Pack

R Integration Pack User Guide

R environment requirements
The following configurations are required when installing R for
MicroStrategy environments that integrate with R analytics as well as
machines that use the deployR utility during R script development to create
an R analytic for use in MicroStrategy:

You must install R version 3.x. The proper version of R must be installed
from http://CRAN.R-project.org:
Windows: The 32-bit version of R is required, regardless of whether
the Windows operating system is a 32-bit or 64-bit version.
can install both the 32-bit version and 64-bit version of R
You
on the same machine.
Unix and Linux: The 64-bit version of R is required.

R and any dependencies must be installed on systems that will execute

the R analytics deployed to MicroStrategy. These dependencies include
any add-on packages that are required for a given R analytic. R and any
dependencies must be installed on the following systems:
MicroStrategy Intelligence Server host machine, which supports R
analytic execution for MicroStrategy Web, MicroStrategy Mobile,
MicroStrategy Visual Insight, and MicroStrategy Office.
Intelligence Server also supports R analytic execution with
stand-alone metrics for MicroStrategy Developer clients that are
connected in server (three-tier) mode.
MicroStrategy Developer clients that execute R analytics as derived
metrics or in direct (two-tier) mode.
MicroStrategy Analytics Desktop machine that executes deployed
R analytics. For Analytics Desktop configurations, this is the only
machine that must include the R dependencies.

Installing and configuring the R Integration

Pack
Depending on whether you are integrating your MicroStrategy environment
with R analytics or creating R analytics for integration in MicroStrategy, you
can begin by installing the following components:
4 Installing and configuring the R Integration Pack

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

RScript Functions Installer, which must be completed on systems that

will integrate with R analytics as described in Integrating R analytics
with MicroStrategy, page 3. For steps to complete the RScript Functions
installation, see Installing the R script functions and supporting files,
page 5.

MicroStrategyR Package, which must be installed on machines that use

the deployR utility during R script development to create an R analytic
for use in MicroStrategy. For steps to complete the package installation,
see Installing the MicroStrategyR Package for R, page 10.

Installing the R script functions and supporting files

The R script functions include the pre-compiled R script functions and
supporting files, ready to integrate into MicroStrategy. The required
installation files can be downloaded from the Downloads tab at http://
RIntegrationPack.codeplex.com.

Installing on Windows
The steps below show you how to use the RScript Functions Installer to
install the R script functions on a Windows environment for MicroStrategy
Analytics Enterprise and MicroStrategy Analytics Desktop.
an early version (1.000.002 and earlier versions) of the R
 Upgrading
script functions can fail with a message that a newer version of this
application is already installed. If you encounter this problem while
upgrading, you must first uninstall the existing version of the R script
functions. Refer to your third-party Microsoft documentation for
steps to remove programs from your system. Once the early version of
the R script functions are removed, you can install the new version
using the steps provided below.
To install the R script functions on Windows

1 Access the site http://RIntegrationPack.codeplex.com.

2 From the Downloads tab, locate and download the
RIntegrationPack.msi file.

2014 MicroStrategy, Inc.

Installing and configuring the R Integration Pack

Using the R Integration Pack

R Integration Pack User Guide

3 Double-click RintegrationPack.msi to execute the file and begin the

installation process. The installation wizard is displayed.
successfully complete the installation, you must execute the
 Toinstallation
using an account with administrative privileges or
choose to execute the installation as an administrator.
4 Complete the steps provided in the installation wizard.
By default, the installation location is:

32-bit Windows environments: C:\Program Files\R

Integration Pack

64-bit Windows environments: C:\Program Files (x86)\R

Integration Pack

The following files and folders are available:

ReadMe.txt: Includes whats new information as well as important

support and configuration information such as upgrade
considerations.

Documentation: Location of this document.

RScripts: The default location for R scripts deployed to

MicroStrategy. The sample R script referenced later in this document
can be found in this folder.

5 Once installation is complete, ensure that the R script functions are

available for your environment as described below:

MicroStrategy Analytics Enterprise:

For existing projects, the R script functions must be added to the
projects metadata or upgraded. For steps to add or upgrade R
script functions for existing projects, see Post-installation
requirements for MicroStrategy Analytics Enterprise projects,
page 8.
For projects created after installation, the R script functions are
automatically added to these newly created projects. The R script
functions are added to the list of Data Mining Functions available
when creating metrics, including the functions RScript,
RScriptU, RScriptAgg, RScriptAggU, and RScriptSimple.

MicroStrategy Analytics Desktop:

The R script functions are included with the standard installation
of Analytics Desktop. The functions RScript, RScriptU,

6 Installing and configuring the R Integration Pack

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

RScriptAgg, RScriptAggU, and RScriptSimple are included

in the list of Data Mining Functions, available when creating
metrics.

Installing on UNIX and Linux

The steps below show you how to use the RScript Functions Installer to
install the R script functions on a UNIX or Linux environment for
MicroStrategy Analytics Enterprise.
To install the R script functions on UNIX or Linux

1 Access the site http://RIntegrationPack.codeplex.com.

2 From the Downloads tab, locate and download the
RintegrationPack_OS.tar.gz file, where OS is the operating system that
you are installing to. For example, if you are installing on AIX, install the
RintegrationPack_AIX.tar.gz file.
3 Unzip the contents of the file, using a command such as the following:
gunzip RintegrationPack_OS.tar.gz
4 Extract the installation files, using a command such as the following:
tar -xvf RintegrationPack_OS.tar
5 You must execute the RScript Functions Installer with the same user
account that executed the MicroStrategy software installation for the
system. This ensures that the R script function files are installed to the
required MicroStrategy installation folder location. Begin the installation
by using the following command:
setup.sh
The installation wizard opens.
6 Complete the steps provided in the installation wizard.
By default, the installation location is /var/opt/
R_Integration_Pack, or $HOME/R_Integration_Pack if you do

2014 MicroStrategy, Inc.

Installing and configuring the R Integration Pack

Using the R Integration Pack

R Integration Pack User Guide

not have write access to /var/opt/R_Integration_Pack. The

following files and folders are available:

ReadMe.txt: Includes whats new information as well as important

support and configuration information such as upgrade
considerations.

Documentation: The location of this document.

RScripts: The default location for R scripts deployed to

MicroStrategy. The sample R script referenced later in this document
can be found in this folder.

7 Once installation is complete, ensure that the R script functions are

available for your environment as described below:

MicroStrategy Analytics Enterprise:

For existing projects, the R script functions must be added to the
projects metadata or upgraded. For steps to add or upgrade R
script functions for existing projects, see Post-installation
requirements for MicroStrategy Analytics Enterprise projects
below.
For projects created after installation, the R script functions are
automatically added to these newly created projects. The R script
functions are added to the list of Data Mining Functions available
when creating metrics, including the functions RScript,
RScriptU, RScriptAgg, RScriptAggU, and RScriptSimple.

Post-installation requirements for MicroStrategy Analytics

Enterprise projects
If you have MicroStrategy Analytics Enterprise projects that existed prior to
the installation of the R script functions, you must upgrade the projects using
the MicroStrategy Configuration Wizard to support the following scenarios:

If this is the first installation of the R script functions, upgrading a project

adds the R script functions to the project.

If you upgraded a previous version of the R script functions, upgrading a

project ensures that any changes to the R script functions since your
previous installation are applied to the project. The ReadMe.txt file
includes information on whether the R script functions were modified for
the most recent release. If you are upgrading a version of the R script
functions from more than one release prior, it is recommended to

8 Installing and configuring the R Integration Pack

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

upgrade a project to ensure that any R script function changes are

applied.
For Analytics Desktop configurations, the R script functions are included
with the standard installation of Analytics Desktop.
The steps below show you how to add or upgrade the R script functions for
existing MicroStrategy projects by upgrading the projects.
To add or upgrade R script functions for existing MicroStrategy Analytics
Enterprise projects

1 If you are upgrading MicroStrategy projects on:

Windows, then perform the following step:

From the Start menu, point to Programs, then MicroStrategy Tools,
and then choose Configuration Wizard. The Configuration Wizard
opens.

UNIX or Linux using the Configuration Wizard interface, then

perform the following steps:
a From a UNIX or Linux console window, browse to HOME_PATH,
where HOME_PATH is the directory that you specified as the home
directory during your MicroStrategy installation.
b Browse to the folder bin and type ./mstrcfgwiz, then press
ENTER. The Configuration Wizard opens.

2 Select Upgrade existing environment to MicroStrategy 9.

3 Click Next. Options to upgrade your MicroStrategy environment are
displayed.
4 Select Intelligence Server Components.
5 Click Next. The MicroStrategy Authentication page opens.
6 Type the user name and password of a MicroStrategy system
administrator.
7 Click Next. The Select Components to Upgrade page opens.
8 For each project to add the R script functions to, select the Re-execute
the Project Logical Upgrade check box.
2014 MicroStrategy, Inc.

Installing and configuring the R Integration Pack

Using the R Integration Pack

R Integration Pack User Guide

9 Select the Re-execute Metadata Repository Upgrade check box for the
Local Host Intelligence Server.
10 Click Next. The Summary page opens.
11 Click Finish to begin the upgrade.
12 Once the upgrade is complete, restart any MicroStrategy Intelligence
Server that is connected to the project metadata that was upgraded. The
R script functions are added to the list of Data Mining Functions available
when creating metrics, including the functions RScript, RScriptU,
RScriptAgg, RScriptAggU, and RScriptSimple.

Installing the MicroStrategyR Package for R

The MicroStrategyR Package includes the R-based deployR utility, which is
an interface used to prepare your R script for deployment to MicroStrategy.
It can be installed like any other R package using the Comprehensive R
Archive Network (CRAN) available via the http://www.r-project.org home
page. Alternatively, this package can be installed by typing this command
into an R console:
install.packages("MicroStrategyR")
to be available to all users and applications, packages need to
 Inbe order
installed into the default R library. Administrative privileges are
typically required to install into the default R library. Therefore, to
install package into the default R library to provide availability to all
users and applications, it is recommended to use an account with
administrative privileges and permissions to the default R library to
install packages.
Once installed, the MicroStrategyR library can be loaded by typing the
following command in the R Console:
library(MicroStrategyR)
This package depends on other R packages for graphics as well as the GTK+
graphical environment. The absence of the GTK+ graphical environment is
common and can cause the display of error messages:

Windows environments: Messages are displayed that mention missing

DLL files. Click OK to dismiss any error messages encountered due to
these missing requirements. When prompted, accept the installation of

10 Installing and configuring the R Integration Pack

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

the GTK+ graphical environment to complete the MicroStrategy R

Package installation.

UNIX/Linux environments: The console displays errors related to other

packages, such as the RGtk2 package. You can download the most recent
version of the GTK+ graphical environment for your operating system at
sites such as http://ftp.acc.umu.se/pub/gnome/binaries. Once
downloaded, you must manually install the GTK+ graphical environment.

Once installed, you can launch the deployR utility by typing the following
command in the R Console:
deployR()

Deploying R analytics in MicroStrategy

The steps required to implement and deploy R analytics to MicroStrategy
are:
1 Implement the analytic in R; see Implementing the analytic in R for
deployment to MicroStrategy, page 11.
2 Add features to make the R script more robust; see Best practices:
Making the R script robust, page 13.
3 Capture an analytics signature to the R script using the deployR utility
and create a metric expression; see Using the deployR utility, page 26.
For an example of deploying an R script as an R analytic in MicroStrategy,
see R analytic deployment example, page 31.

Implementing the analytic in R for deployment to MicroStrategy

Review the following considerations when implementing an analytic in R to
deploy in MicroStrategy:

Inputs and outputs of the R analytic correspond to MicroStrategy

metrics. MicroStrategy metrics represent values in a cell or column of
data in a report, dataset, grid, and so on. In other words, input and output
variables can be either scalars (a single value) or vectors (one or more
values). It is not possible to automatically pass tables, matrices, or data
frames between MicroStrategy and R when using this approach. There is
a Repeated Parameter option for R analytics that consume a variable

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

11

Using the R Integration Pack

R Integration Pack User Guide

number of inputs, which can mimic the passing of table-like structures

from MicroStrategy to R.

In addition to passing values as metric arguments, a set of Boolean,

numeric, and string parameters is available to pass into R scalar values
that do not change from execution to execution. The scripts working
directory also is a special function parameter (see Defining an R scripts
file location and working directory, page 12).

Graphs and plots can be saved to the file system for inclusion in
MicroStrategy documents and Visual Insight dashboards.

The R workspace can also be saved to the file system.

Defining an R scripts file location and working directory

The R scripts for your R analytics utilize directories to store and locate the R
script file, error log, and other supporting files. The directories for these R
script resources are determined as follows:

Location of the R script file

The R scripts directory is used, as specified in the _RScriptFile

parameter for the R analytics metric in MicroStrategy.
If the path or R script file name listed in the _RScriptFile
 parameter
for R does not exist, the execution of the R script will
fail. An R script failure can cause different error results in
MicroStrategy, depending on whether the R script is used by a
stand-alone metric or a derived metric, as described in
Implementing the tryCatch function wrapper for error handling,
page 14.

If there is no path in the _RScriptFile parameter, the directory

defined in the _WorkingDir parameter for R is used.

If there is no path in the _RScriptFile parameter and an existing

directory is not defined in the _WorkingDir parameter for R, the
directory defined in the registry key RScriptsFolder is used.

If the directory could not be located using the resources listed above, the
default RScripts folder defined during the R Integration Pack
installation is used. This is typically InstallPath\RScripts.

12 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

Location of the R script working directory

The working directory stores an error log and supporting files:

If a working directory is specified for R, the directory defined in the

_WorkingDir parameter for R is used.

If there is no working directory specified for R or the working directory

specified does not exist, the location of the R script file, as determined in
Location of the R script file above, is used.

If the directory could not be located using the resources listed above, the
the R Integration Pack installation folder is used.

Best practices: Making the R script robust

The R Integration Pack automates the execution of an R script and the
delivery of its results to MicroStrategy users. Ideally, if an R script works as
expected when executed within the R console, it should work properly when
deployed to MicroStrategy. To avoid potential errors, you can make
preparations to handle situations that can arise from differences in how data
is supplied, how exceptions are handled, and even differences in the
operating environment. For example, the deployed system can be different
from the R script developers system.
This section provides guidance to help make the R script robust enough to
handle real world circumstances that can arise, and to make troubleshooting
as easy as possible. The following best practices should be applied to the R
script before deploying it to MicroStrategy:

Implementing the tryCatch function wrapper for error handling,

page 14

Saving the R workspace, page 16

Configuring dual execution modes, page 17

Creating a data frame, page 18

Using MicroStrategy names for R variables, page 19

Installing required packages, page 20

Upgrading R, page 22

Using an R global environment, page 22

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

13

Using the R Integration Pack

R Integration Pack User Guide

Combining all techniques for a robust script, page 23

The simple R script for forecasting seasonal data, shown below, will be used
to provide examples of how to implement these best practices to make your R
scripts robust.
Simple R script
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#Train model on all records with Target values
model <- lm(Target ~ Trend + factor(Season),data=df[!is.na(Target), ])
#Return predictions from the model
Forecast <- predict(model, newdata = df[, -1])

Implementing the tryCatch function wrapper for error

handling
R provides the tryCatch function to use as a wrapper around your function
code to handle any errors or exceptions. Problems encountered while
executing code enclosed within the function are then caught and returned to
MicroStrategy via the R variable called mstr.ErrMsg (this is a reserved
name for this purpose).
If an error is returned, MicroStrategy creates an error log file with the
message. If your script generates any output files, this error log file should
appear in the same location. It is a good practice to use a working directory
specific to your script to keep its error log files separate from those from
other scripts.
The error log file is called RScriptErrors.log and users can find it in the
supporting directory for the R script (see Defining an R scripts file location
and working directory, page 12).
If the R analytic is deployed as a stand-alone metric, the error causes a report
or document execution failure, resulting in the message being displayed to
the user.
Errors in R analytics deployed as derived metrics or stand-alone metrics that
are configured as smart metrics typically do not cause report or document
execution failures. Instead, null results appear as if empty values were
returned by the R analytic. Empty results can indicate that there was a

14 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

problem executing the R analytic and that you should check the log file for
more details.
steps to define stand-alone metrics as smart metrics, also referred
For
to as smart totals, as well as background information on smart
metrics, refer to the Advanced Reporting Guide.
In both cases described above, a message is logged in the DSSErrors.log
file, unless logging is disabled via the MicroStrategy Diagnostics Utility.
DSSErrors.log is typically found at X:\
The
Program Files (x86)\Common Files\MicroStrategy\Log,
where X: is the drive where MicroStrategy is installed.
In addition to errors caught by the tryCatch function, other conditions can
result in error logging, including:

Errors during processing of registry entries, for example, problems with

the keys associated with the InstallPath and RScriptsFolder.
These errors do not cause a report to fail.

Errors loading the R library or initializing the R environment.

Errors parsing the R script header block.

Data type mismatches.

Failure locating the R script specified by the _RScriptFile parameter

for the R analytics metric in MicroStrategy (see Location of the R script
file, page 12). This can occur if a bad path or file name is specified, or if
the script is not found at the location specified by the RScriptsFolder
registry key.

example R script described in R analytic deployment example,

The
page 31 includes a command to set the working directory. It is
recommended to move this line of code to the body of the script,
within a tryCatch function wrapper. This ensures that any potential
failure of the setwd() command is caught.

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

15

Using the R Integration Pack

R Integration Pack User Guide

The following example shows how to wrap the forecasting example code in a
tryCatch function to catch errors:
R script with tryCatch
#tryCatch for Exception Handling
mstr.ErrMsg <- tryCatch({
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#Train model on all records with Target values
model <- lm(Target ~ Trend + factor(Season),data=df[!is.na(Target), ])
#Return predictions from the model
Forecast <- predict(model, newdata = df[, -1])
#Print success message when run from the console
try(print("Success!"))
#If we made it here, no errors were caught
mstr.ErrMsg <- ""
#Catch block to report an error
}, error = function(err) {
#Print error message if run from console
try(print(err))
#Return error message
return(err$message)
})

Saving the R workspace

R has the ability to save its workspace to the file system. This is helpful when
you need to revisit the results of an analysis. When executing a script from
the R console, it is easy to inspect the state of the workspace and its objects.
It is helpful to capture the R workspace when MicroStrategy executes the
script. The workspace is a valuable tool for the R developer to use when
troubleshooting problems or verifying results.

16 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

An example of code inserted to save a workspace is shown below. The

addition (highlighted with bold) to the R script shown below saves objects
from the R workspace.
R script that includes saving the R work space
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#Train model on all records with Target values
model <- lm(Target ~ Trend + factor(Season),data=df[!is.na(Target), ])
#Return predictions from the model
Forecast <- predict(model, newdata = df[, -1])
#Persist objects to file
save(list=c("df", "model", "Forecast"), file=paste(FileName, ".Rdata", sep = ""))

Configuring dual execution modes

When developing a new analytic in R, a common practice is to use an
iterative process to ensure that the analytic works as expected. That process
usually involves the R script taking inputs that are either created by the
script or read from a data source, such as a file or a database. The results of
the script are usually returned to the R console. But when the script is
deployed to MicroStrategy, MicroStrategy provides the inputs to the R script
and uses the R script outputs.
While it is possible to have the same analytic implemented in two different
scripts, one for running from the console and one for execution by
MicroStrategy, this approach requires maintaining two scripts. In this
scenario, it can be difficult to keep the scripts synchronized as changes occur.
MicroStrategy provides the execution flag mstr.ExFlag, which exists only
when MicroStrategy executes the R script. This means that you can use the
existence of the flag to determine if MicroStrategy executed the R script. You
can develop your script to use this flag and react to whether the script is run
from the R console or executed by MicroStrategy.

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

17

Using the R Integration Pack

R Integration Pack User Guide

The example shown below includes code inserted to adapt the forecasting
script example to generate its own data when it is not executed by
MicroStrategy:
Code to configure dual execution modes
#Get data
#If this is executed by MicroStrategy
if(exists("mstr.ExFlag")) {
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#If InputNames is non-empty
if(length(mstr.InputNames) > 0) {
#Name these variables
colnames(df) <- mstr.InputNames
}
#If this is NOT via a MicroStrategy Report Execution
} else {
#Set random number seed for consistency
set.seed(42)
#Set Trend variable for 48 months
Trend <- seq(1:48)
#Set Season variable for 4 years of 12 months
Season <- rep(seq(1:12),4)
#Set 3 years of linear but noisy values for the Target
Target <- (seq(1:36)*(0.8+(0.4*runif(36,0,1))))
#Add the forecast horizon
Target <- append(Target, c(rep(NA, 12)))
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#Set the name for saving output
FileName <- "SeasonalForecasting_console"
}
#Modeling
#Train model on all records with Target values
model <- lm(Target ~ Trend + factor(Season),data=df[!is.na(Target), ])
#Return predictions from the model
Forecast <- predict(model, newdata = df[, -1])

Creating a data frame

Since most analytics operate on a table of data, known as a data frame in R, it
is often helpful to combine input variables in a data frame. In the seasonal
forecast data example, the three input variables (target, trend, and season)
are combined into a data frame. Since both execution flows use the same
data frame object, you can compare the data used when MicroStrategy
executes the script with the data used when executing from the R console.
18 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

While there are reasons to avoid the use of a data frame in either flow, such
as if they cause undesired side effects like performance problems, having the
data in the same object for both flows allows for easier comparison.

Using MicroStrategy names for R variables

The R Integration Pack allows data from MicroStrategy to be passed into R
for execution by mapping MicroStrategy metrics to R variables. For the R
environment to be able to use the MicroStrategy metric names in objects and
graphics that R generates, the names associated with the inputs from
MicroStrategy need to be passed to R.
names of the metrics in MicroStrategy may not always match the
The
names of the variables in R. For R analytics, R variables typically have
generic names, as is the case with the R script example used in this
section: Target, Trend, and Season. To forecast monthly revenue, the
corresponding MicroStrategy metrics could be Revenue, Month
Index, and Month of Year.
To provide this support, each R script function has an _InputNames
function parameter where you can pass MicroStrategy names to R. When you
create a metric to display the results of your R analytic, you can also define
the _InputNames function parameter using the MicroStrategy Metric
Editor. You can use the metric expression generated for your R analytic (see
Using the deployR utility, page 26) to retrieve the inputs for your R script
(the inputs are at the end of metric expression between the final parentheses
(...)). You can then replace each input name with the associated
MicroStrategy metric that provides its data, and then copy the inputs to the
_InputNames function parameter.
For this example, the metric expression would be "RScript(Revenue,
[Month Index], [Month of Year])". Copy the metric names
(between the parentheses) and paste them to the _InputNames function
parameter to define the R analytics metric parameter as Revenue, [Month
Index], [Month of Year]. An example using MicroStrategy
Developers Metric Editor is shown below:

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

19

Using the R Integration Pack

R Integration Pack User Guide

Installing required packages

R scripts commonly have dependencies on R packages, which are modules
that provide additional functionality beyond the out-of-the-box features
included with the standard R installation. R packages are installed from
CRAN mirror repository sites. The machine executing the script must have
access to the Internet to download any missing packages.
A default CRAN mirror repository site can be established by modifying the
following code with the desired CRAN mirror URL in the RProfile file
located at the /library/base/R directory of the R installation:
options(repos= c(CRAN="CRANMirrorURL"))
For example, you can establish http://cran.rstudio.com as the default
CRAN mirror repository as shown below:
options(repos= c(CRAN="http://cran.rstudio.com"))
Packages can also be installed manually using the R console, as shown below:
install.packages("RPackage")
to be available to all users and applications, packages need to
 Inbe order
installed into the default R library. Administrative privileges are
typically required to install into the default R library. Therefore, to
install package into the default R library to provide availability to all
users and applications, it is recommended to use an account with
administrative privileges and permissions to the default R library to
install packages.
When installing packages manually, the R console will prompt you to
identify a CRAN mirror repository to use. To avoid this prompt, you can
specify a CRAN mirror repository as part of the manual installation from the
R console, as shown below:
install.packages("RPackage", repos="http://
cran.rstudio.com")
The sample R script below avoids any required user intervention to install R
packages by automatically checking for and installing R packages if
necessary. This approach assumes that the machine executing the script has
access to the Internet to download any missing packages. For environments
that do not have access to the Internet, other workflows need to be used to
add any required R packages to the environment.

20 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

R packages can require administrative access to folders. The

 Installing
sample R script below includes error handling if the user employing
the R script does not have the administrative access required to
complete the package installation. In these cases, the sample R script
below installs the package in a personal folder for the user that they
have access to, or a new folder is created. This error handling for
installing packages should be included in R scripts used in
MicroStrategy to ensure that users without administrative access can
employ the R scripts.
R script that checks for and installs missing packages
#Check to see if package(s) are installed, install if not and then load
#pkgs is a vector of strings with length >= 1
CheckInstallPackages <- function(pkgs){
#For each pkg in pkgs (attempt to load each package one at a time):
x <- lapply(pkgs, function(pkg){
#Load the package if available,
if(!do.call("require", list(pkg))) {
#Silently attempt to install into the default library
try(install.packages(pkg, lib=.Library,repos="http://cran.rstudio.com"))
#Now attempt to load the package, catch error if it wasn't installed
tryCatch(do.call("library", list(pkg)),
#Catch if we're unable to install into the default library
error = function(err) {
#If non-interactive, install into this user's personal library
if(!interactive()) {
#Get the path to this user's personal library
personalLibPath <- Sys.getenv("R_LIBS_USER")
#If the personal library is not in the list of libraries
if(is.na(match(personalLibPath, .libPaths()))) {
#Then create the personal library
dir.create(personalLibPath, recursive = TRUE)
#And add the personal library to the list of libraries
.libPaths(personalLibPath)
}
#Attempt to install the package into the personal library
#If this fails, raise the error back to the report
install.packages(pkg, lib=personalLibPath, repos="http://cran.rstudio.com")
#Finally, attempt to load the package
do.call("library", list(pkg))
}})}})
}
#Load the PMML package
CheckInstallPackages(c("pmml"))
#Save the model as PMML
saveXML(pmml(model), paste(FileName,".xml", sep=""))

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

21

Using the R Integration Pack

R Integration Pack User Guide

Upgrading R
Several times a year, new releases of R become available. The following steps
are recommended to minimize the possibility of problems when upgrading to
a new R release.
To upgrade your R environment

1 Uninstall the old version of R. Uninstalling R removes files from the

initial installation, but not packages that have been installed or updated.
to your third-party R documentation for steps to uninstall R
Refer
for your machine configuration.
2 Install the new version of R. The proper version of R must be installed
from http://CRAN.R-project.org.
3 Copy any installed packages from the old installation library folder to the
new installation library folder.
4 In the new R console, run the following command:
update.packages(checkBuilt=TRUE, ask=FALSE)
5 Delete any files left from the old installation.

Using an R global environment

The R Integration Pack uses a single R global environment when executing R
scripts. This means that R variables that are created by the execution of one
script are accessible to other scripts that are subsequently executed.
Therefore, when you are developing R scripts to be executed in the R
Integration Pack environment, use the following rules to ensure proper and
expected behavior:

Always initialize R variables prior to use.

Do not rely on a test of an R variables existence to indicate the state of

the script, since the variable may have been created by an entirely
different script.

22 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

Combining all techniques for a robust script

The simple R script example, unmodified, is shown again below:
Simple R script
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#Train model on all records with Target values
model <- lm(Target ~ Trend + factor(Season),data=df[!is.na(Target), ])
#Return predictions from the model
Forecast <- predict(model, newdata = df[, -1])

By using all of the recommendations above, the script shown below is more
robust to handle errors, generates PMML, saves important objects from the
R environment for future analysis, and can be executed using the R console
or MicroStrategy:
Robust R script
#tryCatch for Exception Handling
mstr.ErrMsg <- tryCatch({
#Working Directory if executed by MicroStrategy
if(exists("mstr.WorkingDir")) setwd(mstr.WorkingDir)

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

23

Using the R Integration Pack

R Integration Pack User Guide

Robust R script
#Check to see if package(s) are installed, install if not and then load
#pkgs is a vector of strings with length >=1
CheckInstallPackages <- function(pkgs){
#For each pkg in pkgs (attempt to load each package one at a time):
x <- lapply(pkgs, function(pkg){
#Load the package if available,
if(!do.call("require", list(pkg))) {
#Silently attempt to install into the default library
try(install.packages(pkg, lib=.Library,repos="http://cran.rstudio.com"))
#Now attempt to load the package, catch error if it wasn't installed
tryCatch(do.call("library", list(pkg)),
#Catch if we're unable to install into the default library
error = function(err) {
#If non-interactive, install into this user's personal library
if(!interactive()) {
#Get the path to this user's personal library
personalLibPath <- Sys.getenv("R_LIBS_USER")
#If the personal library is not in the list of libraries
if(is.na(match(personalLibPath, .libPaths()))) {
#Then create the personal library
dir.create(personalLibPath, recursive = TRUE)
#And add the personal library to the list of libraries
.libPaths(personalLibPath)
}
#Attempt to install the package into the personal library
#If this fails, raise the error back to the report
install.packages(pkg, lib=personalLibPath, repos="http://cran.rstudio.com")
#Finally, attempt to load the package
do.call("library", list(pkg))
}})}})
}

24 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

Robust R script
#Get data
#If this is executed by MicroStrategy
if(exists("mstr.ExFlag")) {
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#If InputNames is non-empty
if(length(mstr.InputNames) > 0) {
#Name these variables
colnames(df) <- mstr.InputNames
}
#If this is NOT via a MicroStrategy Report Execution
} else {
#Set random number seed for consistency
set.seed(42)
#Set Trend variable for 48 months
Trend <- seq(1:48)
#Set Season variable for 4 years of 12 months
Season <- rep(seq(1:12),4)
#Set 3 years of linear but noisy values for the Target
Target <- (seq(1:36)*(0.8+(0.4*runif(36,0,1))))
#Add the forecast horizon
Target <- append(Target, c(rep(NA, 12)))
#Create a data frame from the input variables
df <- data.frame(cbind(Target, Trend, Season))
#Set the name for saving output
FileName <- "SeasonalForecasting_console"
}
#Modeling
#Train model on all records with Target values
model <- lm(Target ~ Trend + factor(Season),data=df[!is.na(Target), ])
#Return predictions from the model
Forecast <- predict(model, newdata = df[, -1])
#If FileName is not an empty string
if(nchar(FileName)>0) {
#Persist objects to file
save(list=c("df", "model", "Forecast"), file=paste(FileName, ".Rdata", sep = ""))
#Load the PMML package
CheckInstallPackages(c("pmml"))
#Save the model as PMML
saveXML(pmml(model), paste(FileName,".xml", sep=""))
}

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

25

Using the R Integration Pack

R Integration Pack User Guide

Robust R script
#Print completion message when run from the console
try(print("Success!"))
#If we made it here, no errors were caught
mstr.ErrMsg <- ""
#Catch block to report an error
}, error = function(err) {
#Print error message if run from console
try(print(err))
#Return error message
return(err$message)
})

Using the deployR utility

After implementing an R analytic in an R script that is ready to be deployed
to MicroStrategy, you must define how MicroStrategy interacts with the
analytic by capturing the analytics signature. The analytics signature is a
description of the number and nature of the inputs and outputs to the R
script, along with any other information needed for MicroStrategy to execute
the script properly.

26 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

The deployR utility is an R-based utility that analyzes an R script, captures

its signature, and creates the metric expressions that execute the function
within MicroStrategy. The image below shows the deployR utility.

The standard workflow for using the deployR utility to capture the signature
of your R analytic and deploy it to MicroStrategy follows.
To deploy R scripts using the deployR utility

1 From an R console, open the deployR utility using the following

commands:
library(MicroStrategyR)
deployR()
The deployR utility opens.
2 Click the Open button at the upper left to open your R script.
After you open your R script, the deployR utility parses the script to
identify all potential variables.

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

27

Using the R Integration Pack

R Integration Pack User Guide

If this script contains the MicroStrategy header block at the top, then
that information is used to configure the utility and any variables not
identified are displayed in the Unused Variables column.

If there is no MicroStrategy header block, the deployR utility attempts

to determine whether a variable is an input or an output, based on the
first occurrence of that variable in the script. If the variables first
occurrence assigns it a value, it is considered an output; otherwise, it
is designated as an input.

For new variables, the default Data Type is Numeric and the default
Parameter Type is Vector.

3 Determine the path that is used for the R script using one of the following
methods:

To include the selected R scripts file name and path in the metric
expression, clear the Use R Script Folder check box. When executed,
the specified R script file name and path will be used. If the R script is
not found, execution will fail and an error will be logged, if possible.

To include only the file name of the R script in the metric expression,
select the Use R Script Folder check box. When executed, the R
Script Folder is searched for the specified script. If the R script is not
found, execution will fail and an error will be logged, if possible. The
default location for the R Script Folder is
RIntegrationPackInstallFolder\RScripts. This location is
controlled by the HKLM\SOFTWARE\MicroStrategy\
R Integration Pack\RScriptsFolder registry key.

4 Modify the definition of each variable as required to match the functions

logic.
a Drag and drop variables to place them in the appropriate columns:
Unused Variables: Variables that appear in the R script but are
not passed between MicroStrategy and R as either inputs, outputs,
or parameters. The order of unused variables does not affect the R
script execution.
Input: Indicates data imported into R from MicroStrategy. The
order of inputs, from top to bottom, determines the order of
arguments passed in from MicroStrategy, from left to right.
Parameter: Allows data to be passed as one of the various function
parameters available for passing scalar values from MicroStrategy
to R. These function parameters include Boolean parameters,
numbers, and strings. Parameters are typically used for values that

28 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

are changed infrequently or values that are not determined from

other metrics.
Use the Parameter drop-down list to specify which parameter to
use. Each parameter can only be used for one variable. The order
of parameters does not affect the R script execution.
Output: Indicates data returned from R to MicroStrategy. If there
is more than one output, the first output is considered the default
output.The order of any additional outputs does not affect the
signature.
b Each variable must be configured appropriately:
a Set Data Type to one of the following options:
Numeric: Indicates variables that contain numbers.
String: Indicates variables that contain text.
Default: Indicates that the data type defined by MicroStrategy
should be used. This setting can be used for inputs only. It is
useful for scripts that use categorical variables, such as Month.
This type of categorical variable might be strings, such as Jan,
Feb, Mar, and so on, or numbers.
b Set Parameter Type to one of the following options:
Vector: Indicates a variable that contains one or more values.
Scalar: Indicates a variable that contains only one value.
5 If one or more of the variables form a repeated argument, define a value
for Repeat Count.
This option identifies an input that can vary in quantity; such variables
are known as repeated arguments because they represent a varying
number of variables. The Repeat Count value specifies how many of the
variables may be repeated, counting backwards from the last variable.
These variables always occur at the end of the list of arguments. These
variables appear in the Inputs column with an asterisk (*). Examples
include:

A predictive analytical function supports one target variable Y (the

dependent variable) and an indeterminate number of explanatory
variables X (independent variables). Establish this configuration by
defining Y as the first variable, defining X as the second variable, and
defining a Repeat Count value of 1. The deployR utility recognizes that

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

29

Using the R Integration Pack

R Integration Pack User Guide

Y is the first argument passed into the function, followed by one or

more X variables.

A predictive analytical function supports one target variable Y (the

dependent variable) and an indeterminate number of explanatory,
independent variable pairs, X1 and X2, with X1 as a numeric identifier
for an item and X2 as its text description. By defining Y as the first
input, X1 as the second, X2 as the third, and a Repeat Count value of
2, the deployR utility recognizes that Y is the first argument and there
can be one or more pairs of X1 and X2 variables passed into the R
script.

6 You can define the metric that utilizes the R script using the Metric
Specification section, which contains the following options:

Nulls Allowed: Controls whether records containing null values are

to be passed in as inputs to your analytic:
By default this option is selected and null values are included in
the analysis.
If cleared, all records containing null values are eliminated from
the analysis.

Check Input Count: Controls whether MicroStrategy ensures that the

number of inputs to the metric matches exactly with the number of
inputs specified in the functions signature.
By default, the option is selected. If it is selected and the number of
inputs is different, a warning message is returned when using the
R script in MicroStrategy.
If it is cleared and the number of inputs is different, the script
execution will attempt to proceed.

Enable Sort By: Controls the sorting of records before the data is
passed to R.
By default, the option is selected. If this option is selected, the first
input must be a vector, since the default behavior sorts records in
ascending order by the first input. To specify a particular sorting
criterion, you can type the sort by value in the field below the check
box.
If this option is cleared, the order of records passed into R is
determined by MicroStrategy automatically.

30 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

Specify Working Directory: Allows you to specify a working

directory for your R scripts used in MicroStrategy, without affecting
your R configuration.
By default, this option is cleared and the path provided for each R
script is used.
To specify a working directory for MicroStrategy to search for R
scripts, select the check box and specify a working directory in the
field below the check box. MicroStrategy does not alter Rs
working directory, which is otherwise determined by R.

Output Variable: Allows the user to control which variable is returned

to MicroStrategy. The first output of an R script is selected by default.
This output variable is not included in the metric expression.

7 To review the changes before saving, click Preview.

8 After you have configured the variables and specified the metric options,
you can save the analytics signature to the R script by clicking Save.
9 After saving the signature to your R script, the deployR utility provides
the metric expression for your analytic. The Metric Expression pane at
the bottom right of the dialog box shows the metric expression that
defines how MicroStrategy interacts with your function. To complete the
creation of a metric for your R analytic:
a Click Copy to Clipboard, and then paste this metric expression into
any MicroStrategy metric editor, including the metric editors
available for MicroStrategy Developer, MicroStrategy Web,
MicroStrategy Analytics Desktop, and MicroStrategy Visual Insight.
b Map each of the inputs of the expression, which are included between
parentheses, to MicroStrategy metrics that provide the data for
statistical analysis. An example of this modification is provided in R
analytic deployment example below.

R analytic deployment example

Below is the R script for the forecasting analytic described in Combining all
techniques for a robust script, page 23. It is also available as part of the
installation package in the default RScripts folder as a file called
SeasonalForecasting.R. This example explains how to deploy this script
with the MicroStrategy Tutorial project available with MicroStrategy
Analytics Enterprise.

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

31

Using the R Integration Pack

R Integration Pack User Guide

The header block for this R script is as follows:

#MICROSTRATEGY_BEGIN
#
#RVAR target -input -numeric -vector
#RVAR trend -input -numeric -vector
#RVAR Season -input -vector
#
#RVAR FileName -parameter StringParam9
#
#RVAR Forecast -output -numeric -vector
#Metric Expression:
RScript<_RScriptFile="SeasonalForecasting.R",
_InputNames="Target, Trend, Season", StringParam9="">
(Target, Trend, Season)
#
#MICROSTRATEGY_END
This header includes the following features:

Lines that begin with # are considered comments and are ignored by R.

MicroStrategy processes the contents between the

#MICROSTRATEGY_BEGIN and #MICROSTRATEGY_END lines to
understand the analytics signature. You should not edit this block
manually because doing so can cause errors.

If you modify the R script or want to change anything else, you can open
the R script using the deployR utility. The deployR utility automatically
restores everything in the header, as well as looks for any new variables in
the script. You can then use the deployR utility to make your
adjustments. Saving any changes replaces the existing header block with
an updated one, and provides the updated metric expression as well.

The metric expression for each output, highlighted with bold text above,
is included in this header block, and is ready to copy and paste into a
metric definition.

The following steps describe how to deploy this analytic to MicroStrategy

Analytics Enterprise.
To deploy the sample R analytic

1 Copy the metric expression to the clipboard.

32 Deploying R analytics in MicroStrategy

2014 MicroStrategy, Inc.

R Integration Pack User Guide

Using the R Integration Pack

2 Open the MicroStrategy Tutorial project in either Developer or Web and

run the report named 2 -- Monthly Revenue Forecast located by
default at Tutorial\Public Objects\Reports\
MicroStrategy Platform Capabilities\
MicroStrategy Data Mining Services\Linear Regression\
Monthly.
3 When the report finishes executing, insert a new metric and provide it a
name such as Forecast from R. Paste the metric expression into the new
metric.
4 Map the three inputs to MicroStrategy metrics using the following steps:
a Highlight Target in the expression and replace it with Revenue from
the Report Objects.
b Highlight Trend in the expression and replace it with Month Index
from the Report Objects.
c

Highlight Season in the expression and replace it with Month of

Year from the Report Objects.

5 Click OK to re-execute your report.

The values for your new metric generated by R match those from the
Revenue Predictor (Monthly) metric, because they are both linear
regression models trained with the same data as on this report.
6 Depending on the execution of the R script, you can do one of the
following:

Locate the Forecast.Rdata file in your working directory, open it,

and explore the R environment that is saved when your function
executes.

If you did not get results, check the DSSErrors.log file for
information on any errors detected.

2014 MicroStrategy, Inc.

Deploying R analytics in MicroStrategy

33

Using the R Integration Pack

34 Deploying R analytics in MicroStrategy

R Integration Pack User Guide

2014 MicroStrategy, Inc.

INDEX
A
analytic implementation in R 11

B
best practices
creating a data frame 18
dual execution mode 17
example of a robust R script 23
installing an R package 20
making the R script robust 13
R global environment 22
tryCatch function wrapper 14
upgrading R 22

C
Comprehensive R Archive Network
(CRAN) 10

D
data frame creation 18
deploying an R script 11
deployR utility 3, 10
deploying R scripts 27

2014 MicroStrategy, Inc.

using 26

E
examples
dual execution mode 18
R analytic deployment 31
R package installation 20
R script to save the R workspace 17
R script with the tryCatch function 16
robust R script 23
simple R script 14

I
installing
MicroStrategyR Package 10
RScript Functions Installer 5

M
MicroStrategy
documentation 2
Function Plug-in family 1
R Integration Pack 1

35

Index

R Integration Pack User Guide

MicroStrategyR Package for R 3

deployR utility 10
installing 10

RScript Functions Installer

installing 5
post-installation requirements 8

parameters for an R script 19

Predictive Model Markup Language
(PMML) 20
prerequisites for the R Integration Pack 3
project, adding R scripts to 8

saving the R workspace 16

R
R 1
environment prerequisites 4
global environment 22
installing a package 20
MicroStrategyR Package 3
mstr.ErrMsg variable 14
saving the workspace 16
upgrading 22
variables 19
R Integration Pack 1
components 2
prerequisites 3
R script
adding to an existing project 8
analytic deployment example 31
best practices 13
deploying 11
using the deployR utility 27
example
robust 23
simple 14
folder 28
implementing an analytic 11
parameters 19
RScript Functions 2

36

T
troubleshooting function code using the
tryCatch function wrapper 14

U
upgrading R 22

V
variable
mstr.ErrMsg 14
R 19

2014 MicroStrategy, Inc.