phit

Data & Workflow

Statistics, Modeling, & Visualization

Model functions

On this page
Examples

Linear and generalized linear models from a formula or a numeric design. Result keys, inference, and algorithms are detailed in Model contracts; formula syntax in Model formulas.

Formula models

fit_ols()

Fits a linear model from a formula, like R’s lm().

  • Builds the model matrix from named columns and fits by least squares, or by weighted least squares when weights is given, as lm(weights = ) does.
  • offset() terms in the formula are added to the linear predictor.
  • Factor levels left unused after missing rows are dropped are removed, as lm() does.
  • A rank-deficient design throws instead of returning R’s NA coefficients.
  • Rows with null or NAN in a variable the formula uses are dropped with one warning; missing: 'raise' rejects them instead. retained_rows and dropped_rows give the original row positions.
Phit\fit_ols(    string $formula,    array|object $data,    string $missing = 'drop',    array|string|null $weights = NULL,): LinearFit
Parameter Type Default Description
$formula string required R formula, such as 'y ~ log(x) + f * z + offset(log(t))'
$data array\|object required Named columns or factor descriptors; objects use toModelData(), else toColumns()
$missing string 'drop' 'drop' removes rows with null or NAN in any variable the model uses and warns once; 'raise' rejects them
$weights array\|string\|null NULL Positive prior weights aligned with the original rows, or a column name

Returns

LinearFit A fit object, read like this array:array{  model: 'linear'|'generalized_linear'|'mixed_gaussian'|'mixed_logistic',  coefficients: list<float>,  covariance: list<list<float>>,  std_errors: list<float>,  p_values: list<float>,  conf_int: list<array{float,float}>,  fitted: list<float>,  residuals: list<float>,  log_likelihood: float,  df_residual: int,  diagnostics: array{converged:bool,solver:string,warnings:list<string>,iterations?:int,evaluations?:int,gradient_max?:float,boundary?:bool,singular?:bool},  n_input: int,  n_observations: int,  n_dropped: int,  retained_rows: list<int>,  dropped_rows: list<int>,  t_statistics: list<float>,  rss: float,  residual_variance: float,  sigma: float,  r_squared: float,  adj_r_squared: float,  formula: string,  response: string,  columns: list<string>,  terms: list<string>,  assign: list<int>,  intercept: bool,  named: array<string,float>,  predvars: array{levels:array<string,list<string>>,poly:array<string,array{alpha:list<float>,norm2:list<float>}>},}

Errors Exception: a code from 1001 to 1008 for an input or statistical error; 1007 for an unsupported function, family, or random term.

See also Details · Example

fit_generalized_linear()

Fits a generalized linear model from a formula, like R’s glm().

  • Families and links: gaussian with identity, binomial with logit or probit, and poisson with log. An empty link selects the canonical link.
  • A binomial response can be 0/1 numbers, booleans, a factor or string column (the first level is failure), proportions with integer trial weights, or cbind(successes, failures).
  • Rows with null or NAN in a variable the formula uses are dropped with one warning; missing: 'raise' rejects them instead. retained_rows and dropped_rows give the original row positions.
Phit\fit_generalized_linear(    string $formula,    array|object $data,    string $family = 'gaussian',    string $link = '',    string $missing = 'drop',    array|string|null $weights = NULL,): GeneralizedLinearFit
Parameter Type Default Description
$formula string required R formula, such as 'y ~ log(x) + f * z + offset(log(t))'
$data array\|object required Named columns or factor descriptors; objects use toModelData(), else toColumns()
$family string 'gaussian' 'gaussian', 'binomial', or 'poisson'
$link string '' '' (canonical), 'identity', 'logit', 'probit', or 'log'
$missing string 'drop' 'drop' removes rows with null or NAN in any variable the model uses and warns once; 'raise' rejects them
$weights array\|string\|null NULL Positive prior weights aligned with the original rows, or a column name

Returns

GeneralizedLinearFit A fit object, read like this array:array{  model: 'linear'|'generalized_linear'|'mixed_gaussian'|'mixed_logistic',  coefficients: list<float>,  covariance: list<list<float>>,  std_errors: list<float>,  p_values: list<float>,  conf_int: list<array{float,float}>,  fitted: list<float>,  residuals: list<float>,  log_likelihood: float,  df_residual: int,  diagnostics: array{converged:bool,solver:string,warnings:list<string>,iterations?:int,evaluations?:int,gradient_max?:float,boundary?:bool,singular?:bool},  n_input: int,  n_observations: int,  n_dropped: int,  retained_rows: list<int>,  dropped_rows: list<int>,  z_statistics: list<float>,  deviance: float,  null_deviance: float,  aic: float,  iterations: int,  converged: bool,  family: string,  link: string,  formula: string,  response: string,  columns: list<string>,  terms: list<string>,  assign: list<int>,  intercept: bool,  named: array<string,float>,  predvars: array{levels:array<string,list<string>>,poly:array<string,array{alpha:list<float>,norm2:list<float>}>},  t_statistics?: list<float>,  rss?: float,  residual_variance?: float,  sigma?: float,  r_squared?: float,  adj_r_squared?: float,}

