The purpose of this document is to explain to you what the "key components"
of Spectre are. Once you know what these key components are, then you know
how the system hangs together and what you are free to change and what
not to change. The "key components" are what you must not change. This
will not be complicated. In a broad sense, you must not change any of
the macros but you are free to change some of the production scripts
or not use them at all, as will be explained.
The autocall library
The autocall library, which is the collection of sas macros held here,
is the foundation of Spectre. You must not change these macros
under any circumstances. You can add to the collection if you like, but
the macros you add should come from the larger collection of macros that
are webbed on my old web site here.
It is I who maintain these macros. They are like a family of macros
that work together, which is why they must not be changed by anybody except
me, as it is only me who knows how they hang together. They are the infrastructure
of any sas batch application that I write. If new macros are written for
study reporting purposes, then they should go in a separate library or
be held at the study level or drug level. If a new utility macro is conceived
of that you think should go in this autocall library, then first check
the larger library for a macro that already does what you want or contact
me about it and tell me about your proposed new utility macro. I will be
able to tell you a way of achieving the same thing using the existing macros
or through a different method or, if not, and the macro seems like a good
thing to add to the library as a general purpose macro, then I will write
it for you for free and add it to the collection so that you can use it
and so can anybody else.
The reporting macros %unistats and %npcttab
The two reporting macros %unistats and %npcttab are given
a lot of space on this web site in terms of describing how to use them.
A lot of people could be forgiven for thinking Spectre was %unistats
and %npcttab. However, the surprise is that these two macros are not
part of Spectre. They are part of a family of reporting macros that
includes %popfmt, %unistats and %npcttab plus their supporting macros
%unimap,
%unicatrep,
%unipvals
and %npctpvals. They rely on a number of autocall macros and are
themselves members of that library. The reason they appear to be part of
Spectre is because the documentation on how to use them is on this web
site because it is the most appropriate place to put it for the time being.
Strictly speaking, they should have their own web site as they are independent
of Spectre and the %unistats macro gets used for non-clinical reporting
purposes in any case. If you check the demonstrations that are on this
web site, then once you know what macros
are a part of Spectre,
you will see that all the demonstrations were done not calling any of the
Spectre macros. Having explained that these macros are not part of Spectre
then it does not mean you can amend them. Actually, you can amend %unimap
if you need to. That is the macro that maps a statistics label to a "proc
univariate" keyword. You may need a mapping that is not there in which
case you have to add it yourself. If you do amend it, make it clear from
the "macro called" message that it puts out that this is a user-modified
version. Start again at version 1.0 if you modify it in-house and use a
"%put" message like this:
%put MACRO CALLED: unimap v1.0 (user modified);
You must not amend any of the other macros.
The derived datasets build
The scripts that help you to run the programs to create the derived datasets
are not a part of Spectre. It is up to you to build the derived datasets
and you should do it in the way that best suits your needs. Spectre makes
no demands on the derived dataset content or structure. You can change
the scripts. You can ignore the scripts entirely if you wish. You might
even get these datasets prepared by a CRO and the form it takes does not
matter so long as they get built correctly according to your own needs.
So what is Spectre?
I have told you a few things about what Spectre is not. It would
be helpful at this point for me to define what Spectre is. Before
I define what Spectre is, I will tell you that I am going to discount
all the scripts that I supply with Spectre. There are some scripts for
handling PDFs that are complicated but most of the scripts in Spectre that
do stuff like run suites of programs are trivial. Scripts are simplicity
itself once you get used to them. The clever stuff is not in the scripts.
The real processing in Spectre and all the clever stuff is in the sas macros.
It's "definition time" for Spectre so here goes.........
Spectre is an extended titles and footnotes system, "extended" in
the sense that it incorporates protocol information which allows it to
satisfy multiple client layout requirements, is structured in a way that
it can act as a "push button" reporting system and has the capacity to
add "Page x of Y" labels to the final output in varying styles.
At its most essential level, the above statement completely defines
Spectre. Hopefully, things should start to make sense from now on, once
you know this.
As I previously stated in this section - it is the sas macros that
define Spectre. The defining macros for Spectre do not exist on my
old web site here
but they exist in the Spectre macro library here.
A simple bit of detective work can reveal what makes Spectre function.
I have a script called "compdirs" that compares directories which can tell
me which member are in one library but not in another. I have used this
command below to list macros in the spectre macros directory that are not
in the "Roland's SAS Macros" directory, as you can see in the box that
follows. The macros listed are the macros that
make Spectre. The
first two macros %allocr and %allocw are obviously doing
allocations,
autoexec.sas (actually not a macro) is the start-up
member that makes sure the correct macro libraries get assigned in the
correct order and the rest are all to do with the protocol, titles, footnotes
and the layout requirements plus %openrep and %closerep that
reroute output to a temporary file to allow "Page x of Y" page labels to
be added. They are short simple macros apart from %xytitles, the example
client titles macro. Hopefully, Spectre looks less complicated now.
At last we come to Spectre proper! The "titles" macros and scripts
are most definitely a part of Spectre and form the bulk of its key components.
This "titles" handling also includes footnotes and protocol information
plus layout and population and a few other things. They combine to create
the titles and protocol dataset and when a program runs the
information in the protocol dataset will get read in as well as the corresponding
entries in the titles dataset for that program.
The structure and contents of the titles and protocol datasets
are key to Spectre functioning and can not be changed. So long as these
datasets get built correctly, you could do it by any means you like. Instead
of using a protocol.txt member and .titles members, you could
have this information stored in a spreadsheet and somehow extract it and
build these datasets, but the key thing is that these two datasets get
built correctly.
Remembering that so long as the titles and protocol datasets are built
correctly then it can be done any way you like, then the following scripts
and macros are supplied with Spectre to help you build these datasets and
their functions will be listed. Macro names will be prefixed by a "%" and
script names not. These scripts might call other scripts and macros and
the macros might call other macros but this will not be expanded upon here.
crprttmpl - this script creates the protocol template which must be copied
across and protocol.txt and the protocol information filled in as
detailed in the header.
crtitlestmpl - this script creates the titles template that will be copied
across as a ".titles" member and each programmer will fill this
in with titles, footnotes and other information as detailed in the header.
crtitlesds - this script reads the protocol information in protocol.txt
and all the information in the ".titles" members and builds the
protocol and titles datasets.
Once the protocol and titles datasets are built correctly
then the information in these datasets is ready to be read in by a reporting
program. It is read in using a call to the %titles macro which in
turn calls other macros which includes those listed below.
%protinfo - reads protocol information from the protocol dataset
%proginfo - reads in program information from the titles dataset
the client titles macro - reads information from the titles dataset and
sets up titles and footnotes in accordance with the client's preferences
%openrep and %closerep
The two macros %openrep and %closerep are definitely part
of Spectre. They "open" a report ready for a "proc report" step or a call
to a reporting macro or whatever is creating the report output and "close"
the report afterwards. What %openrep is essentially doing is calling "proc
printto" to redirect print output to a temporary file and %closerep is
reading in that temporary file, calling a macro to add "page x of Y" labels
and copying the file to the non-temporary ".lis" file. For "production
runs", both %openrep and %closerep read information from two system environment
variables named OUTDIR and DONELIST so they know what directory to put
the outputs in and what the name of the "donelist" file is to write entries
to to record what reports have been produced.
makerun and makexrun
How you choose to run the programs that create the derived datasets and
how you run the programs that create output, and what programs you run,
is entirely up to you. It doesn't matter, so long as it gets done correctly.
The script makerun "makes" separate scripts to run the derived dataset
build and to run the reports while makexrun "makes" a script to
run "extra" reports, assuming these are programs that start with an "x"
and have entries in the titles dataset. They are clever scripts but do
not assume you have to use them or conform to the structure they are expecting.
They are just there to give you an idea of the way it can be done. You
are free to make copies of them and change them as you see fit. If you
want to direct the output to a folder and you want %closerep to write entries
to some sort of "donelist" file then you will have to set up the two system
environment variables OUTDIR and DONELIST and give them appropriate values,
otherwise, do not bother.
bigps and bigxps
The two scripts bigps and bigxps read in the donelist file
to find what reports have been created and gathers their outputs together
to form a big PostScript file. They are clever scripts, just as makerun
and makexrun are, but again you don't have to use them. All that matters
is that you have a list of outputs. This list doesn't have to be in a file
-- it could be a list gotten from a Unix command. There are others ways
of making a large PostScript file from a list of outputs and utilities
on this web site to help you. It is quite well explained in the "Ad-hoc
reporting and PDFs" document you can link to from the main page.
The "key" key components of Spectre
The "key" key components of Spectre -- the absolutely essential ones whose
use can not be avoided are:
the protocol dataset, created any way you like, so long as it is
correct
the titles dataset, created any way you like, so long as it is correct
%titles and all its submacros
%openrep and %closerep
Conclusion
The key components of the Spectre (Clinical) reporting system have been
explained in this document. You will have seen that these key components
are very few in number and so long as these components are not altered,
this leaves huge scope for tailoring Spectre to fit your requirements.
Use the "Back" button of your browser
to return to the previous page.