fstats_regression

Uses

- iso_fortran_env
- fstats_t_distribution
- fstats_descriptive_statistics
- fstats_special_functions
- fstats_distributions
- fstats_errors
- fstats_hypothesis
- linalg
- ieee_arithmetic
- blas

Interfaces

interface

public subroutine iteration_update(iter, funvals, resid, params, step)

Defines a routine for providing updates about an iteration process.

Arguments

Type	Intent	Attributes		Name
integer(kind=int32),	intent(in)		::	iter	The current iteration number.
real(kind=real64),	intent(in),	dimension(:)	::	funvals	The function values.
real(kind=real64),	intent(in),	dimension(:)	::	resid	The residuals.
real(kind=real64),	intent(in),	dimension(:)	::	params	The model parameters.
real(kind=real64),	intent(in),	dimension(:)	::	step	Step sizes for each parameter.

interface

public subroutine regression_function(xdata, params, f, stop, args)

Defines the interface of a subroutine computing the function values at each of the N data points as part of a regression analysis.

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=real64),	intent(in),		dimension(:)	::	xdata	An N-element array containing the N independent data points.
real(kind=real64),	intent(in),		dimension(:)	::	params	An M-element array containing the M model parameters.
real(kind=real64),	intent(out),		dimension(:)	::	f	An N-element array where the results of the N function evaluations will be written.
logical,	intent(out)			::	stop	A mechanism to force a stop to the iteration process. If set to true, the iteration process will terminate. If set to false, the iteration process will continue along as normal.
class(*),	intent(inout),	optional		::	args	An optional argument allowing the passing in/out of data.

Derived Types

type, public :: convergence_info

Provides information regarding convergence status.

Components

Type	Visibility		Name		Initial
logical,	public	::	converge_on_gradient			True if convergence on the gradient was achieved; else, false.
logical,	public	::	converge_on_residual_parameter			True if convergence on the residual error parameter was achieved; else, false.
logical,	public	::	converge_on_solution_change			True if convergence on the change in solution was achieved; else, false.
real(kind=real64),	public	::	covariance_condition_number	=	0.0d0	Condition number of that Jacobian; infinity indicates rank deficiency.
integer(kind=int32),	public	::	covariance_rank	=	0	Numerical rank of the final weighted Jacobian when covariance is requested.
integer(kind=int32),	public	::	function_evaluation_count			The function evaluation count.
real(kind=real64),	public	::	gradient_value			The value of the gradient test parameter.
integer(kind=int32),	public	::	iteration_count			The iteration count.
logical,	public	::	reach_function_evaluation_limit			True if the solution did not converge in the allowed number of function evaluations.
logical,	public	::	reach_iteration_limit			True if the solution did not converge in the allowed number of iterations.
real(kind=real64),	public	::	residual_value			The value of the residual error parameter.
real(kind=real64),	public	::	solution_change_value			The value of the change in solution parameter.
logical,	public	::	user_requested_stop			True if the user requested the stop; else, false.

type, public :: iteration_controls

Provides a collection of iteration control parameters.

Components

Type	Visibility		Name
real(kind=real64),	public	::	change_in_solution_tolerance	Defines a tolerance on the change in parameter values.
real(kind=real64),	public	::	gradient_tolerance	Defines a tolerance on the gradient of the fitted function.
real(kind=real64),	public	::	iteration_improvement_tolerance	Defines a tolerance to ensure adequate improvement on each iteration.
integer(kind=int32),	public	::	max_function_evaluations	Defines the maximum number of function evaluations allowed.
integer(kind=int32),	public	::	max_iteration_between_updates	Defines how many iterations can pass before a re-evaluation of the Jacobian matrix is forced.
integer(kind=int32),	public	::	max_iteration_count	Defines the maximum number of iterations allowed.
real(kind=real64),	public	::	residual_tolerance	Defines a tolerance on the metric associated with the residual error.

Type-Bound Procedures