Errors Exception: a code from 1001 to 1008 for an input or statistical error; 1007 for an unsupported function, family, or random term.

See also Details · Example

model_matrix()

Builds the numeric design of a formula over named columns, like R’s model.matrix().

  • Factors use treatment contrasts with the first level as the reference; ordered factors use contr.poly.
  • Column names, term order, inline transforms, offset(), and random-effect bars follow R.
  • Unused factor levels are kept, as in model.matrix(), and x includes the (Intercept) column when present.
  • Rows with null or NAN in a variable the formula uses are dropped with one warning; missing: 'raise' rejects them instead. retained_rows and dropped_rows give the original row positions.
Phit\model_matrix(    string $formula,    array|object $data,    string $missing = 'drop',): array
Parameter Type Default Description
$formula string required R formula, such as 'y ~ log(x) + f * z + offset(log(t))'
$data array\|object required Named columns or factor descriptors; objects use toModelData(), else toColumns()
$missing string 'drop' 'drop' removes rows with null or NAN in any variable the model uses and warns once; 'raise' rejects them

Returns

array{  y: list<float>|list<array{float,float}>|null,  response_levels?: list<string>,  x: list<list<float>>,  columns: list<string>,  intercept: bool,  terms: list<string>,  assign: list<int>,  formula: string,  response: string|null,  offset: list<float>|null,  random: list<array{label:string,group:string,columns:list<string>,correlated:bool,z:list<list<float>>,groups:list<int|string>}>,  n_input: int,  n_observations: int,  n_dropped: int,  retained_rows: list<int>,  dropped_rows: list<int>,}

Errors Exception: a code from 1001 to 1008 for an input or statistical error; 1007 for an unsupported function, family, or random term.

See also Details

predict()

Predicts new data from a fit_ols(), fit_generalized_linear(), fit_mixed_gaussian(), or fit_mixed_logistic() result, like R’s predict().

  • The fit’s formula is rebuilt over newdata with the fitted factor levels and poly() basis, from the fit’s predvars key. A level the fit never saw throws.
  • A row with a missing predictor predicts null and is listed in missing_rows.
  • type: 'response' applies the inverse link, and seFit then uses the delta method on that scale.
  • interval: 'confidence' or 'prediction' adds lower and upper for fit_ols() fits, using t with df_residual.
  • Mixed fits add the random effects of known groups. random: false gives population predictions, and allowNewLevels predicts unseen groups at the population level.
  • GLM standard errors use the covariance at the final coefficients, which differs slightly from R’s predict.glm().
Phit\predict(    Fit|array $fit,    array|object $newdata,    string $type = 'link',    bool $seFit = false,    string $interval = 'none',    float $level = 0.95,    bool $random = true,    bool $allowNewLevels = false,): array
Parameter Type Default Description
$fit Fit\|array required A formula fit, or its toArray() array, with the keys formula, coefficients, covariance, columns, and predvars
$newdata array\|object required Named columns, as for the fit; the response may be absent
$type string 'link' 'link' (linear predictor) or 'response'
$seFit bool false Also return standard errors of the predictions; fixed-effect fits only
$interval string 'none' 'none', 'confidence', or 'prediction'
$level float 0.95 Confidence level of the interval
$random bool true Mixed fits: include the random effects of known groups, as lme4’s re.form = NULL; false predicts at the population level, as re.form = NA
$allowNewLevels bool false Predict a group the fit never saw at the population level instead of throwing

Returns

array{  fit: list<float|null>,  se_fit?: list<float|null>,  df?: int,  residual_scale?: float,  lower?: list<float|null>,  upper?: list<float|null>,  level: float|null,  n_input: int,  n_predicted: int,  missing_rows: list<int>,}

Errors Exception: code 1001 for invalid input, a malformed fit, or a new factor level, or 1007 for an unsupported option.

See also Details · Example

Matrix models

fit_ols_matrix()

