Aladin V1.0 ------------------- *** Shareware-Version *** by Volker Erb Ernst-Reuter-Str.31 D-W6508 Alzey Germany Phone: Germany- 6731-8167 (No fax, no modem, I'm still poor.) Before you read the manual, read this: To run this library you will need James Donnelly's "The HP 48 Programmer's ToolKit" (TLLIB and TBLIB) and about 60kB of free Memory !!!!! Well, English is not my tongue and I'm sorry about my poor orthography and the, hm, individual grammar and expressions ... This is the "small" fuzzy version. The full version is about one kByte bigger. All options or commands, which are marked (*) are not available (*-) or are in a less powerfull shareware version (#). Please, read the manual from the beginning to the end, you will like it. ----------------------------------------------------------------- ----------------------------------------------------------------- CONTENS 0. Prolog 1. Introduction 2. Programs and new commands 2.0 copyrgt 2.1 ARGUS (#) 2.2 DATUS (#) 2.3 DIRM 2.4 TABM (*-) 2.5 DEL 2.6 Y.N? 2.7 UNIT? 2.8 SELECT 2.9 ASK 2.10 ASK+ 2.11 CHECK 2.12 NMENU 2.13 NM+ 2.14 COMBI 2.15 TYP 2.16 OBJ 2.17 ANDOR 2.18 RF 2.19 RFP 2.20 RFD 2.21 RFQ 2.22 RFU 2.23 DRF 2.24 XUNIT 2.25 EXL 2.26 M->L 2.27 L->M 2.28 S->OB 2.29 DIG 2.30 MULTI 3. Compressed Libraries 3.1 How to compress libraries 4. Remarks to Aladin 1.0 5. Disclaimer ----------------------------------------------------------------- ----------------------------------------------------------------- 0. Prolog What is Aladin ? Aladin had a magic lamp and this will shine for you. In this libray is the newest shareware version of ARGUS (V4.0) and a new data analysis program called DATUS V2.0. Both together are the best and easiest way of getting from datas a complete error and data analysis with the possibilities of transfer the results to a PC or a MAC in three GROB's or print them on an IR-Printer or another printer. (Well, printing and transfering the results is possible in a few cases only.) However, some of the subprograms (TABM (*-), DIRM, ...) are so useful, that I included them for your use. I hope you can use them. For fast and good working, I included some genious programs of some other authors, which are freeware, and it wouldn't be nice not to mention them: A very big "Thank you" I have to say to Lutz Vieweg, Frankfurt, Germany for the Redundance Fighter V1.2 and XUNIT, which are included in the library. (Because they are partly changed, I distibute the original files with this library!) I want to thank Rick Grevelle for a small but essential program part from his HACKIT.LIB and, of cause, I include this library herein, too. (Have fun, if you start hacking this library, even, I couldn't do this without my notes! The source code are 70(!) pages and about 50kB) 1.Introduction When I presented ARGUS V3.2 to Lutz Vieweg, he answered me: nice program, but, what is it doing exactly? And I agree, I'm a bad author.... ARGUS is for error analysis. What is error analysis? If you are working with datas, which are from any kind of measurement or however lie in a small or big tolerance interval, you want to know, how good your results are. For example, if you want to measure the volume of a cube and your ruler's smallest scale are 1 mm and one or more length of the cube's sides are in between two millimeter lines (e.g. between 20 and 21 mm) you will have to estimate the exactly length. You can say: okay, 20,3 mm, maybe 0,2 mm more or less! So, you are estimating the accuracy of your measurement in the tolerance interval of 0,2 mm. So, what, why writing an huge program for that? This program calculates the geometric mean of the tolerance you are doing when you are calcu- lating the volume of the cube with you estimated values: Example: You measured A=22,2mm , B= 33,3mm and C= 44,4mm ;Tolerance:+-0,2mm Volume V= A*B*C = 32823,144 mm^3 the mean tolerance of the volume was defined by Gauss: delta V= SQR(((derivation of V from A)*delta A)^2+((derivation of V from B)*delta B)^2+((derivation of V from C)*delta C)^2)= 462,325 mm^3 So, you know, that you only can trust your result as far as 32800 mm^3 with a tolerance of 500 mm^3. Okay, you might say, nice, but why writing such a huge program for such a simple formular? This program is not only written for the mathamatic purpose but for the presentation and adaptation to other programs, too. For example, you can use all data, you have put in for ARGUS directely for DATUS, too and not only the "input-data", but the result data, too. Other included features are the conversion of the results into different unit systems and presentation of the equations in the equation writer format, the possible print out of the complete data table to an IR-Printer in vertical format or to a PC or MAC (#). You can treat your results statistically (See description of DATUS!) With other words many useful toys. The aim is a really professional data analysis program, you can use, if you don't have a computer to your hand and want a fancy data presentation. As far as I can decide this is the combination of ARGUS and DATUS a first step in this direction. One disadvantage of this program is its size. This library is optimized for space (but still needs more than 25kB to run). REMARK: Don't worry about the blinking annunciators and the disappearing display. This is due to Lutz Vieweg's Redundance Fighter and does not cause in a break down or a damage. Keep cool! ------------------------------------------------------------------ ------------------------------------------------------------------ 2. Programs and new commands ------------------------------------------------------------------ Menu label Full name (programmable) XLIB-Nr. COPYR copyrgt 1111 0 ARGU ARGUS 1111 1 (#) DATUS DATUS 1111 2 (#) DIRM DIRM 1111 3 TABM TABM 1111 4 (*-) DEL DEL 1111 5 Y.N? Y.N? 1111 6 UNIT? UNIT? 1111 7 SELEC SELECT 1111 8 ASK ASK 1111 9 ASK+ ASK+ 1111 10 CHEC CHECK 1111 11 NMEN NMENU 1111 12 NM+ NM+ 1111 13 COMBI COMBI 1111 14 TYP TYP 1111 15 OBJ OBJ 1111 16 ANDO ANDOR 1111 17 RF RF 1111 18 RFP RFP 1111 19 RFD RFD 1111 20 RFQ RFQ 1111 21 RFU RFU 1111 22 DRF DRF 1111 23 XUNIT XUNIT 1111 24 EXL EXL 1111 25 M->L M->L 1111 26 L->M L->M 1111 27 S->OB S->OB 1111 28 DIG DIG 1111 29 MULTI MULTI 1111 30 ------------------------------------------------------------------ 2.0 shows the copy right notice and installs <&&&>. Without <&&&> the whole library will not work. To reinstall &&&, press ! ------------------------------------------------------------------ 2.1 The function of ARGUS was described in the introduction. in 2.1 the single steps are mentioned. 2.1.1 Getting started with ARGUS Press or use ARGUS as a command in a program or type in ARGUS and press [ENTER]. Everything works ? Okay ... 2.1.2 The second display explains, how to type in an equation. The equation has to be in quotes and the must be a single variable name before an equation mark. There is also the possibility to use the equation writer. Be sure that if you want to use units with your analysis later on, the equation doesn't cause an "Inconsistant Units Error". 2.1.3 The next display asks to continue your session with ARGUS. If you made a mistake in your equation and pressed accidentally [ENTER], or you don't like a data analysis, press now and leave the program. 2.1.3.1 You really pressed : ARGUS creates a directory in the HOME directory, called . In the case of ARGUS builds up a subdirectory in the Argus directory like E.1 or E.2 ... . In these E-directories are three variabeles now: EVIEW, EEQ, and EQN, where EQN the given equation, EEQ its gaussian error equation and EVIEW a program, which shows GROB's of the equations, are. 2.1.3.1.1 How EVIEW works: EVIEW creates GROB's of the equations in the Equation Writer format and store them in the temptorary variables EQG and EEG, which will be purged at the end. Press the [ON] key to go through the equations. At the end EVIEW offers to print the equations on an IR-printer (Yes, it does!). 2.1.3.2 You pressed : Go on with 2.1.4 . If you tried and started again, don't 'DEL'ete the E-directories. Now everthing is stored into A-directories (A.1, A.2, ...) 2.1.4 Now you are asked to choose units (or not). 2.1.4.1 You like to use units with your data values: Press . ARGUS will ask units for each variable. This asking is supported by the UNIT? command (see chapter 2.7). 2.1.4.2 You don't like units: Press . ARGUS will set all unit equal to 1 and won't ask for them. It is the faster way. 2.1.5 After the preparation for the data analysis, ARGUS wants to know the values for each variable and its confidence range. Be careful, if you typed in a wrong value and pressed [ENTER], there is no possibility to correct this mistake !!! After the first set of values, you will be asked for another set. If you are choosing more than 2 sets, you are able to use the statistic devices of DATUS. Before you can give the second set of values, you have to define the number of valid digits on the following displays. I recomment 4 valid digits. The displays show the actuell variable name, the variable's unit and the last value. There are two new commands on the menu line: : keeps the last value for the actuell set and the value will be asked again at the next set. : keeps the last value for the actuell and all following set constant and will not be asked again. A value on the stack has priority before and and will be taken as the actuell value, if you press or and will be asked again at the next set. After the last set, press , when you are asked for another set. Then the 48 will take some time to organize all this stuff. I'm working out this to make it faster. 2.1.6 Then ARGUS offers you to look at your results and activates the RVIEW and the EVIEW programs in the actuell A-directory. For more details look in chapter 2.1.9) 2.1.7 If you have given more than two data sets, you are able to use DATUS' statistic devices, if you like to look for some correlat- ions of given variables or results. Sometimes it's interesting to look for the relationship of the final relative or absolute confidence range of the calculated variable and some mesured variables. For more details see chapter 2.2.4 and following. 2.1.8 (*-) Finally you have the possibility to create a complete result table with all given and calculated values and the two equations. Every- thing will be stored in the compressed program RTAB in the A-directory. 2.1.9 Remaining variables: 1) RTAB (*-) Program, which shows the result table with all details and the possibility to print it on an IR-printer. After the run the result tabel remains as PICT. This program is compressed. 2) GR.x - directories: For more details see chapter 2.2.13 1). 3) TBLIST List of strings of the variable names. Necessary for DATUS. 4) EVIEW Program, which shows the used equations in equation writer format and which can print out the equations to an IR-printer. This program is compressed). 5) RVIEW Program, which shows the results in a fancy way. (Compressed) 6) DSIZE Number of data sets. Necessary for DATUS and RVIEW. 7) &&D Last used number of valid digits 8) DMAT Data matrix of the same size and order as DLIST. (Compressed) 9) DLIST List of lists: First list: names of variables with their units in the valid order second list: the units in the valid order all other lists: values of the variables in the valid order. 10) ASKLIST Same as TBLIST, but no strings 11) EEQ Gaussian error equation 12) EQN Origin equation ------------------------------------------------------------------ 2.2 DATUS is a complete data analysis program with linear and none linear regression. There are options to linearize none linear regressions, optimize linear or linearized regressions, check for out-of-confidence values. This is the fuzzy part of the program, because the program knows the tolerances of each point of the measurement, it weigthes the importance of each of them and is able to do the same as you, if you try to draw the most possible correlation curve between the points. Finally you will get a result GROB with all details and a statistical plot (...with drawn confidence ranges, which can be transfered to a PC/MAC and an IR-printer.(*-) ). The advantage of DATUS is its compatibility with ARGUS. You can use all datas stored in A- and D-directories, as long as they have the same data size (Same number of data sets). 2.2.1 Getting started with DATUS See chapter 2.1.1 . 2.2.2 If you want to use data from an A_- or/and D-directory, press , else 2.2.2.1 You pressed : In this level DATUS offers you the possible A- and D-directories. The first selection defines the data dimension for the current data analysis. For the further procedure only directories with the same data size will be accepted. or [ENTER] switches into the highlighted directory and quit this level to the "Own variable input"-level. 2.2.2.1.1 You pressed : All variables of the chosen directory are offered now. Choose with the variables you like. You don't need to choose the confidence ranges with the "main"-variables, they will be treated automatically. If you have chosen confidence ranges as "main"- variables, the confidence ranges of the confidence ranges are set equal to zero (and the c-range of ERROR, too!) switches to the directory choosing level again and you may choose another directory or the same again. This procedure has one disadvantage: You can't correlate data with the same variable name from different directories ! 2.2.2.1.2 You pressed : You are leaving the "Choose Directory"-level, DATUS organizes the data from different directories to a new data list and matrix, or if you didn't choose data from other directories DATUS prepares everything for the data input. 2.2.2.2 You pressed : DATUS skips the "Choose Directory"-level 2.2.3 Now you will be asked for "own" variables. "Own" variables are variables, which don't come from A- or D-directories and have to be typed in by hand. There are three possibilities: a) You didn't choose variables from A- or D-directories, b) you chose one variable from directories, c) you chose more tha one variable from directories. to a): You pressed : DATUS quits, because you obviously don't want a data analysis. You pressed : DATUS asks for new variable names until you gave a minimum of two and pressed . For more details of the asking look chapter 2.1.4 . to b): You pressed : DATUS asked for one more variable name and then asks for new variable names as long as you don't press . Then a asking routine like 2.1.4 asks for units and data values until the new data matrix has the same number of data sets as the given data from the directory . You pressed : The same procedure as if you press . to c): You pressed : DATUS proceeds with the given data. You pressed : see 2.1.4. 2.2.4 The next display offers you all possible variables, you have chosen in the directories and/or typed in by hand. You have to choose now the independent variable (X-Axis), by using the arrow keys and the [ENTER] key. Then the same display, but without the chosen independent variable is asking you to choose the dependent variable. If you have made a mistake when you have chosen your independent variable, you may correct it now by choosing the empty field. Then the first (complete) display asks for the independent variable again. 2.2.5 After choosing the variables, you will be asked for the prefered regression model. In this version of DATUS only the build in model are offered. Use the arrow keys and [ENTER]. If you chose , a short message shows the best model. 2.2.6 The next option let you decide wether you like the untreated regression (faster and not optimized) or a linearized and optimized regression (slower, but with some fancy properties, like confidence calculation for the regression's parameters). 2.2.6.1 Linearization: origin. linearized indep. dep. indep. dep. EXPFIT: X Y X ln(Y) LOGFIT: X Y ln(X) Y PWRFIT: X Y ln(X) ln(Y) LINFIT: X Y X Y 2.2.6.2 Optimization: The program does the same, as you do, if you try to fit a curve between the data points in a statistical plot on a sheet of paper: You try to go with your curve though as many as possible confidence ranges of the dots. With other words, the program checks, if the curve touches the confidence range of a data point. If not, the originally data point is replaced by the nearest piont of the c-range. This correlates with a devaluation of the priority of data points, who's c-ranges are not touched by the regression curve. After all points were checked and a minimum of one point was not touched, the regression curve is calculated again and the check starts again. A optimization is not necessary, if the correlation coefficent is better than 0.999. The second level of the optimization is the check for out-of- confidence values. This routine starts, if the correlation coefficent is smaller than 0,99. A "out-of-confidence"-value is a value with a distance d from the curve with: d >= X^(-1) * Z * SDEV, Z = 8,557*X^(-0,671) for N < 13 = 2,847*X^(-0,108) for N >=13 X = N-2 , N = number of data sets SDEV = standard deviation of the distances from data points to the curve. This is valid for P = 95% of both sides of the curve. That means, the probability to find a data point in the calculated ranges is 0,95. 2.2.7 Then DATUS asks for the number of valid digits in the result text and table. In the result text all important parameters are given. For a linear or a linearized regression c-ranges for the para- meters are calculated, too: deltaSlope = T * S, deltaIntercept = T * I T = 1,006 * EXP(-0,053 * (N - 2)) S = SQR((N * ((N - 2)^(-1) * ((SIGM(Y^2) - ... ...- (Intercept * SIGM(Y) + Slope * SIGM(X * Y)))/ ... .../(N * SIGM(X^2) - (SIGM(X))^2)) I = SQR((SIGM(X^2) * ((N - 2)^(-1) * ((SIGM(Y^2) - ... ...- (Intercept * SIGM(Y) + Slope * SIGM(X * Y)))/ ... .../(N * SIGM(X^2) - (SIGM(X))^2)) N = number of data sets, SQR = squareroot, SIGM = capital sigma (sign for summation) 2.2.8 The third part of the resolts GROB is the statistical plot, with all data points and their c-ranges. You are able to choose line filling or no line filling for your curve. 2.2.9 The Results GROB The first part is the regression analysis, with informations concerning the origin model, the parameters, c-ranges etc... The second part is the table of values: If you chose a linearized mode, you will get two tables, one with the origin values and the other one the the transformed values. If there are any out-of- confidence values, then they are labeled with a cross. The third part is the statistical plot. It always shows the origin. The numbers closest to the origin are the distances between two intersection points on the axes. The data points are surrounded by their confidence squares. A out-of-confidence value is labeled with a cross. Anything else is described in the owner's handbook. 2.2.9.1 DATUS shows the results GROB. You can scroll around with the arrow keys and proceed with the [ON] key. (In a registrated version you will get a single output file, which contains the whole story and is able to print out or to transfere the results to a computer. You are able to see the results in a very fance kind without starting the whole program!!!) 2.2.10 If an errors occures (for example negative values in a regression model, where no negative values are allowed) or at the end of the regression analysis, you will be asked, to try another model. (Then start reading again from 2.2.6) 2.2.11 The next upper level asks, if you like to try another analysis with some other chosen variables. (Then start reading again from 2.2.4) 2.2.12 (*-) Finally, you will ask to summarize all data values in a "result table". This means only the untreated values without any regres- sions etc... . 2.2.13 Remaining variables DATUS creates the D-subdirectories, where all results are stored. 1) GR.1, GR.2, ... GR.x subdirectories Variables in a GR-subdirectory: 1.1) RPAR.y Regression parameters Position designation 1-7 PPAR 8-12 SIGMPAR 13 deltaIntercept 14 deltaSlope 15 Regression equation 16 corr. coeff. before treatment 17 corr. coeff. after treatment 18 vertical pixel height of SPLOT.GRO 19 vertical pixel height of STABL.GRO 20 vertical pixel height of STEXT.GRO 1.2) STP.y (*-) 2) TBLIST \ 3) &&D \ 4) DMAT \ 2) - 7) see 2.1.9 5) DLIST / 6) DSIZE / 7) ASKLIST / ------------------------------------------------------------------ 2.3 DIRM creates directories with same names and continuing number extensions (for example, ABC.1, ABC.2, ABC.3,...) and switches into them. 2.3.1 SYNTAX Examples: (Use the same order if you try these!) 1) level 1: "ABC.1" ; --> creating ABC.1 dir. and switches into it. 2) level 1: "ABC.1" ; --> creating ABC.2 dir. and switches into it. 3) level 1: "ABC.4" ; --> creating ABC.4 dir. and switches into it. 4) level 1: "ABC.1" ; --> creating ABC.3 dir. and switches into it. Advantage: You may use this command in a routine, to store results in sorted directories. ------------------------------------------------------------------ 2.4 (*-) TABM creates a table from a title string, a list with head lines (strings, object names, etc) and lists of values. The format of this table is vertical, because it's better for print outs on an IR-printer. 2.4.1 Syntax Input: (Example !) Output: 1) Empty stack level 4: { 4 5 6 } 2) Table in PICT (horizontal) level 3: { 1 2 3 } 3) Program RTAB (compressed), level 2: { A B C } which offers the possibilities level 1: "Title" of viewing, transfering and printing the table. Table: ________________________________ |Title | | | | 'A' 'B' 'C' | | 1 2 3 | | 4 5 6 | -------------------------------- (without the lines !) If you don't want the quotation marks in the heads, use strings ! ------------------------------------------------------------------ 2.5 is the universal purging program, which deletes even large programs in a relatively short time, by using a trick (Described by Joseph K. Horn in FPGDIR). There is a safty quastionary built in, which askes you, if you really want to purge a directory. 2.5.1 Syntax: Input: level 1: variable name, directory name, objects, and mixed lists of the named objects and names, except numbers, arrays and libraries. I recomment to asign this program to the [DEL] key. (I really don't know, why there occurs a 1 or a 0 when the program ends. There is no such command in the source -maybe a hardware bug?!) ------------------------------------------------------------------ 2.6 Takes a YES-NO-question in a string from level one, and creates a display with this question and a menu line with and . The only possible inputs except and are 1 and 0, which are standing for the same (True, yes, 1 and false, no, 0). 2.6.1 Syntax: Input: level 1: "Question?" Output: level 1: 1 or 0 ------------------------------------------------------------------ 2.7 Takes a name or a object as a string or in quotes from level one and asks for a unit of this name. 2.7.1 Syntax: Input: level 1: "A" or 'A' Output: level 2: "A" or 'A' level 1: 1_chosen unit 2.7.2 The menu line of If you don't want to have a unit with your variable value, press , and UNIT? will give back a 1 in level 1. The three dots on the last menu label mean, that there is at least one more page, if you press [NXT]. 2.7.2.1 Switching through the unit menus The best way to explain it, is to go through an example: a) Press , a 1 appears in level 1 and the LENG-menu is offered. Choose a unit by pressing its menu label and press [ENTER]. b) Go again into the LENG-menu. Now, you want to go from the LENG- to the ENRG-menu: press orange shift ['] ([UP]), and you see, that the 1 disappears and you are back in the main unit menu. Press [NXT] and choose . You are now in the ENRG menu and the 1 is there again. Press the -key to get 1_kcal on level one. Press orange shift ['] again to go back to the main unit menu and press again . Now you will find a 1 in level one and the 1_kcal in level two. Choose and you will get 1_mm in level one. This is the moment, when you may choose wether you want to multiply or to divide or to swap and divide or do anything else with these two units. Finally you press [ENTER] to get your output. ------------------------------------------------------------------ 2.8