procedure, public :: set_to_default => lm_set_default_tolerances

type, public :: regression_statistics

A container for regression-related statistical information.

Components

Type	Visibility		Name
real(kind=real64),	public	::	confidence_interval	The confidence interval for the parameter at the level determined by the regression process. Read more…
real(kind=real64),	public	::	probability	The probability that the coefficient is not statistically important. A statistically important coefficient will have a low probability (p-value), typically 0.05 or lower; however, a p-value of up to ~0.2 may be acceptable dependent upon the problem. Typically any p-value larger than ~0.2 indicates the parameter is not statistically important for the model. Read more…
real(kind=real64),	public	::	standard_error	The standard error for the model coefficient. Read more…
real(kind=real64),	public	::	t_statistic	The T-statistic for the model coefficient. Read more…

Functions

public pure function adjusted_r_squared(p, x, xm) result(rst)

Computes the adjusted R-squared value for a data set.

Arguments

Type	Intent		Name
integer(kind=int32),	intent(in)	::	p	The number of variables.
real(kind=real64),	intent(in)	::	x(:)	An N-element array containing the dependent variables from the data set.
real(kind=real64),	intent(in)	::	xm(:)	An N-element array containing the corresponding modeled values.

Return Value real(kind=real64)

The result.

public function calculate_regression_statistics(resid, params, c, alpha) result(rst)

Computes statistics for the quality of fit for a regression model.

Arguments

Type	Intent	Optional		Name
real(kind=real64),	intent(in)		::	resid(:)	An M-element array containing the model residual errors.
real(kind=real64),	intent(in)		::	params(:)	An N-element array containing the model parameters.
real(kind=real64),	intent(in)		::	c(:,:)	The N-by-N covariance matrix.
real(kind=real64),	intent(in),	optional	::	alpha	The significance level at which to evaluate the confidence intervals. The default value is 0.05 such that a 95% confidence interval is calculated.

Return Value type(regression_statistics), allocatable, (:)

A regression_statistics object containing the analysis results.

public pure function correlation(x, y) result(rst)

Computes the sample correlation coefficient (an estimate to the population Pearson correlation) as follows.

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=real64),	intent(in),		dimension(:)	::	x	The first N-element data set.
real(kind=real64),	intent(in),		dimension(size(x))	::	y	The second N-element data set.

Return Value real(kind=real64)

Correlation coefficient on [-1, 1]; constant, nonfinite, or undersized data give NaN. Scaled centering avoids overflowing moments.

public pure function covariance_matrix(x) result(c)

Computes the covariance matrix $C$ where $C = \left( X^{T} X \right)^{-1}$ and $X$ is computed by design_matrix. Uses an SVD of X, without forming X**T * X. Rank-deficient inputs give the Moore-Penrose covariance; use regression_covariance for rank diagnostics.

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=real64),	intent(in)			::	x(:,:)	An M-by-N matrix containing the formatted independent data matrix $X$ as computed by design_matrix.

Return Value real(kind=real64), allocatable, (:,:)

The N-by-N covariance matrix.

public pure function design_matrix(order, intercept, x) result(c)

Computes the design matrix $X$ for the linear least-squares regression problem of $X \beta = y$ , where $X$ is the matrix computed here, $\beta$ is the vector of coefficients to be determined, and $y$ is the vector of measured dependent variables.

Arguments

Type	Intent		Name
integer(kind=int32),	intent(in)	::	order	The order of the equation to fit. This value must be at least one (linear equation), but can be higher as desired.
logical,	intent(in)	::	intercept	Set to true if the intercept is being computed as part of the regression; else, false.
real(kind=real64),	intent(in)	::	x(:)	An N-element array containing the independent variable measurement points.

Return Value real(kind=real64), allocatable, (:,:)

An N-by-K matrix where the results will be written. K must equal order + 1 in the event intercept is true; however, if intercept is false, K must equal order.

