SAS Viya Custom Steps

By Paul Burgess

Within SAS Viya Studio there is a library of Steps available to users out of the box:

At the time of writing there are approximately 30 steps available, performing a range of data management, visualisation, and statistical tasks. The list is growing with each release of SAS Viya. Steps have a user interface, to set their parameters and in the background SAS code to perform the functionality. They are used by incorporating into SAS Studio Flows, or in stand-alone mode.

Comparing to the SAS 9 world similarities to both SAS Data Integration Studio and SAS Enterprise Guide are evident. Steps can be viewed as the equivalent of transformations within SAS DI Studio, in that typically they have an input and output node, and options to set associated parameters. In SAS EG, we have tasks. Many of the steps within SAS Studio perform functions similar to the tasks in EG, for example the Query task in EG is analogous to the Query step in SAS Studio. (Note, SAS Studio also has tasks, which are perhaps more analogous to the tasks within SAS Studio).

But what if you want a Step within SAS Studio, to perform a task that is not covered by the ‘out of the box’ list? All is not lost; you can create your own Steps – Custom Steps to perform the task. Your Custom Step can be shared with users within your organisation. A library of Custom Steps can be created, covering the requirements of your organisation. As well as making life easier for SAS programmers, the advantage of using a library of Custom steps is that you ensure consistency across the organisation and by using good practice to test and release the Custom Steps, ensure good programming disciplines are used.

Now let’s have a look at how to generate a Custom Step.

Generating Custom Steps

Custom Steps consist of an interface to set the parameters for the Step, written in JSON and SAS code to perform the task within the step. To make life easier to write the Custom Step there are wizards available which will generate the user interface JSON code for you and example Custom Steps, that you can use as a template.

Have a look at the ‘Starter templates’, these are very useful for showing how to define the interface, use macro variables in your SAS code and generate more sophisticated Custom Steps using dynamic cascading prompts.

Let’s generate a Custom Step. The example illustrated here is to add a field to a data set called Body Mass Index (BMI), and if required, round this to the nearest integer using a selected SAS function (INT, CEIL or FLOOR). BMI is derived from a person’s height and weight:

• BMI = Weight/Height²

Create the User Interface – Page 1, Table and Field Selection

Select ‘Custom Step quick start’ and the following interface is displayed.

There are three tabs on the interface:

• Designer – This is where we add Controls to build the user interface.
• DesignerPrompt UI – This contains the JSON code for our user interface. As we build the interface using the Designer tab, the JSON code will be written for us. If you are skilled with JSON, you can edit or write code in this tab directly.
• Program – Contains the SAS program to perform the task.

From the Designer tab, firstly name the first page for the Custom Step. We will have two pages, the first to select an input data set and variables and the second to set options. Change the default ID and label as illustrated:

Next add a control. The first thing we need is an input data set, so add the ‘Input Table’ control as shown in the picture below

In the properties pane, the ID property has been left as the default value, note this will become a macro variable name when we write the SAS code. The other parameters have been left as the default values.

Next add a ‘Column Selector’ control to select the first input variable, the height field, (as shown in the picture below) and set the properties:

• The ID has been changed to ‘height’.
• The label changed to ‘Height’
• In ‘Link to input table’ we have selected ‘Inputtable (inputtable 1)’– the input table created in our previous control.
• The ‘Column type’ is set to numeric – we can only generate BMI from a numeric column.
• Minimum and Maximum columns are both set to 1, as we just require a single column for ‘weight’.

Next add a further ‘Column Selector’ control for the weight. This can be generated in exactly the same way as the ‘height’ column, or more simply by right clicking the ‘height’ column and clicking ’Duplicate’, and then adjusting the ID and Label properties:

Finally on this page we need to add an output table, using an ‘Output Table’ control, in exactly the same way as the input table:

Create the User Interface – Page 2, Options

Having created a page to add the input table, variables, and output table, we now need to add a page for the options. The options are:

• Do we want to convert BMI to an integer value?
• And if so, do we use the INT, CEIL or FLOOR function

Click ‘Add Page’ on the Designer tab to add the second page and page its ID and Label as below:

Add a ‘Check Box’ control to the Options page, to indicate if we wish to convert BMI to an integer. Set the properties as below:

Next add a ‘Radio Button Group’ control to select the INT, CEIL or FLOOR function to be used:

• The ID has been changed to ‘int_type’
• The label changed to ‘Select function to convert to Integer’
• Values INT, CEIL and FLOOR have been added to create the radio buttons. These are added by selecting ‘Add Many’ and then typing the values into the box:

