"Fossies" - the Fresh Open Source Software Archive

Member "statist-1.4.2/doc/programm.tex" (31 May 2003, 12496 Bytes) of package /linux/privat/old/statist-1.4.2.tar.gz:

    1 \documentstyle[german,11pt,mydefs]{article}
    2 %\documentstyle[german,11pt,mydefs]{script_s}
    3 
    4 \voffset 1cm
    5 \newcommand{\st}{\tt sta"-tist \rm}
    6 % \addtolength{\textwidth}{-2.5cm}
    7 % \raggedright
    8 
    9 \begin{document}
   10 
   11 \begin{center}
   12 {\Large\bf Dokumentation f"ur Programmierer zum Statistikprogramm \st \\ }
   13 \el
   14 {\small Dirk Melcher, Institut f"ur Umweltsystemforschung , Uni
   15   Osnabr"uck\\ Artilleriestr.\ 34, 49069 Osnabr"uck\\
   16   email:  dmelcher@ramses.usf.uni-osnabrueck.de}
   17 \el
   18 \el
   19   Version vom 25.5.95\\
   20         {\bf Achtung! Diese Dokumentation enth"alt 
   21     veraltete Informationen!}
   22 \end{center}
   23 
   24 \section{Einleitung}
   25 
   26 Das Programm \st\ besteht aus den Modulen {\tt statist.c, menue.c, da"-ta.c,
   27   funcs.c, procs.c} und {\tt plot.c}. Zu jeder C-Datei geh"ort
   28 au"serdem eine entsprechende Headerdatei.
   29 
   30 Wie in der Einleitung bereits verk"undet, hat das Programm den Anspruch,
   31 einigerma"sen leicht erweiterbar zu sein. Hierzu sei zun"achst die
   32 Philosophie des Programmes geschildert:
   33 
   34 Im Programm wird streng zwischen den eigentlichen Rechenprozeduren und
   35 den Routinen, welche Datenmanagement, Men"uf"uhrung und Dialog
   36 durchf"uhren, unterschieden. Deswegen sollten {\em alle\/} Variablen
   37 in den Rechenprozeduren lokal sein! Das Programm mu"s die
   38 Rechenroutienen also mit den fertig zusammengestellten Daten
   39 versorgen. Die Rechenprozeduren "ubernehmen die eigentliche
   40 Rechenarbeit und schreiben das Ergebnis auf den Bildschirm.
   41 
   42 \section{Kompilieren}
   43 \st\ kann sowohl f"ur {\sc Unix} als auch {\sc Dos} kompiliert werden.
   44 
   45 % Es existieren Makefiles f"ur {\tt gcc} unter {\sc Unix} und dem {\sc
   46 %  Borland} C-Compiler {\tt bcc} bzw.\ der {\tt gcc}-Portierung {\tt
   47 %  djgpp} f"ur {\sc Dos}.
   48 
   49 %Falls \st noch kompiliert werden mu"s: Unter {\sc Unix}:
   50 
   51 % {\tt \ \ \ gcc -o statist statist.c -lm  }
   52 % {\tt \ \ \ make -f makefile.unx statist   }
   53 
   54 F"ur {\sc Unix} wird der gcc-Compiler vorrausgesetzt, der K\&R cc-Compiler
   55 tut's nicht, da das Programm in Ansi-C geschrieben ist. Das Makefile
   56 f"ur {\tt gcc} hei"st {\tt makefile.unx}.
   57 
   58 Unter {\sc Dos} kann das Programm z.B. mit dem Kommandozeilen-Compiler
   59 {\tt bcc} von {\sc Borland} (Makefile {\tt makefile.bcc}) oder mit der
   60 Portierung des gcc-Compilers {\tt djgpp} (Makefile {\tt makefile.djg})
   61 kompiliert werden. ({\tt djgpp} erstellt 32-Bit-Code f"ur 386'er. Mit
   62 einer 386'er Version von \st lassen sich wesentlich gr"o"sere
   63 Datenmengen bearbeiten.)  Das Programm wird dann jeweils mit
   64 
   65 % In diesem Fall bitte das
   66 % Speichermodell `Large' w"ah"-len.  Au"serdem sollte {\tt MSDOS}
   67 % definiert sein (als Kommandozeilenparameter {\tt -DMSDOS}, s.u.).
   68 % Falls man das Gl"uck hat, vor einem 286'er aufw"arts zu sitzen, kann
   69 % man \st z.B. folgenderma"sen kompilieren:
   70 % { \tt \ \ \ bcc -2 -H -d -DMSDOS -ll statist.c }
   71 
   72 {\tt \ \ \ make -f<Makefile>}  \ \ bzw. \par
   73 % {\tt \ \ \ make -f makefile.djg }  \ \ erstellt \par
   74 
   75 Das utility {\tt make}, welche das Makefile abarbeitet, ist sowohl im
   76 {\sc Borland}-Paket als auch als gnu-utility erh"altlich.
   77 
   78 
   79 
   80 \section{Ausgabeprozeduren}
   81 Um die Ausgabe von beliebeigen Meldungen \st flexibel handhaben zu
   82 k"onnen (Mitschreiben von Protokolldateien usw.), gibt es drei
   83 verschiedene Ausgabefunktionen, die im Stil von {\tt printf} aufgerufen
   84 werden:
   85 
   86 
   87 \begin{enumerate}
   88 \item {\tt out\_d}: Ausgabe von Dialogtexten, da"s hei"st also, die
   89   Men"utexte, Eingabeaufforderungen und alles andere, was nicht mit
   90   den eigentlichen Berechnungen zu tun hat.
   91 \item {\tt out\_r}: Ausgabe aller Ergebnistexte, also alles, was mit
   92   den eigentlichen Berechnungen zu tun hat und in dem Modul {\tt
   93     procs.c} steht.
   94 \item {\tt out\_err}: Ausgabe aller Fehlermeldungen. Im Gegensatz zu
   95   den beiden anderen Routinen wird au"ser den `normalen' {\tt
   96     printf}-Argumenten zus"atzlich als erstes Argument eine
   97   Fehlerkonstante "ubergeben, die die Art des Fehlers charakterisiert:
   98   {\tt WAR} wird als Warnung ausgegeben, {\tt ERR} ist ein `normaler'
   99   Fehler, {\tt MAT} ist ein Fehler und {\tt MWA} eine Warnung
  100   innerhalb einer Rechenprozedur (werden mit ins Protokoll geschrieben)
  101   und {\tt FAT} ist ein `fataler' Fehler, der einen sofortigen Abbruch
  102   des Programmes bewirkt. Danach folgen wie "ublich der Formatstring
  103   und die restlichen Argumente.
  104 \end{enumerate}
  105 
  106 
  107 \section{Men"u}
  108 
  109 Will man eine Statistikprozedur hinzuf"ugen, so schaut man zuerst, in
  110 welches Untermen"u (Datei {\tt menue.c}) sie am besten hineinpa"st.
  111 Momentan gibt es lediglich die Men"uprozeduren {\tt data\_menu(),
  112   re"-gress"-\_menu(), test"-\_menu()} und {\tt misc"-\_menu()}. Will
  113 man z.B.\ eine Testprozedur hinzuf"ugen, so sucht man die Prozedur
  114 {\tt test\_menu()} und f"ugt mit einer fortlaufenden Nummer den Namen
  115 der neuen Prozedur zum Men"utext hinzu, also z.B. \\ \verb| out_d(" 5
  116 = U-Test von Mann und Whitney\n");| \\ Sodann geht man in die {\tt
  117   switch} Anweisung der Men"uprozedur und f"ugt die entsprechende {\tt
  118   case}-Marke f"ur die hinzugef"ugte Nummer an (in unserem Beispiel
  119 also {\tt case 5}). Hier werden dann die Dialoge gef"uhrt und die
  120 eigentliche Rechenprozedur aufgerufen.
  121 
  122 \section{Dialoge}
  123 Die Dialoge befinden sich ebenfalls in der Datei {\tt menue.c}.
  124 Wie man wahrscheinlich gesehen hat, sind die Dialoge sehr primitiv. Es
  125 gibt allerdings ein Feature des Programmes, welches die Dialoge leicht
  126 verkompliziert: die M"oglichkeit, da"s der Benutzer jederzeit durch
  127 dr"ucken der Returntaste einen Dialog abbricht und wieder ins Men"u
  128 zur"uckkehrt.
  129 
  130 Oft beschr"ankt sich der Dialog darauf, den Benutzer zu fragen, welche
  131 Spalten er welchen Variablen zuordnen m"ochte. Dabei kann man zwei
  132 F"alle unterscheiden:
  133 
  134 \begin{enumerate}
  135 \item Die Anzahl der Variablen (und damit der Spalten) ist festgelegt,
  136   z.B.\ 2 Spalten bei dem einfachen t-Test.
  137 \item Die Anzahl der Spalten ist variabel, wie dies z.B.\ bei der
  138   Erstellung der Korrelationsmatrix der Fall ist.
  139 \end{enumerate}
  140 
  141 Meistens tritt Fall 1 ein. Will man also f"ur den U-Test zwei Spalten
  142 einlesen, dann wird einfach die Prozedur {\tt getcols(2)}
  143 aufgerufen.
  144 
  145 Bei jedem Einlesevorgang wird die globale bool'sche Variable {\tt empty}
  146 neu gesetzt. Wird bei einer Eingabe nur die Entertaste gedr"uckt, dem
  147 Programm also eine Leerzeile "ubergeben, dann wird {\tt empty} auf
  148 {\em true\/} gesetzt, sonst auf {\em false\/}. Deswegen sollte immer,
  149 wenn direkt oder "uber eine Prozdeur (wie bei {\tt getcols}) eine
  150 Eingabeaufforderung stattgefunden hat, "uberpr"uft werden, ob die Eingabe
  151 `leer' war oder nicht, um dem Benutzer die M"oglichkeit zu geben, den
  152 Dialog jederzeit abzubrechen. Daher w"urde in unserem Beispiel der Aufruf
  153 einer Prozedur {\tt u\_test} folgenderma"sen aussehen:
  154 
  155 \begin{verbatim}
  156    case 5: {
  157        getcols(2);
  158        if (!empty) {
  159           u_test(xx[acol[0]],nn[acol[0]], xx[acol[1]],nn[acol[1]]);
  160        }
  161    }
  162    break;
  163 \end{verbatim}
  164 
  165 Die Namen der Variablen, die {\tt u\_test} "ubergeben werden m"ussen,
  166 werden im folgenden Abschnitt besprochen.
  167 
  168 Bei vielen Statistikprozeduren ist es notwendig, da"s die Spalten alle gleich
  169 viele Werte haben m"ussen. Dies kann mit der Funktion {\tt equal\_rows}
  170 getested werden. In diesem Fall kann man also die Zeile \\
  171 \verb|    if (!empty) { | \\
  172 aus dem letzten Beispiel durch die Bedingung \\
  173 \verb|    if ((!empty) && (equal_rows(2))) { |  \\
  174 ersetzen (wenn z.B.\ 2 Spalten auf gleiche Anzahl "uberpr"uft werden
  175 sollen).
  176 
  177 Falls die Anzahl der Spalten, die von einer Rechenprozedur ben"otigt
  178 werden, variabel ist, gestaltet sich der Dialog komplizierter. In diesem
  179 Falle kann man z.B.\ den Dialog f"ur den Aufruf der Funktion
  180 {\tt correl\_matrix()} im Regre"s-Men"u "ubernehmen.
  181 
  182 Mu"s man irgendwelche Parameter direkt vom Benutzer erfragen, so sollte
  183 man dies in einer bestimmten Form tun: Es gibt eine globale
  184 String-Variable {\tt line}, in der prinzipiell alle Benutzereingaben
  185 abgespeichert werden. Dies sollte immer mit Hilfe einiger Makros
  186 erfolgen, die am Anfang des Programmes definiert sind. In der Regel
  187 wird eine Abfrage innerhalb eines {\tt switch}-Statements erfolgen.
  188 Dann verwende man das Makro {\tt GETBLINE}. Dieses Makro lie"st die
  189 Benutzereingabe in {\tt line} ein und bricht den Dialog ab, falls die
  190 Eingabe leer war. Will man eine Zahl vom Benutzer eingeben lassen, so
  191 verwende man nach Aufruf des Makros {\tt GETBLINE} die Funktion {\tt
  192 getint()} bzw.\ {\tt getreal()} (letztere f"ur {\tt double} Zahlen). Diese
  193 Funktionen "uberpr"ufen, ob eine g"ultige Zahl eingegeben wurde. Sollen
  194 einzelne Zeichen eingelesen werden (z.B.\ `j' oder `n' bei ja/nein
  195 Verzeigungen), so tue man dies nach Aufruf des Makros {\tt GETBLINE} mit
  196 {\tt sscanf(line, \dq \%c\dq, \&antwort)} oder sowas.
  197 
  198 Die eigentliche Rechenprozedur sollte in die Datei {\tt procs.c}
  199 eingef"ugt werden. Der Funktionsprototyp sollte als {\tt extern}
  200 deklariert in die Headerdatei {\tt procs.h} geschrieben werden. {\tt
  201   funcs.h} gibt einen "Uberblick "uber bereits vorhandenen Funktionen,
  202 die mit benutzt werden k"onnen.
  203 
  204 \section{Variablen und Parameter}
  205 Alle globalen Variablen befinden sich als {\tt extern} deklariet in
  206 {\tt statist.h}. Au"serdem befinden sich hier auch die
  207 Typ-Definitionen.
  208 
  209 Die Spalten werden in den Array-Variablen {\tt xx} gespeichert. Die
  210 Gr"o"se jeder Spalte wird in dem Array {\tt nn} gespeichert. Die
  211 Spalte {\tt xx[0]} enth"alt also {\tt nn[0]} Werte. Durch den Aufruf
  212 von {\tt getcols} werden lediglich den Spalten Variablen zugeordnet. Es
  213 soll ja z.B.\ dem Benutzer m"oglich sein, die Spalte 2 der Variable 1
  214 einer Prozedur zuzuordnen. In der Array-Variablen {\tt acol} wird
  215 diese Zuordnung gespeichert. Nehmen wir als Beispiel die Prozedur {\tt
  216   u\_test}: Diese Prozedur w"urde vier Parameter ben"otigen,
  217 n"amlich zwei Feldvariablen {\tt x} und {\tt y}, welche die
  218 eigentlichen Beobachtungswerte enthalten, und {\tt nx} und {\tt ny},
  219 die angeben, wie gro"s diese beiden Felder sind. Zun"achst wird also
  220 {\tt getcols(2)} aufgerufen, um den Dialog auszuf"uhren, welcher die
  221 Zuordnung der Spalten zu den Variablen "ubernimmt. Daher lautet der
  222 Aufruf also \\ \verb| u_test(xx[acol[0]],nn[acol[0]],
  223 xx[acol[1]],nn[acol[1]]); | \\ Es werden also {\em nicht\/} die
  224 Spalten 0 und 1 "ubergeben, sondern die, welche der Benutzer vorher
  225 der ersten und zweiten Variable zugeordnet hat!
  226 
  227 Um die Datentypen etwas flexibler zu halten, wurde f"ur Gleitkommazahlen
  228 (also f"ur "`normale"' Werte) der Typ {\tt REAL} eingef"uhrt, der momentan
  229 auf den Standardtyp {\tt double} gesetzt ist. Aus Konsistenzgr"unden
  230 sollte man also immer den Typ {\tt REAL} verwenden. Die Deklaration
  231 f"ur die Funktion {\tt u\_test} sollte also etwa folgenderma"sen
  232 aussehen: \\
  233 \verb|    void u_test(REAL x[], int nx, REAL y[], int ny);|
  234 
  235 Ist die Anzahl der Variablen, die einer Prozedur "ubergeben werden
  236 sollen, nicht festgelegt, so wird die Sache komplizierter. In diesem
  237 Falle gibt es einen Typ {\tt PREAL}, der einen Pointer auf ein {\tt
  238 REAL}-Array, also im Prinzip eine Spalte darstellt.
  239 {\tt PREAL} ist folgenderma"sen definiert:
  240 
  241 \begin{verbatim}
  242    typedef double REAL;
  243    typedef REAL* PREAL;
  244 \end{verbatim}
  245 
  246 Deklariert man nun ein Feld vom Typ {\tt PREAL}, so hat man eine
  247 zweiminensionale Matrix:
  248 
  249 \begin{verbatim}
  250    PREAL  xx[MCOL];
  251 \end{verbatim}
  252 
  253 Also mu"s eine zweidimensiomale Matrix immer als {\tt PREAL x[]} einer
  254 Prozedur "ubergeben werden.  Zus"atzlich sollte dann noch die Anzahl
  255 der Spalten und Spalten angegeben werden. Der ganze Hokuspokus mit
  256 {\tt PREAL} wird "ubrigens deswegen gemacht, um einer Prozedur eine
  257 Matrix als Parameter "ubergeben zu k"onnen, deren Spaltengr"o"se
  258 vollkommen variabel ist.  Wie in so einem Fall die Spalten den
  259 Variablen zugeordnet werden, schaue man sich anhand des Aufrufes der
  260 Prozedur {\tt correl\_matrix} an.
  261 
  262 
  263 \section{Fazit}
  264 \label{sec:fazit}
  265 
  266 Hier noch mal eine kurze Zusammenfasung, was zu tun ist, um \st um
  267 eine Prozedur zu erweitern:
  268 
  269 \begin{enumerate}
  270 \item In {\tt procs.h} die Prozedur {\tt extern}
  271   deklarieren (hierbei die Typen {\tt REAL} bzw.\ {\tt PREAL} verwenden).
  272 \item In {\tt procs.c} neue Prozedur definieren.
  273 \item In {\tt menue.c} das Men"u suchen, in welches die neue Prozedur
  274   am besten hineinpa"st und den Men"utext f"ur die neue Funktion
  275   hineinschreiben
  276 \item Im selben Men"u die entsprechende {\tt switch}-Anweisung
  277   suchen, die neue {\tt case}-Marke eintragen und dort den Dialog
  278   und den Aufruf f"ur die neue Prozedur hineinschreiben.
  279 \end{enumerate}
  280 
  281 \el
  282 Noch eine Bitte am Schlu"s: Wenn jemand das Programm erweitert hat,
  283 w"are es  {\em sehr\/} nett, wenn er mir die neue Version auch
  284 zukommen lassen w"urde!
  285 
  286 \end{document}