public pure function r_squared(x, xm) result(rst)

Computes the R-squared value for a data set.

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=real64),	intent(in)			::	x(:)	An N-element array containing the dependent variables from the data set.
real(kind=real64),	intent(in)			::	xm(:)	An N-element array containing the corresponding modeled values.

Return Value real(kind=real64)

The result.

Subroutines

public subroutine jacobian(fun, xdata, params, jac, stop, f0, f1, step, args)

Computes the Jacobian matrix for a nonlinear regression problem.

Arguments

Type	Intent	Optional	Attributes		Name
procedure(regression_function),	intent(in),		pointer	::	fun	A pointer to the regression_function to evaluate.
real(kind=real64),	intent(in)			::	xdata(:)	The M-element array containing x-coordinate data.
real(kind=real64),	intent(in)			::	params(:)	The N-element array containing the model parameters.
real(kind=real64),	intent(out)			::	jac(:,:)	The M-by-N matrix where the Jacobian will be written.
logical,	intent(out)			::	stop	A value that the user can set in fun forcing the evaluation process to stop prior to completion.
real(kind=real64),	intent(in),	optional,	target	::	f0(:)	An optional M-element array containing the model values using the current parameters as defined in m. This input can be used to prevent the routine from performing a function evaluation at the model parameter state defined in params.
real(kind=real64),	intent(out),	optional,	target	::	f1(:)	An optional M-element workspace array used for function evaluations.
real(kind=real64),	intent(in),	optional		::	step	The differentiation step size. The default is the square root of machine precision.
class(*),	intent(inout),	optional		::	args	An optional argument allowing the passing in/out of data.

public pure subroutine regression_covariance(x, c, rank, condition_number)

Computes the unscaled regression covariance using an SVD of X itself. Singular directions below MAX(M, N) * EPSILON * largest singular value are discarded, giving the Moore-Penrose covariance on identifiable directions. Rank-deficient fits require care: a zero pseudocovariance along a discarded direction does not imply that the corresponding parameter is known exactly.

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=real64),	intent(in),		dimension(:,:)	::	x	M-by-N design matrix, or a Jacobian whose rows include sqrt(weights).
real(kind=real64),	intent(out),		allocatable, dimension(:,:)	::	c	N-by-N covariance before residual-variance scaling. Nonfinite X gives NaNs.
integer(kind=int32),	intent(out),	optional		::	rank	Number of retained singular directions; zero for empty/invalid input.
real(kind=real64),	intent(out),	optional		::	condition_number	Condition number of X; +infinity for rank deficiency, NaN for invalid X.

fstats_regression Module

Contents

Interfaces

Derived Types

Functions

Subroutines

Uses

Interfaces

interface

public subroutine iteration_update(iter, funvals, resid, params, step)

Arguments

interface

public subroutine regression_function(xdata, params, f, stop, args)

Arguments

Derived Types

type, public :: convergence_info

Components

type, public :: iteration_controls

Components

Type-Bound Procedures

type, public :: regression_statistics

Components

Functions

public pure function adjusted_r_squared(p, x, xm) result(rst)

Arguments

Return Value real(kind=real64)

public function calculate_regression_statistics(resid, params, c, alpha) result(rst)

Arguments

Return Value type(regression_statistics), allocatable, (:)

public pure function correlation(x, y) result(rst)

Arguments

Return Value real(kind=real64)

public pure function covariance_matrix(x) result(c)

Arguments

Return Value real(kind=real64), allocatable, (:,:)

public pure function design_matrix(order, intercept, x) result(c)

Arguments

Return Value real(kind=real64), allocatable, (:,:)

public pure function r_squared(x, xm) result(rst)

Arguments

Return Value real(kind=real64)

Subroutines

public subroutine jacobian(fun, xdata, params, jac, stop, f0, f1, step, args)

Arguments

public pure subroutine regression_covariance(x, c, rank, condition_number)

Arguments