% -*- texinfo -*-
% @deftypefn {Function File} {[@var{theta}, @var{beta}, @var{dev}, @var{dl}, @var{d2l}, @var{p}] =} logistic_regression (@var{y}, @var{x}, @var{print}, @var{theta}, @var{beta})
% Perform ordinal logistic regression.
%
% Suppose @var{y} takes values in @var{k} ordered categories, and let
% @code{gamma_i (@var{x})} be the cumulative probability that @var{y}
% falls in one of the first @var{i} categories given the covariate
% @var{x}. Then
%
% @example
% [theta, beta] = logistic_regression (y, x)
% @end example
%
% @noindent
% fits the model
%
% @example
% logit (gamma_i (x)) = theta_i - beta' * x, i = 1 @dots{} k-1
% @end example
%
% The number of ordinal categories, @var{k}, is taken to be the number
% of distinct values of @code{round (@var{y})}. If @var{k} equals 2,
% @var{y} is binary and the model is ordinary logistic regression. The
% matrix @var{x} is assumed to have full column rank.
%
% Given @var{y} only, @code{theta = logistic_regression (y)}
% fits the model with baseline logit odds only.
%
% The full form is
%
% @example
% @group
% [theta, beta, dev, dl, d2l, gamma]
% = logistic_regression (y, x, print, theta, beta)
% @end group
% @end example
%
% @noindent
% in which all output arguments and all input arguments except @var{y}
% are optional.
%
% Setting @var{print} to 1 requests summary information about the fitted
% model to be displayed. Setting @var{print} to 2 requests information
% about convergence at each iteration. Other values request no
% information to be displayed. The input arguments @var{theta} and
% @var{beta} give initial estimates for @var{theta} and @var{beta}.
%
% The returned value @var{dev} holds minus twice the log-likelihood.
%
% The returned values @var{dl} and @var{d2l} are the vector of first
% and the matrix of second derivatives of the log-likelihood with
% respect to @var{theta} and @var{beta}.
%
% @var{p} holds estimates for the conditional distribution of @var{y}
% given @var{x}.
% @end deftypefn