Fits a linear model by least squares on a numeric design, like R’s lm.fit() with the full summary.

  • weights gives weighted least squares, as lm(weights = ) does.
  • An intercept column is prepended unless intercept is false, in which case x is used exactly.
  • Rows with null or NAN in x, y, or another aligned input are dropped with one warning; missing: 'raise' rejects them instead. retained_rows and dropped_rows give the original row positions.
Phit\fit_ols_matrix(    array $x,    array $y,    string $missing = 'drop',    ?array $weights = NULL,    ?array $offset = NULL,    bool $intercept = true,): LinearFit
Parameter Type Default Description
$x array required Predictor matrix: one row per observation and one numeric column per predictor; null or NAN is missing
$y array required Numeric response, one value per row; null or NAN is missing
$missing string 'drop' 'drop' removes rows with null or NAN in any variable the model uses and warns once; 'raise' rejects them
$weights ?array NULL Positive weights: weighted least squares, as lm(weights = )
$offset ?array NULL Known part of the linear predictor, aligned with the rows; null is zero
$intercept bool true False uses x exactly (including any caller-supplied ones).

Returns

LinearFit A fit object, read like this array:array{  model: 'linear'|'generalized_linear'|'mixed_gaussian'|'mixed_logistic',  coefficients: list<float>,  covariance: list<list<float>>,  std_errors: list<float>,  p_values: list<float>,  conf_int: list<array{float,float}>,  fitted: list<float>,  residuals: list<float>,  log_likelihood: float,  df_residual: int,  diagnostics: array{converged:bool,solver:string,warnings:list<string>,iterations?:int,evaluations?:int,gradient_max?:float,boundary?:bool,singular?:bool},  n_input: int,  n_observations: int,  n_dropped: int,  retained_rows: list<int>,  dropped_rows: list<int>,  t_statistics: list<float>,  rss: float,  residual_variance: float,  sigma: float,  r_squared: float,  adj_r_squared: float,}

Errors Exception: a code from 1001 to 1008 for an input or statistical error.

See also Details

fit_logistic_matrix()

Fits a binomial logit model on a numeric design by Newton steps, like R’s glm(family = binomial).

  • An intercept column is prepended unless intercept is false, in which case x is used exactly.
  • Rows with null or NAN in x, y, or another aligned input are dropped with one warning; missing: 'raise' rejects them instead. retained_rows and dropped_rows give the original row positions.
Phit\fit_logistic_matrix(    array $x,    array $y,    string $missing = 'drop',    ?array $weights = NULL,    ?array $offset = NULL,    bool $intercept = true,): GeneralizedLinearFit
Parameter Type Default Description
$x array required Predictor matrix: one row per observation and one numeric column per predictor; null or NAN is missing
$y array required 0/1 outcomes, or proportions with integer trial weights; null or NAN is missing
$missing string 'drop' 'drop' removes rows with null or NAN in any variable the model uses and warns once; 'raise' rejects them
$weights ?array NULL Positive integer trial counts aligned with the rows; null is one trial per row
$offset ?array NULL Known part of the linear predictor, aligned with the rows; null is zero
$intercept bool true False uses x exactly (including any caller-supplied ones).

Returns

GeneralizedLinearFit A fit object, read like this array:array{  model: 'linear'|'generalized_linear'|'mixed_gaussian'|'mixed_logistic',  coefficients: list<float>,  covariance: list<list<float>>,  std_errors: list<float>,  p_values: list<float>,  conf_int: list<array{float,float}>,  fitted: list<float>,  residuals: list<float>,  log_likelihood: float,  df_residual: int,  diagnostics: array{converged:bool,solver:string,warnings:list<string>,iterations?:int,evaluations?:int,gradient_max?:float,boundary?:bool,singular?:bool},  n_input: int,  n_observations: int,  n_dropped: int,  retained_rows: list<int>,  dropped_rows: list<int>,  z_statistics: list<float>,  deviance: float,  null_deviance: float,  aic: float,  iterations: int,  converged: bool,}

Errors Exception: a code from 1001 to 1008 for an input or statistical error.

See also Details

fit_probit_matrix()

Fits a binomial probit model on a numeric design by Fisher scoring, like R’s glm(family = binomial(link = "probit")).

  • An intercept column is prepended unless intercept is false, in which case x is used exactly.
  • Rows with null or NAN in x, y, or another aligned input are dropped with one warning; missing: 'raise' rejects them instead. retained_rows and dropped_rows give the original row positions.
