asreml

Supply optional arguments.

Arguments:

• aisingularities: A bool value that forces the computation to continue even if singularities are detected in the Average Information (AI) matrix.
• arlimit: A float value, r. When the correlation parameter in an ar1() model goes to the boundary (+/- 0.999) the boundary limit for the magnitude of the AR parameter is reset to r. The default value is 0.75.
• asuv: A bool value allowing for an error variance structure other than block unstructured for a multivariate model.
• automatically_display_output: A bool value used as the default value for the display argument on most output functions
• automatically_return_all: A bool value used as the default value for the return_all argument on most output functions
• blup: An integer value, i, controlling how the coefficients and their standard errors are calculated.
  • i = 1 to 3: forming the estimates by matrix inversion.
  • i = 4: forming the estimates using the Preconditioned Conjugate Gradient (PCG) method (Mrode, 2005).
  • i = 10 to 19: forming the estimates by Gauss-Seidel iteration of the mixed model equations, with relaxation factor i/10.
• ddf: Either True or an integer value, i, which request computation of approximate denominator degrees of freedom according to Kenward and Roger (1997) for testing of fixed effects terms in the dense part of the linear mixed model.
  • i = -1: suppresses computation
  • i = 1: degrees of freedom are calculated using numerical methods
  • i = 2: degrees of freedom are calculated using algebraic methods If a value of True is supplied then a default method is used depending on the size of the problem.
• dense: An integer i, controlling the number of equations solved densely. By default sparse matrix methods are applied to random effects and any fixed effects supplied via the sparse argument. Dense methods are applied to any other fixed effects. If dense is supplied, then sparse methods are applied to the last i fixed effects.
• design: A bool value indicating whether the design matrix should be explicitly constructed. If True, the design matrix can be returned using the asreml.asreml_class.design_matrix method.
• emflag: An integer value. This option and the pxem option request the use of Expectation-Maximization (EM) updates rather than Average Information (AI) updates when the AI updates would make a US structure non-positive definite.
• extra: An integer value, i, which forces another mod(i, 10) rounds of iteration after apparent convergence, defaults to 0.
• fcon: A bool value that adds a 'conditional' Wald F statistic column to the Wald F Statistics table.
• gdense: A bool value that causes the first random term to be included in the dense equations if it is a GRM/GIV variance structure.
• hold: A list of integer values indicating the numeric ID of the variance parameters to fix at their initial value.
• knot_points: A dictionary or list of dictionaries, specifying knot points. The dictionaries should contain two keys, "name" and "values", where "name" specifies the name of a factor appearing in a spl() function and the "values" give a list of knot points to use for that factor.
• maxiterations: An integer value which sets the maximum number of iterations. The default value depends on the type of model being fit.
• na_action: A dictionary specifying the method to use for missing values. Its keys should be one or more of "x" and "y". The valid values for both "x" and y are: "fail", "omit" and "include". Example: {"y":"omit", "x":"omit"}. The default value is "omit" for both.
  • "omit": records with missing values are omitted from the analysis
  • "include": records with missing values are included in the analysis and the missing value is treated as zero
  • "fail": report any missing values
• pxem: An integer value. See the description of the emflag option for details.
• screen: An integer value. This option along with the smx option performs a 'Regression Screen', a form of all subsets regression. For d model terms in the dense equations there are pow(2, d) - 1 possible submodels. Since this can be large, the submodels explored are reduced so that only models with at least n (default 1) terms and no more than m (default 6) terms are considered. Where n is the value supplied via the screen option and m the value supplied via the smx option.
• slow: An integer value, i, that reduces the update step size of the variance parameters more persistently than the step_size option. If supplied then the potential size of the updates are looked at and if any are large, then the step size is reduced. If i is greater than 10 then the Information matrix is also modified by multiplying the diagonal elements by i which has the effect of further reducing the updates.
• smx: An integer value. See the description of the screen option for details.
• spatial: A bool value that increases the amount of information reported on the residuals obtained from the analysis of a two-dimensional regular grid field trial.
• step_size: A float value, r, that reduces the update step sizes of the variance parameters. The default value is the reciprocal of the square root of the maximum number of iterations. The step size is increased towards 1 each iteration.
• trace: A bool value controlling if the log-likelihood, sigma^2, degrees of freedom and time will be printed at each iteration, defaults to True.
• twostageweights: A bool value that is intended for use with variety trials which will subsequently be combined in meta analysis.
• varscale: A float value, r, used to scale the variance parameters. If r == 1 then the sigma parameterization is used.
• wald: A dictionary specifying options to control the Wald test. The dictionary keys and associated values should tie up with the arguments of the asreml.asreml_class.setup_wald method.

