Chapter XI - NONMEM Users Guide and On-line Help
This chapter discusses documentation that can be found on the NONMEM distribution medium.
On the NONMEM distribution medium is a
directory NONMEM_6_1.0/guides
(Unix: nonmem~1.0/guides).
This directory contains the following files, which collectively are called the NONMEM Users Guide.
The CDSETUP6.BAT utility creates a directory named guides and copies the files to it. Typically, this is c:\nmvi\guides.
With NONMEM VI 1.0 and 1.1, the Unix SETUP utility does not do this. You will need to create the directory and read the files yourself. For example, on Solaris 2 UNIX and Fedora Red Hat Linux, the commands might be as follows.
|
UNIX: |
mkdir /export/home/nmvi/guides cd /export/home/nmvi/guides cp /cdrom/cdrom0/nonmem~1.0/guides/* .
|
Linux: |
mkdir /home/nmvi/guides cd /home/nmvi/guides cp /media/NONMEM_6.1.0/Guides/* .
The pdf files may be viewed using Adobe(R) Reader. All but Part II are searchable. Although the files are copyrighted, licensed NONMEM users may print any of the files.
Chapter 2 describes the following files and directories in directory NONMEM_6.1.0 of the distribution medium:
These files contain the same material that is distributed in printed form as NONMEM Users Guide - Part VIII, Help Guide. In addition, they contain files that enable the material to be searched and displayed conveniently when installed on a computer. When installed as suggested, they implement the On-line Help feature of NONMEM. Their installation and use is optional.
The contents of help and unix/help.tar is essentially identical, as are the contents of html and unix/html.tar. They are formatted differently, reflecting the difference in line endings between Unix and MS-DOS.
The HTML versions work with all web browsers such as Internet Explorer, Netscape, Firefox, etc., and can be used with all operating systems.
Help files are intended for command-line usage, and may be useful when working from a UNIX or MS-DOS command prompt, or if there is no web browser available.
Dos_tools allow convenient command-line help under MS-DOS. DOS tools do not work with Microsoft Windows XP, although they do work with earlier versions of Windows and with Vista.
Users with other operating systems can use the command-line Help material, but they may have to create their own user-interface for search and display; the UNIX and MS-DOS examples may serve as convenient starting points.
The printed Help Guide consists of two sections: an index, which is printed in two parts (RESERVED WORDS and MISCELLANEOUS TOPICS); and over 200 individual discussions, which are also printed in two parts (DETAILED DESCRIPTIONS and EXAMPLES). In the Help directory, a file named index contains both parts of the printed index, in a format designed for use by the UNIX and DOS tools included on the distribution medium. Also on the Help Guide directory are over 200 files with names of the form xxxx.xxx, each of which contains the text of a single individual discussion. These files are referred to collectively as "detailed description files" in the examples below. (The suffix identifies the content. For example, examples have names ending with the suffix exa.)
The files in the html directory (or unix/html.tar) should be read to a directory, say, c:\nmvi\html or /export/home/nmvi/html. The CDSETUP6.BAT utility creates a directory named html and copies the files to it. The Unix SETUP utility does not do this. You will need to create the directory and read the files yourself. Examples are given for Solaris 2 UNIX and Fedora Red Hat Linux Modifications may be necessary for other versions of UNIX.
|
UNIX: |
mkdir /export/home/nmvi/html cd /export/home/nmvi/html tar xvf /cdrom/cdrom0/nonmem~1.0/unix/html.tar
|
Linux: |
mkdir /home/nmvi/html cd /home/nmvi/html tar xvf /media/NONMEM_6.1.0/unix/html.tar
(See readme~1.txt for other suggestions.)
Once the files have been read, start a web browser such
as Internet Explorer, Netscape, or Firefox. On the File
menu, you should find a button called Open or Open File.
Type (or browse for) the directory into which the files were
read, e.g., c:\nmvi\html or /export/home/nmvi/html. Type the
file name index.htm (not $index.htm). This should open a
page with the title
This is the main index of Hyper-NMhelp.
You may find it convenient to bookmark the page.
The use of Hyper-NMhelp is straightforward. Note that the keywords may be grouped somewhat differently than they are with the command-line on-line help described in the following sections.
The files in the help directory (or unix/help.tar) should be read to a directory, say, c:\nmvi\help or /export/home/nmvi/help. The CDSETUP6.BAT utility creates a directory named help and copies the files to it. The Unix SETUP utility does not do this. You will need to create the directory and read the files yourself. Examples are given for Solaris 2 UNIX and Fedora Red Hat Linux Modifications may be necessary for other versions of UNIX.
|
UNIX: |
mkdir /export/home/nmvi/help cd /export/home/nmvi/help tar xvf /cdrom/cdrom0/nonmem~1.0/unix/help.tar
|
Linux: |
mkdir /home/nmvi/help cd /home/nmvi/help tar xvf /media/NONMEM_6.1.0/unix/help.tar
If you now return to the nonmem directory (say, /export/home/nmvi) and retype the SETUP command as before, it will create the shell script help/nmhelp.
Instead, you may do this yourself. One of the files read from the Help directory is named nmhelp. If you have read the files into a directory with a different name than suggested, edit the file nmhelp. Locate this line:
set lf = /export/home/nmv/help
Change the characters "/export/home/nmv/help" to the path of the current directory. Please review the comments in file nmhelp, which suggest other possible changes.
Copy the file nmhelp (which is an executable C-shell script) to a directory in the NONMEM user’s path. Make sure it is executable:
chmod 755 nmhelp
The nmhelp command may now be executed from any directory. (You may first need to enter the unix command "rehash".)
To get information on the command nmhelp itself, enter "nmhelp help"
To get a list of the topics available, enter "nmhelp".
To get information on a given reserved word or topic, enter "nmhelp" followed by the reserved word or topic. For example,
|
UNIX: |
% nmhelp nonlinear Help for nonlinear is available in the following documents: 1 ADVAN10 4 NONMEM model 2 ADVAN6 ADVAN8 5 NONMEM program 3 ADVAN9 6 Michaelis Menten example - Your choices: enter "p number" to print a document (e.g., p1 or p 1) enter the number of the document you wish to see enter <CR> to see document number 1 enter q <CR> to quit this list
A number 1 through 6 may be entered, and the appropriate document will be displayed at the terminal. You may then enter a different number to display a different document.
CDSETUP6.BAT utility installs the Help files for you. It also installs DOS tools. If you have used CDSETUP6.BAT, you can now skip to section 2.3.3, "Using nmhelp in MS-DOS".
If it is necessary to install help yourself, you can create a directory for the help files, and read the files. The following is a suggestion.
|
MS-DOS: |
mkdir c:\nmvi\help cd c:\nmvi\help copy d:\nonmem_6.1.0\help\*.*
Here is a very rudimentary way to search and display the contents of the Help Guide, using ordinary DOS commands. A better way involves the use of the tools in the DOS tools directory, described in the next section. DOS tools do not work with Microsoft Windows XP, although they do work with earlier versions of Windows and with Vista.
Change to the directory into which you read the Help files.
To get information on a given reserved word or topic, enter "find" followed by the reserved word or topic in quotes (""). For example,
|
MS-DOS: |
find "nonlinear" index ---------- INDEX advan10.ppp~ ADVAN10~ nonlinear kinetics model advan68.ppp~ ADVAN6 ADVAN8~ general nonlinear kinetics model advan68.ppp~ ADVAN6 ADVAN8~ nonlinear kinetics model advan9.ppp~ ADVAN9~ general nonlinear kinetics model advan9.ppp~ ADVAN9~ nonlinear kinetics model nonmod.gen~ NONMEM model~ nonmem nonlinear mixed effects model nonpro.gen~ NONMEM program~ nonmem nonlinear mixed effects model michaeli.exa~ Michaelis Menten example~ nonlinear kinetics model
The first column lists detailed description files. The second column gives their titles. The third column gives the context in which the search word "nonlinear" appears as a keyword in these files. (The column delimiter is the character ~).
To display a document in the list, enter "more" followed by the filename. For example,
more < advan10.ppp
Read the file install.exe on the Tools Directory into the directory in which the Help files was read, e.g., c:\nmvi\help, and enter the command "install".
|
MS-DOS: |
copy d:\nonmem_6.1.0\Dos_tools\install.exe install
The following files will be created:
nmhelp.exe
|
A compiled C-program that searches for and displays detailed description documents. Must be used on a 386-based DOS system or higher. Uses utility programs from the Free Software Foundation. (An alternative approach is to use hh.bat and dd.bat; see below.) |
nmhelp.c
|
The source code for nmhelp, in case it is necessary to re-compile it on your system. A C or C++ compiler will be required; we do not provide it. |
gawk.exe, grep.exe
|
Compiled utility programs from the Free Software Foundation. Must be used on a 386-based DOS system or higher. These binaries fail when used in Windows XP. |
hh.bat, dd.bat, hh.awk
|
DOS batch files that search for and display detailed description documents, and a file (hh.awk) used internally by hh.bat. Uses utility programs gawk.exe and grep.exe. (An alternative approach is to use nmhelp.exe; see above.) |
Other files in the Dos_tools directory are gnulic.txt (a license agreement from the Free Software Foundation which should be read by anyone who wishes to make the utilities available to others), and gawk300.tgz and grep20.tgz, the source code for gawk and grep, respectively. Ordinarily, you should not need the source code. The source files can be copied from Dos_tools and then unpacked and untared with gunzip and tar. E.g.,
type gawk300.tgz | gunzip -c | tar xvf -
(Gunzip and tar can be obtained by anonymous ftp from prep.ai.mit.edu. They are in the pub/gnu directory).
Change to the directory into which you read the help files. Or, to use nmhelp from any directory, do the following one time only:
|
Edit your autoexec.bat file to include the following line: set NMHELP=c:\nmvi\help (Supply the path and name of your nmhelp directory, if different) Change the PATH variable to include c:\nmvi\help (or the path and name of your nmhelp directory, if different). Restart your system. |
To get information on the command nmhelp itself, enter "nmhelp help"
To get a list of the topics available, enter "nmhelp".
To get information on a given reserved word or topic, enter "nmhelp" followed by the reserved word or topic. For example,
|
MS-DOS: |
nmhelp nonlinear Help for nonlinear is available in the following 6 document(s): 1 ADVAN10 4 Michaelis_Menten example 2 ADVAN6 ADVAN8 5 NONMEM model 3 ADVAN9 6 NONMEM program Your choices: enter p number to print a document (e.g., p1 or p 1): enter the number of the document you wish to see enter 0 or q to quit, return for next choice (1)
A number 1 through 6 may be entered, and the appropriate document will be displayed at the terminal. You may then enter a different number to display a different document.
On some systems, the compiled nmhelp.exe may fail. If gawk.exe and grep.exe work correctly, then the hh and dd commands can be used instead of nmhelp.
Change to the directory into which you read the help files.
To get information on a given reserved word or topic, enter "hh" followed by the reserved word or topic. For example,
|
MS-DOS: |
hh nonlinear
Help for nonlinear is available in the following documents:
1 ADVAN10 4 Michaelis_Menten example
2 ADVAN6 ADVAN8 5 NONMEM model
3 ADVAN9 6 NONMEM program
Enter "dd n" to display the nth. document, e.g., dd 1
to display the first document.
To display a document in the list, enter "dd" followed by the number. For example,
dd 1
This will display the document ADVAN10. At the DOS prompt, you may then enter "dd" with a different number to display a different document.