Phit\fit_probit_matrix(    array $x,    array $y,    string $missing = 'drop',    ?array $weights = NULL,    ?array $offset = NULL,    bool $intercept = true,): GeneralizedLinearFit
Parameter Type Default Description
$x array required Predictor matrix: one row per observation and one numeric column per predictor; null or NAN is missing
$y array required 0/1 outcomes, or proportions with integer trial weights; null or NAN is missing
$missing string 'drop' 'drop' removes rows with null or NAN in any variable the model uses and warns once; 'raise' rejects them
$weights ?array NULL Positive integer trial counts aligned with the rows; null is one trial per row
$offset ?array NULL Known part of the linear predictor, aligned with the rows; null is zero
$intercept bool true False uses x exactly (including any caller-supplied ones).

Returns

GeneralizedLinearFit A fit object, read like this array:array{  model: 'linear'|'generalized_linear'|'mixed_gaussian'|'mixed_logistic',  coefficients: list<float>,  covariance: list<list<float>>,  std_errors: list<float>,  p_values: list<float>,  conf_int: list<array{float,float}>,  fitted: list<float>,  residuals: list<float>,  log_likelihood: float,  df_residual: int,  diagnostics: array{converged:bool,solver:string,warnings:list<string>,iterations?:int,evaluations?:int,gradient_max?:float,boundary?:bool,singular?:bool},  n_input: int,  n_observations: int,  n_dropped: int,  retained_rows: list<int>,  dropped_rows: list<int>,  z_statistics: list<float>,  deviance: float,  null_deviance: float,  aic: float,  iterations: int,  converged: bool,}

Errors Exception: a code from 1001 to 1008 for an input or statistical error.

See also Details

fit_poisson_matrix()

Fits a Poisson log-link model on a numeric design by Newton steps, like R’s glm(family = poisson).

  • An intercept column is prepended unless intercept is false, in which case x is used exactly.
  • Rows with null or NAN in x, y, or another aligned input are dropped with one warning; missing: 'raise' rejects them instead. retained_rows and dropped_rows give the original row positions.
Phit\fit_poisson_matrix(    array $x,    array $y,    string $missing = 'drop',    ?array $weights = NULL,    ?array $offset = NULL,    bool $intercept = true,): GeneralizedLinearFit
Parameter Type Default Description
$x array required Predictor matrix: one row per observation and one numeric column per predictor; null or NAN is missing
$y array required Nonnegative integer counts, one per row; null or NAN is missing
$missing string 'drop' 'drop' removes rows with null or NAN in any variable the model uses and warns once; 'raise' rejects them
$weights ?array NULL Positive prior weights aligned with the rows
$offset ?array NULL Known part of the linear predictor, aligned with the rows; null is zero
$intercept bool true False uses x exactly (including any caller-supplied ones).

Returns

GeneralizedLinearFit A fit object, read like this array:array{  model: 'linear'|'generalized_linear'|'mixed_gaussian'|'mixed_logistic',  coefficients: list<float>,  covariance: list<list<float>>,  std_errors: list<float>,  p_values: list<float>,  conf_int: list<array{float,float}>,  fitted: list<float>,  residuals: list<float>,  log_likelihood: float,  df_residual: int,  diagnostics: array{converged:bool,solver:string,warnings:list<string>,iterations?:int,evaluations?:int,gradient_max?:float,boundary?:bool,singular?:bool},  n_input: int,  n_observations: int,  n_dropped: int,  retained_rows: list<int>,  dropped_rows: list<int>,  z_statistics: list<float>,  deviance: float,  null_deviance: float,  aic: float,  iterations: int,  converged: bool,}

Errors Exception: a code from 1001 to 1008 for an input or statistical error.

See also Details

Printing results

summary()

Prints a model fit in the layout of R’s print(summary(fit)), as text ending in a newline.

  • Takes the result of any model function: OLS and GLM fits, formula or matrix, and Gaussian and logistic mixed fits.
  • The coefficient table follows R’s printCoefmat(digits = 4) without significance stars. A linear model adds the residual standard error, R-squared, and the F statistic; a GLM adds the dispersion, deviances, and AIC; a mixed model adds its fit criteria and the random-effect variances, as lme4 prints them.
  • Matrix fits name their coefficients x1, x2, and so on, and leave out the lines that need a formula.
Phit\summary(    Fit|array $fit,): string
Parameter Type Default Description
$fit Fit\|array required Result of a model function, such as fit_ols() or fit_mixed_gaussian()

Returns string

Errors Exception: code 1001 when fit is not the result of a model function.

See also Details · Example

tidy()

