Dear ASReml user, These notes relate to ASReml 1.62x (and subsequent versions). This developmental 'Beta' version will stop working on 22 March, 2005, five months from its version date (22 Nov, 2004). Therefore do not destroy your current validated version [1.00 or 1.10]. INSTALLATION: ************* You need to have a licensed copy of ASReml before attempting to run this version. Windows ******* Under Windows, ASReml is normally installed by the install program in C:\Program Files\ASReml\bin. This directory will normally contain ASREML.EXE (the ASReml program executable file) and ASREML.ALX (the ASReml license file). If installing an updated version manually, we suggest you retain the existing version by changing its name to (say) ASREML100.EXE. Then copy the new version (say) ASReml162.EXE into the directory and change its name to ASREML.EXE. Unix **** See separate INSTALL.TXT file ------------------------------------------------------------------------ This file briefly documents options added to ASReml since release 1.00. These changes are documented more completely in the Draft revised Reference Manual [asref162.pdf] also available from VSN. NB The User Guide has not yet been updated to include these changes. As in the Reference Manual and User Guide square brackets, [], are used to denote Optional arguments. Notice that developments to ASReml may generate bugs which take time to identify and fix. Therefore all Beta versions should be used with care and results checked for reasonableness. Please report any suspected bugs. Bugs that have been fixed are not documented here. ------------------ Critical Changes to Behaviour --------------------- The order predicted values are presented has changed. Now combinations of factors are ordered respective to the order of the factors in the PREDICT statement with the rightmost factor levels changing fastest and the leftmost factor moving slowest. If there are two factors then the second factor's level change faster. XFA model fitting extended to allow Zero PSIs in multiple XFA terms and allow interaction of XFA with other structures. However, XFA x XFA (both with zero PSIs) is not covered. The work around in this latter case is to fix 'ZERO' PSIs at 0.001 in one term. In 3-way terms, only XFA x I x A and A x I x XFA allowed. SYNTAX change in model specification: A/B now expands to A A.B Added procedure for ASReml to automatically increase workspace in large jobs. Changes to the rules for modifying the AI update mean that the iteration sequence may differ slightly in some jobs. If the amount of workspace allocated is found to be inadequate, ASReml will attempt to increase it. ------------------ Summary of changes ---------------------- Commmand line Options: ********************** A new command line option A has been added to make it easier to specify command line options in Windows Explorer. One of the options available when right clicking a .as file, invokes ASReml with this option. ASReml then prompts for an option string and arguments string, allowing these to be set interactively at run time. A new command line option B suppresses some of the information written to the .asr file: the data summary and regression coefficient estimates are suppressed. This qualifier should not be used for initial runs of a job until you have verified the data is read correctly. Use B2 to cause the predicted values to be written to the .asr file instead of the .pvs file. A new command line option H allows graphics to be written to file but not displayed on the screen. The H may be followed by a file type code using the same codes as defined for the G option e.g. H22 for .eps. Command line option Wm The W option may be followed by the number of Mbytes required. For example W1600 requests 1600 Mbytes of workspace, the maximum available under Windows. If the requested workspace is not available, the requested size is reduced in a linear manner until the allocation is successful. New optional header line. ************************* Command line information may alternatively be specified on a new optional header line. If the first line of the .as file contains a qualifier other than !DOPART, it is interpreted as setting command line 'option's and the Title line is taken as the next line. This line has 2 alternative forms: 1) sequence of regular ASReml qualifiers 2) !-o arg to mimic the command line Sequence of regular ASReml qualifiers These qualifiers relate directly to command line options !ASK equivalent to command line option A. Prompts for an options string and arguments. The options string may contain -BCDEFGHILNRSTW For example -HR 01 02 03 might be the response. It is assumed that no other qualifiers are set on this line when !ASK is specified. !BRIEF [2] equivalent to command line options B[2] or dataline qualifier !BRIEF [2] !CONTINUE equivalent to command line option C or dataline qualifier !CONTINUE !DEBUG equivalent to command line option D !FINAL equivalent to command line option F !GRAPHICS [g] equivalent to command line option G[g] !HARDCOPY [g] equivalent to command line option H[g] !LOG equivalent to command line option L !JOIN equivalent to command line option J !NOGRAPHICS equivalent to command line N !REPEAT equivalent to command line option R !TEST equivalent to command line option T !WORK m equivalent to command line option Wm To allow the introduction of arguments one can use the qualifier !ARGS and the elements on the rest of line are interpreted as command line arguments !-o arg where o is the option letter string basically as defined for the command line options and 'arg' is a list of 'command line' arguments. E.g. !-h22r 01 02 03 Factor Definition qualifiers **************************** !SORT declared after !A or !I on a factor definition line will cause ASReml to sort the labels for the analysis. !SORTALL means that the levels for the current and subsequent factors are to be sorted. !REPLACE o n replaces data values o with n IF(DV.EQ.o) DV=n !RESCALE o s rescales the column(s) (Y) using (Y+o)*s !MM mm mm is a marker map !DOM a a is the Additive marker data These apply to a !G group of variables !SKIP f will skip f data fields BEFORE reading this field. !DATE allows date formats dd/mm/yy, dd/mm/ccyy, dd-Mon-yy, dd-Mon-ccyy, hh:mm:ss !DMY allows date formats dd/mm/yy, dd/mm/ccyy, [159f] !MDY allows date formats mm/dd/yy, mm/dd/ccyy, [159f] converting the dates to days since 1799, times to seconds. yy 0-32 taken as 2000-2032, 33-99 taken as 1933-1999 Storage of factor level labels changed. Previously there was space for 5000 labels of 20 characters long. Now space is allocated dynamically with default allocation being 2000 labels of 16 characters long. If there are large !A factors (so that the total across all factors will exceed 2000), you must specify the anticipated size (within say 5%). If some labels are longer then 16 characters and the extra characters are significant, you must lengthen the space for each label by specifying !LL c e.g. cross !A 2300 !LL 48 indicates the factor 'cross' will have about 2300 levels and needs 48 characters to hold the level names. NB At present only the first 20 characters of the labels are printed. GIV Files ********* The standard giv file procedure expects the user will supply an inverse matrix. In some situations, it is easier to form the uninverted matrix and not very convenient inverting it outside of ASReml to create the .giv file. In this case, supply the uninverted matrix in a sparse format file but with a file extention .grm. ASReml will then invert the matrix itself before it uses it. Pedigree file line qualifiers ***************************** New pedigree options: Pedigree.pdf contains details. !GROUP empty groups become Lagrangian group constraints !MGS now formed directly rather than by inserting dummy DAMs !SELF s allow partial selfing when 'Dam'=='Male parent' unspecified. !INBRED 1. generates pedigree for inbred lines. Inserted ability to generate simple Lagrangian constraints to genetic groups by inserting Dummy groups. When there are two or more groups containing animals followed by a group with no animals, the A inverse line for the empty group is replaced with a line containing 1's for the preceding set of groups, and zero otherwise. This constrains the genetic group effects to sum to zero. Formation of the A-inverse has been speeded up (substantial gain if many animals without progeny) !DIAG qualifier used to return the diagonal of the A-inverse matrix in AINVERSE.DIA. Now it also returns the inbreeding coefficients for the individuals (calculated as diagonal of A-I). !SORT causes ASReml to sort the pedigree into an acceptable order, before forming the A-Inverse. The sorted file has .SRT appended to the filename. Reading Data ************ ASReml now reads data from multiple files provided the files have the same layout. The file specified as the data file can contain lines of the form INCLUDE filename !SKIP n where 'filename' is the (path)name of the data subfile and !SKIP n is an optional qualifier indicating that the first n lines of the subfile are to be skipped. After reading each subfile, input reverts to the primary data file. If the subfiles have CSV format, then either the primary file should have the .csv extension, or the !CSV file should be declared. Data file line qualifiers ************************* Datafilename line qualifiers may also be defined using an {\sl environment variable} called {\tt ASREML\_QUAL}. The environment variable is processed immediately after the data file name line is processed. !AILOADINGS [i] controls modification to AI updates of loadings. AI updates are performed always after iteration i. !AISINGULARITIES can be specified to force a job to continue even though a singularity was detected in the AI matrix. Normally, the model should be respecified to remove singularities in the AI matrix. !BMP sets hardcopy graphics file type to .bmp. !BRIEF suppresses some of the information written to the .asr file. The data summary and regression coefficient estimates are suppressed. This qualifier should not be used for initial runs of a job until you have verified the data is read correctly. Use !BRIEF 2 to cause the predicted values to be written to the .asr file instead of the .pvs file. The qualifier may be set with the B command line option. !CONTRAST label ref values provides a convenient way to define contrasts among treatment levels. !CONTRAST lines occur between the Data File Name line and the model line. 'label' is the name of the model term being defined. 'ref' is the name of an existing factor. 'values' is the list of contrast coefficients. For example !CONTRAST LinN Nitrogen 3 1 -1 -3 defines LinN as a contrast based on the 4 levels of factor Nitogen. The user should check the levels if the factor are in the order assumed by contrast (check .ass or .sln or .tab files). !DDF 1 requests calculation of Denominator DF This is now the default for small jobs (<1000 observations) !DDF -1 suppresses calculation of Denominator DF NB. The option is inactive under more complex variance structures with 90 or more variance parameters. !DENSE n Dataline qualifier !DENSE has been modified to accept an argument up to 5000. The default max equations in Dense matrix is still 800. !DOPART i can now be located anywhere in the job. !EPS sets hardcopy graphics file type to .eps. !HPGL sets hardcopy graphics file type to HP GL. !HPGL 2 sets hardcopy graphics file type to HP GL 2. !PS sets hardcopy graphics file type to .ps. !RREC [n] cause ASReml to read up to a data error (then process the records it has) or to read n records. Useful for extracting predicted values from a .pvs file. !MBF mbf(X,#) filename !skip n as qualifier line after the data file name line to predefine model term mbf(X,#) as a set of covariates indexed by the data values. X is the variate in the data containing the data values to be used to associate the covariate values with the records. # is the number of covariates. filename is a file containing 1+# fields where the first field contains the data values, the remaining # fields define the corresponding covariate valies. !skip n is an optional qualifier which requests the first n lines of the file be ignored. !SCORE qualifier requests ASReml write the SCORE vector and the Average Information matrix to files .SCO and .AIM The values written are from the last iteration. !SCREEN $n$ qualifier a Regression Screen, a form of all subsets regression. It produces a report to the .asr file showing the sums of squares attributable to each submodel including up to six of up to 20 terms in the DENSE equations. Use the !DENSE qualifier to control which terms are screened. The screen is conditional on all other terms (those in the SPARSE equations) being present. Every submodel will have at lease $n$ terms [default 1]. Use {\tt !SMX $m$} to set the maximum number of terms to include in each model [default 6]. !SLNFORM [i] qualifier modifies the format of the .SLN file. !SLNFORM -1 prevents the .sln file from being written. !SLNFORM [1] replaces some spaces with TAB and changes the file extension to .sln.txt. This makes it easier to load the solutions into Excel. !SLNFORM 2 replaces multiple spaces with COMMA and changes the file extention to .sln.csv. However, since factor labels sometimes contain COMMAS, this form is not so convenient. Omitting the argument invokes the TAB format. Omitting the qualifier means the standard fixed field format is used. !SPATIAL increases the amount of information reported on the residuals obtained from the analysis of a two dimensional field trial. The information is written to the .res file. !SUM causes ASReml to report a general analysis of the distribution of the data. The information is written to the .ass file. !TWOWAY modifies the appearance of the variogram calculated from the residuals obtained from a two dimensional field trial. The default form combines NE and NW heights into an average value. The new form plats NE and NW distances separately. !VRB requests writing of .vrb file. Previously, the default was to write this file but as it is rarely used, the default is now not to write the file. !WMF sets hardcopy graphics file type to .wmf. New Model terms. *************** at(F,n) extended so that at(F,i).X at(F,j).X at(F,k).X can be written as at(F,i,j,k).X NB The at(F,i,j,k) term must be the first component of the interaction. Any number of levels mat be listed. at(F,i) extended so that at(F) generates at(F,i) for all levels of F. NB. Since this command is interpreted before the data is read, it is necessary to declare the number of levels correctly in the factor definition. This extended form may only be used as the first term in an interaction. ge(F,n), gt(F,n), le(F,n) and lt(F,n) create binary covariates indicating whether the level code for factor F is greater (less) than the argument n. They are similar to at(F,n) which indicates whether the level code equals n. qtl(M,s) calculates an expected marker state from flanking marker information at position s of the linkage group (see !MM to define marker locations). PREDICT ******* The !PLOT qualifier has been revamped by Damian Collins. Now possible to include SE bars, and the data on the plot figure. TABULATE ******** TABULATE statements may now appear before the model line as this is logically, a better place for them. However, a linear model must still be supplied. The qualifiers for optional output are: {\tt !COUNT, !SD, !RANGE !STATS}. !STATS is shorthand for !COUNT !SD !RANGE New variance models: ******************* Autoregressive models have been extended to include AR3 and SAR2. SAR2 is a constrained form of AR3 which represents the situation of competition from neighbouring plots plus general spatial correlation. CHOLnC is an alternative zeroed form of CHOLn defining a reduced cholesky factorization. CHOL models use structure V=LDL' where L has 1.0 on the diagonal, zeros above the diagonal, D is diagonal. CHOL1 extends this by setting lower triangle elements of L to zero except the first off diagonal band. CHOL1C extends this by setting lower triangle elements of L to zero except the first column of L. The CHOLnC form is somewhat similar to a Factor Analytic model. MATn Matern spatial correlation model has five parameters PHI NU DELTA ALPHA LAMBDA Use n to specify how many parameters to set; !Gxxxx to indicate which are fixed. PHI is a range variable, NU is a shape variable, default value 0.5 DELTA is a geometric anisotropy ratio, default value 1 is isotropic ALPHA is a geometric anisotropy rotation angle (given anisotropy), LAMBDA is distance measure: 1 is city block, 2 (default) is euclidean distance. Variance model qualifiers ************************* != qualifier extension Fixed bug in != qualifier and extended it as follows Extended syntax as follows: 1-9 different from a-z different from A-Z [0 and . mean unconstrained] Allow colon to generate sequence a:e is the same as abcde !=%.. Means code is absolute and is used to equate parameters across structures !=* indicates special form where numbers are repeat counts and A-Z are equality codes, . is unconstrained [!=*.3A2. is equivalent to !=0AAA00 or !=0aaa00] OUTPUT ****** A hardcopy Line printer plot of Residuals vs Predicted values is now printed to the .res file with other residual statistics. Internal Changes **************** 17 June 2004 Input record length increased to 2048 characters