The Anatomy of a JMP Genomics Analytical Process

To begin to understand how JMP Genomics processes operate, let's peruse the SAS code associated with the Column Contents process. This code is contained in the DataContents.sas file located in the ProcessLibrary folder of your JMP installation directory.

Navigate to the DataContents.sas file.

Typically, when JMP Genomics is loaded on a Windows machine, the default path to this file is C:\Program Files\SASHome\JMPGenomics\13\Genomics\ProcessLibrary\.

Open the DataContents.sas file with a text editing program.

The SAS code for the Column Contents process should appear as follows:

JMP Genomics Analytical Process

Name: DataContents

Author: Russ Wolfinger, SAS Institute Inc.

Support: Tzu-Ming Chu, SAS Institute Inc.

History:

sasrdw 10Sep02 initial coding

Description:

DataContents displays the contents of a SAS data set.

It calls PROC CONTENTS and outputs the results in

HTML format. You can also print out all or a portion

of the data set using PROC PRINT. These results are

also in HTML.

-----------------------------------------------------------

Notice:

The above copyright notice and this notice must appear in

any whole or partial copy of this code and any related

documentation. Permission to use, copy, and modify the

source code contained in this file is hereby granted, but

is limited to customers of SAS with a valid license for the

SAS software product with which this file was provided.

Except as expressly set forth herein, the terms of such

license apply.

-----------------------------------------------------------

*ProcessVariables;

%global InData Print ColumnSubset NumVars OutPath MacroPath DataContents_Frame DataContents_Body

DataContents_Contents;

*ProcessBody;

%macro DataContents;

%let ProcessName = DataContents;

%include "&MacroPath./UtilityMacros.sas" / nosource;

%GetOrigFileName(InData,OrigInData);

%PathName(&InData);

%if &exiterror %then %do;

%put ERROR: Input dataset specification is invalid.;

%goto exit;

%end;

%let InData = &TmpName;

libname InLib "&TmpPath";

libname OutLib "&OutPath";

%PrepHTML(datacontents_body, datacontents_frame, datacontents_contents,&OrigInData._Body.html,&OrigInData._Frame.html,&OrigInData._Contents.html);

* setup for html output;

ods html

body = "&DataContents_Body" (url="&bodyfile")

frame = "&DataContents_Frame"(url="&framefile")

contents = "&DataContents_Contents" (url="&contentsfile")

;

ods listing close;

%if %upcase(&ColumnSubset)=YES %then %do;

%let dsid=%sysfunc(open(InLib.&InData,i));

%let first=%sysfunc(varname(&dsid,1));

%let totvars=%sysfunc(min(&NumVars,%sysfunc(attrn(&dsid,nvars))));

%let last=%sysfunc(varname(&dsid,&totvars));

%let rc=%sysfunc(close(&dsid));

data &InData;

set InLib.&InData;

keep &first--&last;

run;

%end;

%else %do;

data &InData;

set InLib.&InData;

run;

%end;

* create output;

proc contents data=&InData;

run;

%if %length(&Print)>0 %then %do;

proc print data=&InData

%if (%qupcase(&Print)^=ALL) %then %do;

&Print

%end;

;

run;

%end;

ods html close;

ods listing;

%PackageInsertHtml(html from &ProcessName, &OutPath, &bodyfile, &framefile, &contentsfile);

%exit:;

%ExitSDSProcess(&OutPath, &ProcessName, &syserr, &exiterror, &clockrunning);

%mend DataContents;

* execute macro;

%DataContents

The SAS code for a JMP Genomics process contains these primary sections:

•

Preamble

•

Process Variable Definitions

•

Initialization and Argument Checking

•

SAS Data Step and Procedure Code

•

JSL File Generation (optional)

•

Package Publication

•

Macro Conclusion and Invocation.

Each section makes extensive use of SAS macro variables to enable flexibility and reuse. JMP Genomics software resolves all of these variables at run time to create an executable SAS program. The software then submits this code using SAS in batch mode. Output in this case is an .html file, which is automatically launched. Details on each of the coding sections are as follows:

Preamble

The Preamble is the introductory section of the code and can be used to keep track of change dates, special instructions, or whatever other preliminary information you want to include. It should be enclosed in a standard SAS comment block, /* */.

In the Column Contents code example, there is author information and a simple history section. The history section is provided so that future changes to the file can be registered in subsequent lines.

In processes that are supplied by SAS, a copyright notice appears in the preamble.

Process Variable Definitions

Each process contains a set of process variables, which are the input parameters to be set before running the routine. JMP Genomics software automatically generates an input dialog box for each of these parameters according to a format that you specify in an associated .xml file (see JMP Genomics XML Tags, Attributes, and Values). You have the ability to modify, save, and load your own settings for these variables each time you invoke the process.