• The default radio button is set to INT
• A Dependency has been set. The integer function only needs to be selected if the ‘To Integer?’ check box is ticked. This is achieved by adding “&to_int” to the ‘Visibility’ box, to reference the ID of the ‘To Integer?’ control and indicate the dependency.

The Designer interface is now complete. At this point it is advisable to save the Custom Step and Preview the user interface.

Select the ‘Preview’ button, and observe the two pages of the user interface:

On the Options tab you can see that selecting ‘To Integer?’ defines whether the ‘Select function to convert to Integer’ radio button is displayed.

Look at the ‘Prompt UI’ tab. The JSON code, that defines the user interface has been built for us:

Add the SAS code

Having bult the user interface and confirmed that it works as required, the final step is to add the SAS code. In practice, it is easier to develop the SAS code as a program in SAS Studio first, and then add macro variables and paste into the Program tab. For this Custom Step, the macro below contains a data step which calculates BMI and sets as an integer using the selected function if required.

1. Use SAS options to make the log clearer. Delete the mprint option once developed.
2. Use %put statements to examine the values of your macro variables. This makes debugging easier. The macro variables correspond to the IDs set in the Designer Properties pane.
3. &inputtable1 and &outputtable reference the input and output tables set as the ID values in the Designer.
4. Calculate BMI, (weight/height²) – in this case multiplied by 1000 for convenience. Note the names of the macro variables used for weight and height. The ‘Column Selector’ control, used to create these can have multiple values, hence the ‘1’. Plus, it has many attributes and we have specifically referenced its name.
5. Macro code to generate the convert to integer line of code in the data step, only if the ‘To Integer?’ selection box Is ticked, setting the &to_int macro variable to 1.
6. Convert BMI to an integer using either the INT, CEIL or FLOOR function as selected by the ‘Select function to convert to Integer’ radio button. The selection sets the value of macro variable &int_type.
7. Convert BMI to an integer using a SAS function. The function as selected by the ‘Select function to convert to Integer’ radio button, setting the macro variable &int_type to INT, CEIL or FLOOR.

Create a Flow using the Custom Step

We are now ready to use our Custom Step. To do this we create a SAS Studio flow, that contains the Custom Step:

This is a simple flow, with sashelp.class as the input data, and a work data set as the output. Highlighting the Custom Step allows us to set its parameters:

Note, the input and output data sets are not defined here. This is accomplished by the input and output nodes in the flow.

Now we can run the flow. Examining the log reveals the SAS code that has been generated and run:

We can preview the output data set to see the result:

BMI has been successfully calculated and rounded to an integer value.

Using a Custom Step in Stand-Alone Mode

It is possible to use the Custom Step without the need for a Flow. To do this, right click on the Custom Step and ‘Open in a tab’:

This allows the parameters to be set (including the selection of the input and output tables), the Custom Step to be run and the results to be viewed:

To view the log, it can be downloaded.

Saving the Custom Step

Once the Custom Step has been tested and approved to use within your organisation, the final step is to save it in an appropriate folder. Save to a folder which has shared access to users, making the Custom Step available across the organisation. If required, folders can be set up allowing only particular groups access, these folders should be read only. That way, there is control over who can use the Custom Step and see the code behind it. So, hiding potentially sensitive information.

Further Resources

The documentation on the SAS Web site for SAS Studio contains a section ‘Working with Custom Steps’ which contains lots of useful information.

The Github repository ‘ sas-studio-custom-steps’ (https://github.com/sassoftware/sas-studio-custom-steps) contains pre-written Custom Steps. Currently the repository contains approximately 40 Custom Steps. This is a SAS repository, and the content is verified by SAS. A great place to access Custom Steps!

Conclusion

In this blog the creation of a Custom Step has been demonstrated. We have shown that for a person with basic SAS skills these are relatively easy and intuitive to create. Custom Steps provide an excellent means of making organisation specific tasks available to your user group. They can be distributed throughout the organisation, or be given limited access to a selected group of people. Custom Steps can be incorporated into Studio Flows or used as stand-alone entities in SAS Studio.

The library of ‘out of the box’ steps is ever expanding with each release of Viya and a SAS managed Github repository exists where Custom Steps can be accessed.

Want to make your SAS processes enabled with a GUI? Try out using Custom Steps in SAS Viya. Interested further in them or have a question? Connect with Katalyze Data and we are glad to help.