@param returnValue numeric value giving the value for which the risk ratio should be calculated, where the resulting period will be the average number of blocks until the value is exceeded and the probability the probability of exceeding the value in any single block.
@param y1 numpy array of exceedance values for the first dataset (values of the outcome variable above the threshold). For better optimization performance, it is recommended that the ‘y’ have magnitude around one (see ‘Details’), for which one can use ‘scaling1’.
@param y2 numpy array of exceedance values for the second dataset (values of the outcome variable above the threshold).
@param x1 numpy array or pandas data frame with columns corresponding to covariate/predictor/feature variables and each row containing the values of the variable for a block (e.g., often a year with climate data) for the first dataset. The number of rows must equal the number of blocks.
@param x2 analogous to ‘x1’ but for the second dataset
@param threshold1 a single numeric value for constant threshold or a numpy array with length equal to the number of blocks, indicating the threshold for each block for the first dataset.
@param threshold2 analogous to ‘threshold1’ but for the second dataset
@param locationFun1 numpy array of either character strings or indices describing a linear model (i.e., regression function) for the location parameter using columns from ‘x1’ for the first dataset. ‘x1’ must be supplied if this is anything other than ‘None’.
@param locationFun2 numpy array of either character strings or indices describing a linear model (i.e., regression function) for the location parameter using columns from ‘x2’ for the second dataset. ‘x2’ must be supplied if this is anything other than ‘None’.
@param scaleFun1 numpy array of either character strings or indices describing a linear model (i.e., regression function) for the (potentially transformed) scale parameter using columns from ‘x1’ for the first dataset.  ‘x1’ must be supplied if this is anything other than ‘None’. ‘logscale1’ controls whether this determines the log of the scale or the scale directly.
@param scaleFun2 numpy array of either character strings or indices describing a linear model (i.e., regression function) for the (potentially transformed) scale parameter using columns from ‘x2’ for the second dataset.  ‘x2’ must be supplied if this is anything other than ‘None’. ‘logscale2’ controls whether this determines the log of the scale or the scale directly.
@param shapeFun1 numpy array of either character strings or indices describing a linear model (i.e., regression function) for the shape parameter using columns from ‘x1’ for the first dataset.  ‘x1’ must be supplied if this is anything other than ‘None’.
@param shapeFun2 numpy array of either character strings or indices describing a linear model (i.e., regression function) for the shape parameter using columns from ‘x2’ for the first dataset.  ‘x2’ must be supplied if this is anything other than ‘None’.
@param nBlocks1 number of blocks (e.g., a block will often be a year with climate data) in first dataset; note this value determines the interpretation of return values/periods/probabilities; see ‘returnPeriod’ and ‘returnValue’.
@param nBlocks2 number of blocks (e.g., a block will often be a year with climate data) in second dataset; note this value determines the interpretation of return values/periods/probabilities; see ‘returnPeriod’ and ‘returnValue’.
@param blockIndex1 numpy array providing the index of the block corresponding to each element of ‘y1’. Used only when ‘x1’ is provided to match exceedances to the covariate/predictor/feature value for the exceedance or when using bootstrapping with the resampling based on blocks based on the ‘by’ element of ‘bootControl’. If ‘firstBlock1’ is not equal to one, then ‘blockIndex1’ need not have one as its smallest possible value.
@param blockIndex2 numpy array providing the index of the block corresponding to each element of ‘y2’. Analogous to ‘blockIndex1’.
@param firstBlock1 single numeric value indicating the numeric value of the first possible block of ‘blockIndex1’. For example the values in ‘blockIndex1’ might indicate the year of each exceedance with the first year of data being 1969, in which case ‘firstBlock1’ would be 1969. Note that the first block may not have any exceedances so it may not be represented in ‘blockIndex1’. Used only to adjust ‘blockIndex1’ so that the block indices start at one and therefore correspond to the rows of ‘x1’.
@param firstBlock2 single numeric value indicating the numeric value of the first possible block of ‘blockIndex2’. Analogous to ‘firstBlock1’.
@param index1 (optional) numpy array providing the integer-valued index (e.g., julian day for daily climate data) corresponding to each element of ‘y1’. For example if there are 10 original observations and the third, fourth, and seventh values are exceedances, then ‘index1’ would be the vector 3,4,7. Used only when ‘declustering’ is provided to determine which exceedances occur sequentially or within a contiguous set of values of a given length. The actual values are arbitrary; only the lags between the values are used.
@param index2 (optional) numpy array providing the integer-valued index (e.g., julian day for daily climate data) corresponding to each element of ‘y2’. Analogous to ‘index1’.
@param nReplicates1 numeric value indicating the number of replicates for the first dataset.
@param nReplicates2 numeric value indicating the number of replicates for the second dataset.
@param replicateIndex1 numpy array providing the index of the replicate corresponding to each element of ‘y1’. Used for three purposes: (1) when using bootstrapping with the resampling based on replicates based on the ‘by’ element of ‘bootControl’, (2) to avoid treating values in different replicates as potentially being sequential or within a short interval when removing values based on ‘declustering’, and (3) to match outcomes to ‘weights’ or ‘proportionMissing’ when either vary by replicate.  
@param replicateIndex2 numpy array providing the index of the replicate corresponding to each element of ‘y2’. Analogous to ‘replicateIndex1’.
@param weights1 numpy array providing the weights by block for the first dataset. When there is only one replicate or the weights do not vary by replicate, a one-dimensional array of length equal to the number of blocks. When weights vary by replicate, a two-dimensional array with rows corresponding to blocks and columns to replicates. Likelihood contribution of each block is multiplied by the corresponding weight. 
@param weights2 numpy array providing the weights by block for the second dataset. Analogous to ‘weights1’.
@param proportionMissing1 a numeric value or numpy array indicating the proportion of missing values in the original first dataset before exceedances were selected. When the proportion missing is the same for all blocks and replicates, a single value. When there is only one replicate or the weights do not vary by replicate, a one-dimensional array of length equal to the number of blocks. When weights vary by replicate, a two-dimensional array with rows corresponding to blocks and columns to replicates.
@param proportionMissing2 a numeric value or numpy array indicating the proportion of missing values in the original second dataset before exceedances were selected. Analogous to ‘proportionMissing1’.
@param xNew1 object of the same form as ‘x1’, providing covariate/predictor/feature values for which log risk ratios are desired.
@param xNew2 object of the same form as ‘x2’, providing covariate/predictor/feature values for which log risk ratios are desired. Must provide the same number of covariate sets as ‘xNew1’ as the risk ratio is based on contrasting return probabilities under ‘xNew1’ and ‘xNew2’.
@param declustering one of ‘None’, ‘'noruns'’, or a number. If ‘'noruns'’ is specified, only the maximum (or minimum if ‘upperTail = False’) value within a set of exceedances corresponding to successive indices is included. If a number, this should indicate the size of the interval (which will be used with the ‘index’ argument) within which to allow only the largest (or smallest if ‘upperTail = False’) value.
@param upperTail boolean indicating whether one is working with exceedances over a high threshold (‘True’) or exceedances under a low threshold (‘False’); in the latter case, the function works with the negative of the values and the threshold, changing the sign of the resulting location parameters.
@param scaling1 positive-valued scalar used to scale the data values of the first dataset for more robust optimization performance. When multiplied by the values, it should produce values with magnitude around 1.
@param scaling2 positive-valued scalar used to scale the data values of the second dataset for more robust optimization performance. When multiplied by the values, it should produce values with magnitude around 1.
@param ciLevel statistical confidence level for confidence intervals; in repeated experimentation, this proportion of confidence intervals should contain the true risk ratio. Note that if only one endpoint of the resulting interval is used, for example the lower bound, then the effective confidence level increases by half of one minus ‘ciLevel’. For example, a two-sided 0.90 confidence interval corresponds to a one-sided 0.95 confidence interval.
@param ciType numpy string or numpy array of strings indicating which type of confidence intervals to compute. See ‘Details’.
@param bootSE boolean indicating whether to use the bootstrap to estimate the standard error of the risk ratio.
@param bootControl dictionary of control parameters for the bootstrapping, used only when at least one bootstrap confidence interval is requested via ‘ciType’. See ‘Details’.
@param lrtControl dictionary containing a single component, a numpy array named ‘bounds’, which sets the range inside which the algorithm searches for the endpoints of the likelihood ratio-based confidence interval. This avoids numerical issues with endpoints converging to zero and infinity. If an endpoint is not found within the interval, it is set to ‘nan’. Used only when ‘'lrt'’ is one of the ‘ciType’ values.
@param optimArgs a dictionary with named components matching exactly any arguments that the user wishes to pass to R's ‘optim’ function. See ‘help(optim)’ in R for details. Of particular note, ‘'method'’ can be used to choose the optimization method used for maximizing the log-likelihood to fit the model (e.g., ‘'method'’ could be 'BFGS' instead of the default 'Nelder-Mead'). To specify the ‘control’ argument, use ‘optimControl’ rather than including ‘control’ here.
@param optimControl a dictionary with named components matching exactly any elements that the user wishes to pass as the ‘control’ argument to R's ‘optim’ function. For example, ‘control={'maxit': VALUE)’ for a user-specified VALUE can be used to increase the number of iterations if the optimization is converging slowly.
@param initial1 a dictionary with components named ‘'location'’, ‘'scale'’, and ‘'shape'’ providing initial parameter values, intended for use in speeding up or enabling optimization when the default initial values are resulting in failure of the optimization; note that use of ‘scaling’, ‘logScale’ and ‘.normalizeX = True’ cause numerical changes in some of the parameters. For example with ‘logScale1 = True’, initial value(s) for ‘'scale'’ should be specified on the log scale.
@param initial2 a dictionary of initial parameter values for the second dataset, analogous to ‘initial1’.
@param logScale1 boolean indicating whether optimization for the scale parameter should be done on the log scale for the first dataset. By default this is ‘False’ when the scale is not a function of covariates and ‘True’ when the scale is a function of covariates (to ensure the scale is positive regardless of the regression coefficients). 
@param logScale2 boolean indicating whether optimization for the scale parameter should be done on the log scale for the second dataset. By default this is ‘False’ when the scale is not a function of covariates and ‘True’ when the scale is a function of covariates (to ensure the scale is positive regardless of the regression coefficients). 
@param getReturnCalcs boolean indicating whether to return the estimated return values/probabilities/periods from the fitted models. 
@param getParams boolean indicating whether to return the fitted parameter values and their standard errors for the fitted models; WARNING: parameter values for models with covariates for the scale parameter must interpreted based on the value of ‘logScale’.
@param getFit boolean indicating whether to return the full fitted models (potentially useful for model evaluation and for understanding optimization problems); note that estimated parameters in the fit object for nonstationary models will not generally match the MLE provided when ‘getParams’ is ‘True’ because covariates are normalized before fitting and the fit object is based on the normalized covariates. Similarly, parameters will not match if ‘scaling’ is not 1.