The Column Contents process has nine process variables: InData, Print, ColumnSubset, NumVars, OutPath, MacroPath, DataContents_Frame, DataContents_Body, and DataContents_Contents.

You must conform to the following conventions when defining process variables:

•

Begin the section by typing the following SAS comment, with no spaces: *ProcessVariables;.

•

Define each variable with a unique name in a %global statement. These names correspond to SAS macro variables that are to be automatically assigned values specified by the user of the process.

•

No spaces are allowed in the variable name. However, you can use mixed case to delineate distinct parts of the name.

•

Always specify the MacroPath process variable in your list. This variable contains the location of the folder containing SAS macro files that are %include'd in subsequent statements.

•

Conclude the process variable definitions section by typing the following SAS comment, with no spaces: *ProcessBody;.

Initialization and Argument Checking

The initialization section immediately follows the *ProcessBody; statement and is used to define your primary SAS macro block and to perform various tasks that are necessary for process execution. The initialization section should begin with a %macro statement and then contain one or more of these statements:

•

%include statements to retrieve macros or SAS code that is defined in other files

•

LIBNAME statements for referencing file locations

•

%let statements to define macro variables not surfaced to the user

•

other statements needed to prepare for subsequent processing

For Column Contents, the initialization section begins by starting a macro called DataContents and by defining the macro variable ProcessName with the same value. This convention enables you to reference the process name in subsequent utility routines provided with the system.

Note: The %DataContents macro and the primary macros for other processes have no direct functional arguments. All of the input values are defined previously as macro variables using the %global statement. If you prefer to use argument-style macros, you can %include their definition files and then assign their arguments appropriately.

The file UtilityMacros.sas contains a collection of macros that are provided with the system. You should always %include this file near the beginning of your code. You can find this file and others in your JMP installation folder.

Navigate to the location of the UtilityMacros.sas file.

Typically, when JMP Genomics is loaded on a Windows desktop machine, the default path to this file is C:\Program Files\SASHome\JMPGenomics\13\LifeSciences\MacroLib\.

Open the UtilityMacros.sas file with a text editing program.

Examine the contents of the UtilityMacros.sas file.

In addition to providing the definitions for numerous macros, the UtilityMacros.sas file provides some code (located near the end of the file) that is executed to initialize the process.

The Column Contents process uses two of the macros defined in the UtilityMacros.sas file:

The %GetOrigFileNamelock macro obtains the original filename of the specified data set and assigns it to the macro variable OrigFileName.

The %PathName utility macro parses the InData variable so that you can create a SAS LIBNAME and MEMNAME from it.

Whenever possible, you should provide error checking code to help diagnose and troubleshoot unintended results. Use the exiterror macro variable and the SAS syserr macro variable as flags for this, and the %exit: macro label at the end of the code to provide an exit point when an error condition is set or detected.

SAS Data Step and Procedure Code

This section is the heart of the process. It is here that you use all of the previously-defined macros and macro variables to perform the principal operations of the code. You can make this section as simple or as complex as you want. You have the full power of SAS at your disposal, and you can invoke any of the SAS procedures that are available on your machine. You can even use the %LaunchExternalProgram macro to run executables from other languages.

You should write this section generically so that it is reusable with any suitable set of process variables.

For Column Contents, this section performs five basic tasks:

It prepares three .html files and executes an ODS statement that sets up these files for capturing subsequent output in .html.

It creates a subset of the data for the case when the Use a Subset of Columns option is checked.

It provides a standard invocation of the CONTENTS procedure.

If you have specified a printing option, it calls the PRINT procedure, including some macro logic, to accommodate your specifications.

It executes a second ODS statement to close the .html file generation.

JSL File Generation

The Column Contents process does not generate a JMP script.

See Creating a JSL File for Dynamic Graphics and Analyses for a detailed discussion of JSL file generation.

Package Publication

In the packaging section, all of the components of the process that you want to return to the user are bundled together. Package contents can include SAS data sets, SAS output in various forms like text, .html or .pdf, and .jsl files. You create the package by invoking one or more utility macros. This process calls the %PackageInsertHtml macro and inserts the three .html files into the package. Other packaging macros available, but not used here, include %PackageInsertDataset for SAS data sets and %PackageInsertFile for text files.

Macro Conclusion and Invocation

This is the final section of the process and includes all statements that are necessary for successful termination of the macro. The Column Contents process concludes as follows:

The %exit: macro label is the argument for prior %goto statements called whenever there is an error.

The first %if statement checks the error flags and prints a message to the log if they are nonzero.

The %ExitSDSProcess macro concludes packaging, prints error messages, and calls the %ClockStop macro to print the execution time to the log.

The %mend statement concludes the macro definition and the %DataContents statement runs the macro.

Next: Adding and Deleting JMP Genomics Analytical Processes