SAS Code to Run Performance Reports

Overview of the SAS Code to Run the Performance Reports

After you have created the data sets that define the report specifications and have extracted the model from the publishing channel, you then run the %MM_RunReports() macro to create the reports for one or more time periods. Using the data sets that were created to define the report specifications, the %MM_RunReports() macro uses the report specifications to create the reports. The report specifications include the type of report to create, such as characteristic, stability, or model assessment. Other report specifications include the target variable, the libref, and the data set name that is used as the performance data source, variables to keep and drop from reports, e-mail addresses to send report notifications, and performance index warnings and alerts.
To run the %MM_RunReports() macro, your code must accomplish the following tasks:
  • access the reporting macros
  • define the librefs and the macro variables that are required by the %MM_RunReports() macro
  • specify the performance data set to process. To do this, execute a DATA step before each %MM_RunReports() macro
To ensure that you have the latest model, extract the model from the channel each time you create the performance reports. For this reason, you could combine into one SAS program the extraction process and the code to run the reports.
If you run a set of batch jobs every night, you could include this batch job with that set of batch jobs. The reports would be created only after the scheduled date and time that is specified in the mm_jobs.jobtime data set.
The following sections describe each of these components of your SAS program. The last section is an example of a program that is used to test the %MM_RunReports() macro.

Accessing Model Management Report Macros

The %MM_RunReports() macro, the %MM_GetModel() macro, and all other Model Management macros are available in the catalog sashelp.modelmgr.reportmacros.source. Use the following FILENAME statement to make these macros available to your program:
filename repmacro catalog 'sashelp.modelmgr.reportmacros.source';
%inc repmacro;

Required Librefs

The following librefs are required in your report monitoring program:
mm_jobs
defines the local path to the folder that contains the report job files.
Example: libname mm_jobs "c:\mmReports\HMEQ";
mm_meta
defines the local path to the folder that stores the data sets that are created from running the %MM_GetModels() macro. The value of this libref must have the same value as the localPath argument for the %MM_GetModels() macro.
Example: libname mm_meta "c:\mmReports\HMEQ\model";
scoreIn
specifies a user-defined libref that points to the local path that contains the performance data sources.
Interaction: You can use this libref when you set the value of Model Management macro variables, such as _MM_ReportDatasrc, in the precode variable of the mm_jobs.project data set. Here is an example: %let _MM_ReportDatasrc=scoreIn.foo.
Example: libname scoreIn "c:\mmReports\project1\perfdatasets";

Macro Variables to Define Report Local Folders and Data Sets

Define the following macro variables in your report monitoring program. Then define the location of the job and model on the local computer:
_MM_JobLocalPath
specifies the path on the local computer that contains the root folder for the reporting files of a given modeling project.
Example: %let _MM_JobLocalPath=c:\mmReports\HMEQ1;
_MM_ModelLocalPath
specifies the path on the local computer that contains the model after it has been extracted from the SAS Metadata Repository.
Example: %let _MM_ModelLocalPath=c:\mmReports\HMEQ\model;
mapTable
specifies a libref and data set in the form libref.dataSet that contains the mapping of the project output variables to the model output variables. When the model is extracted from the channel, the data set current.sas7bdat is extracted to the folder that contains the model. Use this data set as the value of mapTable.
Example: mapTable=mm_meta.current. The data set name current is arbitrary. It is recommended that you use the name current.
For a description of the macro variables, see Macro Variables.

Macro Variables That Are Used by the %MM_RunReports() Macro

Required Macro Variables

