Estimate ZINB-WaVE simulation parameters

Estimate simulation parameters for the ZINB-WaVE simulation from a real dataset.

zinbEstimate(
  counts,
  design.samples = NULL,
  design.genes = NULL,
  common.disp = TRUE,
  iter.init = 2,
  iter.opt = 25,
  stop.opt = 1e-04,
  params = newZINBParams(),
  verbose = TRUE,
  BPPARAM = SerialParam(),
  ...
)

# S3 method for SingleCellExperiment
zinbEstimate(
  counts,
  design.samples = NULL,
  design.genes = NULL,
  common.disp = TRUE,
  iter.init = 2,
  iter.opt = 25,
  stop.opt = 1e-04,
  params = newZINBParams(),
  verbose = TRUE,
  BPPARAM = SerialParam(),
  ...
)

# S3 method for matrix
zinbEstimate(
  counts,
  design.samples = NULL,
  design.genes = NULL,
  common.disp = TRUE,
  iter.init = 2,
  iter.opt = 25,
  stop.opt = 1e-04,
  params = newZINBParams(),
  verbose = TRUE,
  BPPARAM = SerialParam(),
  ...
)

Arguments

counts	either a counts matrix or a SingleCellExperiment object containing count data to estimate parameters from.
design.samples	design matrix of sample-level covariates.
design.genes	design matrix of gene-level covariates.
common.disp	logical. Whether or not a single dispersion for all features is estimated.
iter.init	number of iterations to use for initialization.
iter.opt	number of iterations to use for optimization.
stop.opt	stopping criterion for optimization.
params	ZINBParams object to store estimated values in.
verbose	logical. Whether to print progress messages.
BPPARAM	A BiocParallelParam instance giving the parallel back-end to be used. Default is SerialParam which uses a single core.
...	additional arguments passes to zinbFit.

Value

ZINBParams object containing the estimated parameters.

Details

The function is a wrapper around zinbFit that takes the fitted model and inserts it into a ZINBParams object. See ZINBParams for more details on the parameters and zinbFit for details of the estimation procedure.

Examples

if (requireNamespace("zinbwave", quietly = TRUE)) {
    library(scater)
    set.seed(1)
    sce <- mockSCE(ncells = 20, ngenes = 100)

    params <- zinbEstimate(sce)
    params
}
#> Removing all zero genes...
#> Fitting model...
#> Create model:
#> ok
#> Initialize parameters:
#> ok
#> Optimize parameters:
#> Iteration 1
#> penalized log-likelihood = -9797.17477826626
#> After dispersion optimization = -9593.51952142957
#>    user  system elapsed 
#>   0.342   0.005   0.346 
#> After right optimization = -9289.8080540993
#> After orthogonalization = -9289.8080540993
#>    user  system elapsed 
#>   0.093   0.000   0.093 
#> After left optimization = -9285.37113356424
#> After orthogonalization = -9285.37113356424
#> Iteration 2
#> penalized log-likelihood = -9285.37113356424
#> After dispersion optimization = -9235.11877822504
#>    user  system elapsed 
#>   0.246   0.004   0.250 
#> After right optimization = -9229.79020322251
#> After orthogonalization = -9229.79020322251
#>    user  system elapsed 
#>   0.058   0.000   0.058 
#> After left optimization = -9229.25017478905
#> After orthogonalization = -9229.25017478905
#> Iteration 3
#> penalized log-likelihood = -9229.25017478905
#> After dispersion optimization = -9228.65439938794
#>    user  system elapsed 
#>   0.217   0.000   0.217 
#> After right optimization = -9228.44379204834
#> After orthogonalization = -9228.44379204834
#>    user  system elapsed 
#>   0.052   0.000   0.052 
#> After left optimization = -9228.40711393688
#> After orthogonalization = -9228.40711393688
#> Iteration 4
#> penalized log-likelihood = -9228.40711393688
#> ok
#> A Params object of class ZINBParams 
#> Parameters can be (estimable) or [not estimable], 'Default' or  'NOT DEFAULT' 
#> Secondary parameters are usually set during simulation
#> 
#> Global: 
#> (Genes)  (CELLS)   [Seed] 
#>     100       20   121054 
#> 
#> 1 additional parameters 
#> 
#> Model: 
#> ZinbModel with 100 features, 20 samples, 0 latent factors and 241 parameters 
#> 
#> Parameters of the ZinbModel 
#> 
#> Model Design: 
#>      (SAMPLES)         (Genes) 
#> 1, 1, 1, 1,...  1, 1, 1, 1,... 
#> 
#> Model Offsets: 
#>            (MU)             (PI) 
#> 20 x 100 matrix  20 x 100 matrix 
#> 
#> Model Indices: 
#> (Sample Mu)    (Gene Mu)  (Sample Pi)    (Gene Pi) 
#>           1            1            1            1 
#> 
#> Model Intercepts: 
#> (Sample Mu)    (Gene Mu)  (Sample Pi)    (Gene Pi) 
#>        TRUE         TRUE         TRUE         TRUE 
#> 
#> Model Latent factors: 
#>           (W) 
#> 20 x 0 matrix 
#> 
#> Model Coefficients: 
#>                                                                     (SAMPLE MU)                                                                        (GENE MU)                                                                      (Latent Mu)                                                                      (SAMPLE PI)                                                                        (GENE PI)                                                                      (Latent Pi) 
#> -0.459768349311904, 1.6211941766607, -0.223102897001514, 0.0429480000462582,...       4.26299871296772, 4.29178877663662, 4.44953734970852, 3.86260699714574,...                                                                   0 x 100 matrix   1.90227701103766, -6.94250263618026, -1.07944947119589, -0.430739492373279,...    -0.983739818961789, -1.35075675357218, -1.232854483926, -1.26060100804175,...                                                                   0 x 100 matrix 
#> 
#> Model Regularisation: 
#>     (Sample Mu)        (GENE MU)      (Sample Pi)        (GENE PI) 
#>               1                5                1                5 
#>        (LATENT)  (Latent coeffs)           (Zeta)          (Logit) 
#>               5                1              100            0.001 
#>