Returns a fit’s coefficient table as columns, like broom’s tidy().

  • The columns are term, estimate, std_error, statistic, and p_value. confInt: true adds conf_low and conf_high at level.
  • Intervals are Wald intervals: t with df_residual degrees of freedom when the fit reports t statistics, and the normal distribution otherwise.
  • For mixed fits, the default effects: 'fixed' gives the fixed effects, and summary() prints the variance components.
  • effects: 'ran_vals' gives a mixed fit’s random effects, as broom.mixed does: group, level, term, estimate, and std_error, one row per term, column, and group. The estimates are the conditional modes and the standard errors their conditional standard deviations, as lme4::ranef(condVar = TRUE) reports them. Intervals use the normal distribution.
Phit\tidy(    Fit|array $fit,    bool $confInt = false,    float $level = 0.95,    string $effects = 'fixed',): Table
Parameter Type Default Description
$fit Fit\|array required Result of a model function, such as fit_ols() or fit_mixed_gaussian()
$confInt bool false Add conf_low and conf_high columns
$level float 0.95 Confidence level of the intervals, in (0, 1)
$effects string 'fixed' 'fixed' for the coefficient table, or 'ran_vals' for a mixed fit’s random effects

Returns Table Columns term, estimate, std_error, statistic, and p_value, or with effects 'ran_vals' group, level, term, estimate, and std_error; confInt adds conf_low and conf_high

Errors Exception: code 1001 when fit is not the result of a model function, level is outside (0, 1), or effects is not 'fixed' or 'ran_vals' ('ran_vals' needs a mixed fit).

See also Details · Example

Fit and table objects

Every model function returns a fit object that implements Phit\Fit: LinearFit, GeneralizedLinearFit, MixedGaussianFit, or MixedLogisticFit, by the kind of model. echo $fit prints its summary. Reading a key, such as $fit['coefficients'], works as on the result array, and nested values are plain arrays. isset(), count(), foreach, and json_encode() work as on the array. Writing or unsetting a key throws LogicException; toArray() returns an array copy. summary(), tidy(), and predict() also accept that array.

Phit\Fit

The interface of every fit object. Each of the four classes has these methods.

Fit::__toString()

The fit printed in the layout of R’s print(summary(fit)), as summary() returns it.

public function __toString(): string

Fit::count()

The number of keys.

public function count(): int

Fit::predict()

Predictions for new data, as predict() returns them for this fit.

public function predict(mixed $newdata, string $type = 'link', bool $seFit = false, string $interval = 'none', float $level = 0.95, bool $random = true, bool $allowNewLevels = false): array
Parameter Description
$newdata Named columns; the response may be absent
$type ‘link’ or ‘response’
$seFit Add standard errors
$interval ‘none’, ‘confidence’, or ‘prediction’
$level Interval level
$random Mixed fits: include the random effects of known groups
$allowNewLevels Mixed fits: predict unseen groups at the population level

Returns array<string,mixed>

Errors Exception: as predict().

Fit::summary()

The fit printed in the layout of R’s print(summary(fit)).

public function summary(): string

Fit::tidy()

The coefficient table as columns, as tidy() returns it.

public function tidy(bool $confInt = false, float $level = 0.95, string $effects = 'fixed'): Table
Parameter Description
$confInt Add conf_low and conf_high columns
$level Confidence level of the intervals, in (0, 1)
$effects ‘fixed’ for the coefficient table, or ‘ran_vals’ for a mixed fit’s random effects

Errors Exception: code 1001 for an invalid level or effects.

Fit::toArray()

The fit as the array the model function computed.

public function toArray(): array

Returns array<string,mixed>

Fit::toMimeBundle()

A Jupyter display bundle: the printed fit as text/plain and the array as application/json.

public function toMimeBundle(): array

Returns array{'text/plain': string, 'application/json': array<string,mixed>}

Phit\Table

Named columns, as tidy() returns them. echo prints them in the layout of R’s print.data.frame(); reading a column works as on the array; the table is read-only, and toColumns() or toArray() returns the columns.

Table::__toString()

The columns in the layout of R’s print.data.frame().

public function __toString(): string

Table::count()

The number of rows.

public function count(): int

Table::toArray()

The columns, name => list.

public function toArray(): array

Returns array<string,list<string\|float>>

Table::toColumns()

The columns, name => list, for phibble’s DataFrame::fromColumns() and phit’s data arguments.

public function toColumns(): array

Returns array<string,list<string\|float>>

Table::toMimeBundle()

A Jupyter display bundle: the printed fit as text/plain and the array as application/json.

public function toMimeBundle(): array

Returns array{'text/plain': string, 'application/json': array<string,mixed>}