Supply data for the model.

Arguments:

• data: data used by the model. Multiple data sources are allowed, however the first supplied data is the primary data source (and is where the response variables etc that make up the model are taken from), this must be a pandas data frame, each variable must be numeric and categorical variables should be indicated using the pandas categorical data type.
• categories: dictionary, with keys set to the name of categorical variables and the associated values a list holding the level decodes, so categories[vname][i] is the label associated with a value of i for data[vname]). This is ignored if data is not a pandas data frame. See also asreml.define_categorical_variables.
• groups: dictionary, with keys defining a label for a group of variables and the associated values a list holding the variable IDs that form the group. Grouped covariates are treated together in the model.
• name: name for the dataset, this is optional only for the primary data source (i.e. it must be supplied for all secondary data sources). The supplied name is how secondary data sources should be referenced in the model.

setup the model

Arguments:

• response: A string or list of strings specifying the response variable(s).
• fixed: A formula string specifying the fixed terms in the model.
• random: A formula string specifying the random effects in the model.
• sparse: A formula string specifying the fixed effects for which the full variance-covariance matrix is not required.
• residual: A formula string specifying the residual model.
• family: A string specifying the link and variance functions. For example "binomial(link=probit, dispersion=1, total=counts)"
• weights: A string identifying the column of data to use as weights in the fit.

Formula Strings:

A formula string takes the form: 'v1+v2+v3' where v1, v2 and v3 are names of the variables to include in the model, as well as '+' a number of other operators can be used as detailed below.

As well as variable names, a formula string can contain one or more functions, for example: 'ar1(v1):arma(v2)', see asreml.model_function_info for details on the available functions.

Formula String Operators:

• '+' = operator used to include the following term in the model
• '-' = operator used to drop the following term from the model
• ':' = operator to indicate an interaction between the terms, for example 'v1:v2:v3' indicates a three way interaction between variables v1, v2 and v3
• '*' = short hand operator used to indicate interactions and main effects for example 'v1*v2*v3' would include all main effects, two and three way interactions between v1, v2 and v3, so is equivalent to 'v1+v2+v3+v1:v2+v1:v3+v2:v3+v1:v2:v3'

Formula String Reserved Names:

The following are reserved and should not be used as a variable name:

• mu = used to indicate the intercept
• mv = used to indicate a term for estimating missing values
• units = forms a factor with a level for each experimental unit, i.e. a factor taking the values 1 to n, where n is the number of data rows
• trait = the multivariate counterpart of mu

set up predict arguments

Arguments:

• classify: Specifies the variables that define the margins of the multiway table to be predicted. Multiway tables are specified by forming an interaction type term from the classifying variables, that is, separating the variable names with the ":" operator.
• present: Specifies which variables to include in the present averaging set. The present set is used when averaging is to be based only on cells with data. The present set may include variables in the classify set but not those in the average set.
• ignore: Specifies which variables to ignore in forming the predictions.
• use: Specifies which variables to add to the prediction model after the default rules have been invoked.
• exclude: Specifies which variables to exclude in the prediction process. That is, the prediction model includes all fitted model terms not in the exclude list.
• only: Specifies which variables (only) form the prediction model, that is, the default rules are not invoked.
• associate: A one-sided formula specifying terms in up to two independent nested hierarchies. The factors in each hierarchy are written as a compound term separated by the ":" operator and in left-to-right outer to inner nesting order. Nested hierarchies are separated by the "+" operator; only one "+" operator is currently permitted, giving a maximum of two associate lists.
• average: Specifies which variables to include in the averaging set. If a dictionary is supplied, the keys should be the margins of the classifying table and the associated values the weights to use in the averaging process. If a string or list is supplied, the values should be the margins of the classifying table and equal weights will be used.
• parallel: If set to True then all classify variables are expanded in parallel. Otherwise, if not None, then the a list of the classify variables whose levels are to be taken in parallel.
• weights: prediction weights applied to the averaging set (parallel to the classify margins).
• levels: Specifies the levels at which predictions are required. If a dictionary is supplied, the keys should be the margins of the classifying table and the associated values the levels at which predictions are required. If a string or list is supplied, the values should be the margins of the classifying table and factors are predicted at each level, simple covariates are predicted at their overall mean and covariates used as a basis for splines or orthogonal polynomials are predicted at their design points.
• options: Optional extra arguments.

set up wald arguments

Arguments:

• den_df: Controls the suppression (None) or the use of a particular algorithmic method: "numeric" for numerical derivatives, or "algebraic" for algebraic derivatives. If a value of "default" is supplied, then the method is chosen depending on the problem size.
• ss_type: Controls the tests within the Wald statistics table. These can be tested sequentially ("incremental") or conditional on all the other terms ("conditional").
• f_test: Allows the test reported in the F-con column of the Wald F statistic table to be controlled. The supplied string has the form: " | " where the "" and "" should be specified using the standard model specification syntax (see asreml.asreml_class.ASReml.setup_model for details). It generates a Wald F statistic for each model term in "" which tests its contributions after all other terms in "" and "", conditional on all terms that appear in the sparse equations.

register a monitor function

Arguments:

• monfn: A monitor function, with prototype:

         def monfn(info: dict) -> int

         Parameters:
           info: dictionary containing iteration information
                 JSN_OTAB_TRACE_ITERATION: iteration number
                 JSN_OTAB_TRACE_LOGL: the log likelihood
                 JSN_OTAB_TRACE_SIGMA2: sigma^2
                 JSN_OTAB_TRACE_DF: degrees of freedom
                 JSN_OTAB_TRACE_TIME: the elapsed time (in seconds) since the
                   last iteration
         Return Value:
           if set to a value > 0, then the model fit will abort
           if set to a value < 0, then the model fit will finish cleanly
           after performing one final iteration
           if set to 0, then the model fit will continue as normal

fit the model

Arguments:

• process_stage: the stage of the fitting process to stop after, valid values are: "all" (default) and "preprocess"
• initial_values: dictionary holding initial value information, each key in the dictionary should be a variance component label and each value in the dictionary should itself be a dictionary with one or both keys "value" and "constraint" holding the initial value to use and the constraint code. Valid constraint codes are:
  • "P" = in the space, attempts to keep the parameter in the theoretical parameter space
  • "U" = unrestricted
  • "F" = fixed see also asreml.asreml_class.initial_values

return a summary

Arguments:

• display: if True then the summary table will be printed, if set to None it takes its value from a global option

return the trace

Arguments:

• display: if True then the trace will be printed, if set to None it takes its value from a global option

return the coefficients

Arguments:

• display: if True then the coefficients will be printed, if set to None it takes its value from a global option

return the fitted values

Arguments:

• display: if True then the fitted values will be printed, if set to None it takes its value from a global option

return the residuals

Arguments:

• display: if True then the residuals will be printed, if set to None it takes its value from a global option

return the variance components

Arguments:

• display: if True then the variance components will be printed, if set to None it takes its value from a global option

return a wald aov table

Arguments:

• display: if True then the wald table will be printed, if set to None it takes its value from a global option
• return_all: if True then everything is returned, otherwise only the body of the table is, if set to None it takes its value from a global option

return predictions

Arguments:

• display: if True then the prediction table will be printed, if set to None it takes its value from a global option
• return_all: if True then everything is returned, otherwise only the body of the table is, if set to None it takes its value from a global option

Returns:

1. A dataframe containing the predicted values, or
2. A SimpleNamespace containing the predicted values and other requested output (like variance matrix etc), or
3. A list with elements of the same types as (1) or (2), with each element of the list corresponding to a different predict statement

set up a vpredict info

Arguments:

• vpredict: formula string or dictionary with labels and formula strings

return a vpredict table

Arguments:

• display: if True then the vpredict table will be printed,
• if set to None it takes its value from a global option

return the initial values

Arguments:

• display: if True then the initial value table will be printed, if set to None it takes its value from a global option

Returns:

A dictionary suitable to use as inputting into the fitting routine to alter initial values see asreml.asreml_class.fit for more information

return the design matrix

Arguments:

• display: if True then the design matrix will be printed, if set to None it takes its value from a global option

return a named table This function is for returning additional output that is rarely required and hence does not have its own specific method

Arguments:

• name: the name of the table to return

return a final status flag and optionally a text message

Arguments:

• return_msg: if True then the text of the status message is returned
• display: if True then the status message will be printed if set to None it takes its value from a global option

Return Value:

either status or (status, msg)

status: status flag,

• 0 = Something went wrong, additional information will be reported via the error handling mechanism and in msg (if returned)
• 1 = The action finished OK (i.e. if fitting model the Log Likelihood converged etc)
• 2 = The action was conditionally OK (for example, this value can be returned if, when fitting a model, the Log Likelihood converged, but the parameters did not etc). Additional information will be reported via the error handling mechanism and in msg (if returned).

msg: status message

Depending on the reason for non-convergence, an Error or Warning message may also have been generated