HLM/2L and HLM/3L: Basic use

HLM/2L and HLM/3L, statistical software for two-level and three-level hierarchical linear models, are available on the Solaris UNIX systems Strauss and Mahler. This document describes how to run these programs in non-interactive and interactive mode. The document should be viewed as a companion to the HLM/2L and HLM/3L User Reference Guide.

The instructions for HLM/2L and HLM/3L are identical except for the substitution of 'hlm3l' for 'hlm2l' and 'prssm3' for 'prssm2' in the descriptions below. The rest of these instructions will refer only to HSM/2L.


Data analysis using the HLM/2L program typically has three stages:

Command summary for HSM/2L

This section starts with general instructions on preparing the files and running the program. It ends with a complete example.

How to create the .ssm file--

To create the .ssm file interactively, type


To create the .ssm file non-interactively, make a UNIX file which contains the responses to the program's prompts for information. Then, if the file is named makessm.rsp, type

	hlm2l < makessm.rsp

Whether you run interactively or non-interactively, the program creates a file named createss.rsp in your current working directory. The file is a log of all the information accepted by the program as responses to its internal prompts. This log file can be renamed and used as a subsequent input file for this step. If you run non-interactively, createss.rsp will be identical to your command file makessm.rsp.

If you respond 'y' to the interactive prompt 'Do you wish to save these descriptive statistics in a file?' or if your command file contains a 'y' on the line corresponding to that prompt's response, the statistics are saved in a file named hlm2ss.sts in your current working directory. If the file already exists, its contents are replaced.

How to translate the .ssm file into an ASCII file--

This step is generally not needed. However, if you want to read the contents of the .ssm file in an editor or another program, you must first translate it into an ASCII file. For example, to translate a file named hsb.ssm into an ASCII file named hsb.suffstat, type

	prssm2 hsb.ssm hsb.suffstat

How to execute the analysis phase--

To proceed interactively using a .ssm file named hsb.ssm, type

	hlm2l hsb.ssm

The program will use the default settings for analysis commands. These defaults are stored in /opt/lib/hlm/comfile2.hlm.

To proceed non-interactively using a .ssm file named hsb.ssm and a command file named hsb.hlm, type

	hlm2l hsb.ssm hsb.hlm

Since a command file is specified here, the defaults file (/opt/lib/hlm/comfile2.hlm) is ignored. All information needed by the program can be placed in your command file. If you fail to specify all the required information in your command file, the program may prompt you for the additional information. One of the required commands you should include is the name of the output file. An example of this is provided below. Note that the filenames may not use the '~' symbol.

How to run these commands in the background--

If you have complete command files (e.g., makessm.rsp or hsb.hlm), the programs will not need to prompt you interactively for additional information. In those cases, you may run those programs in the background. This is essential if you want to log out and let the processing continue. To do this, redirect the output that normally goes to the screen so it is sent instead to a UNIX file. For example, to process the analysis phase command given above, and have the screen output sent to a file named hsb.lst, type

	hlm2l hsb.ssm hsb.hlm  >  hsb.lst &

Command files--important note on layout

Lines of the command files may be longer than 80 characters. Statements starting with the keywords 'level1:', 'level2:' and 'level3:' have one unusual requirement. Variable names appearing after a '+' sign should not have spaces between the sign and the name. For example, the statement

	level2: intrcpt1=intrcpt2+sector+meanses+random

may be written as

	level2: intrcpt1=intrcpt2 +sector +meanses +random

However, it should not be written as

	level2: intrcpt1=intrcpt2  +  sector  +  meanses  +  random 

Furthermore, be sure not to type any spaces after UNIX filenames when the names appear in command files. All trailing spaces must be deleted or the space-characters will become part of the filename!

Annotated example for non-interactive session

There are sample data files and command files corresponding to the High School and Beyond survey in the /opt/lib/hlm directory. (Examples for HLM/3L from the U.S. Sustaining Effects study are also stored in that directory.) The following section illustrates how to use the HS&B files with HLM/2L. The discussion closely parallels the User Reference Guide (URG), pages 13-45.

Creating the .ssm file--

The ASCII file named /opt/lib/hlm/studeg.dat contains the raw data for the level-1 (student-level) variables. The ASCII data file /opt/lib/hlm/scheg.dat contains the level-2 (school-level) variables. The first task is to create the sufficient statistics matrices and store them in the .ssm file named hsb.ssm. Consult pages 13-18 of the URG for the specifications of these data files. The command file that instructs HLM/2L to create hsb.ssm consists of the following lines. The italicized comments on the right side of each line indicate which of the program's prompts corresponds to that line. The comments themselves are not (and may not be) part of the file.

y			Will you be starting with raw data?
n			Is the input file a v-known file?
n			Are the input files SYSTAT .SYS files?
4			Number of level-1 vars (not including ID)?
(a4,8x,4f12.3)		Fortran format for level-1 file?
/opt/lib/hlm/studeg.dat	Name of level-1 file?
n			Is there missing data in the level-1 file?
6			Number of level-2 vars (not including the ID)?
(a4,2x,6f12.3)		Fortran format for level-2 file?
/opt/lib/hlm/scheg.dat	Name of level-2 file?
minority		8-character name for level-1 variable #1
female			8-character name for level-1 variable #2
ses 			8-character name for level-1 variable #3 
mathach 		8-character name for level-1 variable #4
size			8-character name for level-2 variable #1
sector			8-character name for level-2 variable #2
pracad			8-character name for level-2 variable #3
disclim			8-character name for level-2 variable #4
himinty			8-character name for level-2 variable #5
meanses			8-character name for level-2 variable #6
n			Is there a level-1 weighting variable?
n			Is there a level-2 weighting variable
hsb.ssm			Name of sufficient stats matrices output file?
y			Want to save descriptive stats in a file named

If this file is named makessm.rsp, then typing

	hlm2l < makessm.rsp

creates the .ssm file and the descriptive statistics file (for browsing).

Specifying and estimating the model's parameters--

This section estimates a two-level linear model described on pages 20-29 of the URG. The level-1 (student-level) model predicts mathach (mathematical achievement) by ses (socioeconomic status). The level-2 (school-level) model predicts each school's intercept and ses slope as a function of sector (Catholic vs. public) and meanses (school's mean social class). Other potential predictors for the level-2 model are the variables size, pracad and disclim.

The example command file further specifies that the output file is named model1.lst, and that a residuals file should be created. The residuals file is always named residfil.cmd. If the file already exists, its contents are replaced. The keywords used in the command file are described on pages 29 and 40-45 of the URG.

The contents of the command file are


If the command file is named model1.hlm, then typing

	hlm2l hsb.ssm model1.hlm

produces the analysis results.

For additional information

The programs and their command syntax are fully described in the manual HLM™/2L and HLM™/3L User's Reference Guide, A.S. Bryk, S.W. Raudenbush, and R.T. Congdeon, Jr., SSI Scientific Software International, 1992.

The manual should be used in conjunction with the text Hierarchical Linear Models: Applications and Data Analysis Methods, A.S. Bryk and S.W. Raudenbush, Sage Publications, 1992.

All sample programs and sample data are stored in the directory /opt/lib/hlm.

University of Delaware

April 4, 1998