The following macro variables are required to run the %MM_RunReports() macro:
_MM_ServiceRegistry_URL
specifies the service registry to set the environment.
Example: %let _MM_Service_Registry_URL=%nrstr(http://myServer:80/SASWIPClientAccess/remote/ServiceRegistry);
_MM_User
specifies a valid user.
_MM_Password
specifies the password for the user who is identified in the _MM_User macro variable.
For a description of the macro variables, see Macro Variables.

Optional Macro Variable

The example programs use the following global macro variable, which you might find useful in your report monitoring program:
_MM_ReportMode
specifies the mode to run the %MM_RunReports() macro. Valid values are TEST and PRODUCTION. The default value is PRODUCTION. You might want to use a value of TEST while you are testing your program. When the value is TEST, the report output files are written to the local computer. When the value is PRODUCTION, the report output files are written to the appropriate project folders in the model repository.
Interaction: If _MM_ReportMode is set to TEST, you must supply a value for the testDestination variable in the mm_jobs.project data set.
Example: %let _MM_ReportMode=TEST;
For a description of the macro variables, see Macro Variables.

Encoding SAS Model Manager User Passwords

Each time that your run a SAS program to be processed by SAS Model Manager, you specify a user ID and assign the user's password to the global macro variable _MM_Password. In order to not store passwords in clear text, you can use the PWENCODE procedure to encode a password and store it in a file, in a network-accessible directory. Then, in your SAS program, you create a fileref to the network file that contains the encoded password and you use a DATA step to assign the encoded password to the _MM_Password global macro variable.
In a separate SAS program, encode your password:
filename pwfile "my-network-path\pwfile";

  proc pwencode in="12345" out=pwfile; 
  run;
In your SAS program, use a DATA step to access the encoded password file:
filename pwfile "my-network-path\pwfile";
%let _MM_User=mmuser1;
data _null_;
   infile pwfile obs=1 length=l; 
   input @;
   input @1 line $varying1024. l; 
   call symput('_MM_Password',substr(line,1,l)); 
run;

The DATA Step to Access the Performance Data Set

You use a DATA step to access the performance data set before you run the %MM_RunReports() macro:
DATA libref.dataStepName;
   set libref.performanceDataSetName;
run;
   
Here is an example of a DATA step to access the performance data set:
DATA scoreIn.hmeq;
   set scoreIn.hmeq_2013q1;
run;

The %MM_RunReports() Macro

Description of the %MM_RunReports() Macro

You use the %MM_RunReports() macro to create or update the data sets that underlie the performance monitoring reports. Before each %MM_RunReports() macro that you specify in your program, you might want to update the performance data set by including a DATA step that accesses the performance data set input file.
The %MM_RunReports() macro uses the data sets that are stored in the library that is specified by the mm_jobs libref. These data sets define the report specifications and are the data sets that are created in the report specification program. For more information about the report specification program, see Define the Report Specifications.

Syntax

Use the following syntax for the %MM_RunReports() macro:
%MM_RunReportss(localPath=&_MM_JobLocalPath, mapTable=&mapTable,
user=&_MM_User, password=&_MM_Password, <currentTime=&currentTime>);

Syntax Description

localPath=&_MM_ModelLocalPath
specifies the path on the local computer to the location where the %MM_GetModels() macro stores the files extracted from the channel. The %MM_RunReports() macro retrieves the score code from the score code folder, which is a subfolder of &_MM_ModelLocalPath.
Example: localPath=&_MM_ModelLocalPath
mapTable=&mapTable
specifies the name of the data set that contains metadata about the extracted model. mapTable is the data set named current.sas7bdat that is created when the model is extracted using the %MM_GetModels() macro. No modification of this argument is necessary.
Example: mapTable=&mapTable
user=&_MM_User
specifies a valid user. Use the macro variable that defines the valid user.
Example: user=&_MM_User
password=&_MM_Password
specifies the password for _MM_User. Use the _MM_Password global macro variable that defines the password for the user. The value of _MM_Password is a text string.
Example: password=&_MM_Password
currentTime=currentTime
specifies a time to use for the current time. Use this argument for testing the %MM_RunReports() macro. You do not need to specify an argument for currentTime when you run the macro in a production environment, where the system timestamp is used as a value for currentTime.
The value of currentTime must be in the form ddmmmyyyy:hh:mm:ss where dd is a two-digit year, mmm is the first three letters of the month, yyyy is a four-digit year, hh is a two-digit hour, mm is a two-digit minute, and ss is a two-digit second.
Example: currentTime=03Jul2013:12:15:30

Example %MM_RunReports() Macro

The following code is an example of using the %MM_RunReports() macro:
%MM_RunReports(
   localPath=&_MM_ModelLocalPath,
   mapTable=&mapTable,
   user=&_MM_User,
   password=&_MM_Password);

Example Code to Run the Reports

The following example program defines the librefs and macro variables to test the %MM_RunReports() macro's ability to assess home equity performance data for multiple time periods. Before this section of code can be run, the report specifications must be defined in SAS data sets and the model must be extracted from the publishing channel. For more information, see Define the Report Specifications and Extracting the Champion Model from a Channel.
The example program sets the current time to a time that would trigger the creation of data sets or the updating of data sets that underlie the model monitoring reports. When you run your batch program in a production environment, you do not need a variable to set the current time. When no value is set for the current time, the %MM_RunReports() macro uses the system timestamp as the value of the current time variable.
The highlighted values are user-supplied values.
/* Source file name: sashelp.modelmgr.reportExample4.source */

FILENAME repmacro catalog 'sashelp.modelmgr.reportmacros.source';
%inc repmacro;

/* Fileref to the encoded password                */

FILENAME pwfile "my-network-path\pwfile"; 

/**************************************************/
/* Specify the report execution metadata and      */
/* configure the _MM_ macro variables to run the  */
/* report job in TEST mode.                       */
/**************************************************/
  
%let _MM_ReportMode=TEST;
%let _MM_User=mmuser1;
data _null_;
   infile pwfile obs=1 length=l; 
   input @;
   input @1 line $varying1024. l; 
   call symput('_MM_Password',substr(line,1,l)); 
run;
;

%let _mm_Service_Registry_URL=
   %nrstr(http://myServer:80/SASWIBClientAccess/remote/ServiceRegistry);
%let _MM_PathMayChange=Y;

%let _MM_JobLocalPath=c:\mm.test\report.auto;
%let _MM_ModelLocalPath=c:\mm.test\model.extraction;

LIBNAME mm_jobs "&_MM_JobLocalPath";
LIBNAME mm_meta "&_MM_ModelLocalPath";
LIBNAME scoreIn 'c:\mm.test\score.in';

%let mapTable=mm_meta.current;

/***************************************************/
/* DATA step scoreIn.hmeq0                         */
/*                                                 */
/* First, run the 2012Q4 report.It is necessary to */
/* artificially declare a "currentTime" argument   */
/* of 01Jan2013 in order to trigger the report     */
/* execution scheduled for the 2012Q4 interval.    */
/***************************************************/
  
DATA scoreIn.hmeq0; 
  set scoreIn.hmeq_2012Q4; 
run;

%let currentTime=01Jan2013:12:30:15; 
%MM_RunReports(
  localpath=&_MM_JobLocalPath, 
  currentTime=&currentTime,
  mapTable=&mapTable, 
  user=&_MM_User, 
  password=&_MM_Password);

/***************************************************/
/* Now, run the 2012Q1 report. It is necessary to  */
/* artificially declare a "currentTime" argument   */
/* of 03Apr2012 in order to trigger the report     */
/* execution scheduled for the 2012Q1 interval.    */
/***************************************************/
  
DATA scoreIn.hmeq0; 
  set scoreIn.hmeq_2012q1; 
run;

%let currentTime=03Apr2012:12:30:15;
%MM_RunReports(
  localpath=&_MM_JobLocalPath, 
  currentTime=&currentTime,
  mapTable=&mapTable, 
  user=&_MM_User, 
  password=&_MM_Password);
  
/***************************************************/
/* Now, run the 2012Q2 report. It is necessary to  */
/* artificially declare a "currentTime" argument   */
/* of 03Jul2012 in order to trigger the report     */
/* execution scheduled for the 2012Q2 interval.    */
/***************************************************/
  
DATA scoreIn.hmeq0; 
  set scoreIn.hmeq_2012q2; 
run;
  
%let currentTime=03Jul2012:12:30:15;
%MM_RunReports(
  localpath=&_MM_JobLocalPath, 
  currentTime=&currentTime,
  mapTable=&mapTable, 
  user=&_MM_User, 
  password=&_MM_Password);

/***************************************************/
/* Now, run the 2012Q3 report. It is necessary to  */
/* artificially declare a "currentTime" argument   */
/* of 03Oct2012 in order to trigger the report     */
/* execution scheduled for the 2012Q3 interval.    */
/***************************************************/
  
DATA scoreIn.hmeq0; 
  set scoreIn.hmeq_2012q3; 
run;
 
%let currentTime=03Oct2012:12:30:15;
%MM_RunReports(
  localpath=&_MM_JobLocalPath, 
  currentTime=&currentTime,
  mapTable=&mapTable, 
  user=&_MM_User, 
  password=&_MM_Password);

/***************************************************/
/* Now, run the 2012Q4 report. It is necessary to  */
/* artificially declare a "currentTime" argument   */
/* of 03Jan2013 in order to trigger the report     */
/* execution scheduled for the 2012Q4 interval.    */
/***************************************************/
  
DATA scoreIn.hmeq0; 
  set scoreIn.hmeq_2012q4; 
run;
 
%let currentTime=03Jan2013:12:30:15;
%MM_RunReports(
  localpath=&_MM_JobLocalPath, 
  currentTime=&currentTime,
  mapTable=&mapTable, 
  user=&_MM_User, 
  password=&_MM_Password);