docstr: Estimate motion parameters.
  
  Parameters
  ----------
  loops : int or sequence of ints
      Determines the number of iterations performed to realign
      scans within each run for each pass defined by the
      ``speedup`` argument. For instance, setting ``speedup`` ==
      (5,2) and ``loops`` == (5,1) means that 5 iterations are
      performed in a first pass where scans are subsampled by an
      isotropic factor 5, followed by one iteration where scans
      are subsampled by a factor 2.
  between_loops : None, int or sequence of ints
      Similar to ``loops`` for between-run motion
      estimation. Determines the number of iterations used to
      realign scans across runs, a procedure similar to
      within-run realignment that uses the mean images from each
      run. If None, assumed to be the same as ``loops``.
      The setting used in the experiments described in Roche,
      IEEE TMI 2011, was: ``speedup`` = (5, 2), ``loops`` = (5,
      1) and ``between_loops`` = (5, 1).
  align_runs : bool
      Determines whether between-run motion is estimated or
      not. If False, the ``between_loops`` argument is ignored.
  speedup: int or sequence of ints
      Determines an isotropic sub-sampling factor, or a sequence
      of such factors, applied to the scans to perform motion
      estimation. If a sequence, several estimation passes are
      applied.
  refscan : None or int
      Defines the number of the scan used as the reference
      coordinate system for each run. If None, a reference
      coordinate system is defined internally that does not
      correspond to any particular scan. Note that the
      coordinate system associated with the first run is always
  borders : sequence of ints
      Should be of length 3. Determines the field of view for
      motion estimation in terms of the number of slices at each
      extremity of the reference grid that are ignored for
      motion parameter estimation. For instance,
      ``borders``==(1,1,1) means that the realignment cost
      function will not take into account voxels located in the
      first and last axial/sagittal/coronal slices in the
      reference grid. Please note that this choice only affects
      parameter estimation but does not affect image resampling
      in any way, see ``resample`` method.
  optimizer : str
      Defines the optimization method. One of 'simplex',
      'powell', 'cg', 'ncg', 'bfgs' and 'steepest'.
  xtol : float
      Tolerance on variations of transformation parameters to
      test numerical convergence.
  ftol : float
      Tolerance on variations of the intensity comparison metric
      to test numerical convergence.
  gtol : float
      Tolerance on the gradient of the intensity comparison
      metric to test numerical convergence. Applicable to
      optimizers 'cg', 'ncg', 'bfgs' and 'steepest'.
  stepsize : float
      Step size to approximate the gradient and Hessian of the
      intensity comparison metric w.r.t. transformation
      parameters. Applicable to optimizers 'cg', 'ncg', 'bfgs'
      and 'steepest'.
  maxiter : int
      Maximum number of iterations in optimization.
  maxfun : int
      Maximum number of function evaluations in maxfun.
docstr_tok: ["Estimate","motion","parameters",".","Parameters","--","--","--","--","--","loops",":","int","or","sequence","of","ints","Determines","the","number","of","iterations","performed","to","realign","scans","within","each","run","for","each","pass","defined","by","the","``","speedup","``","argument",".","For","instance",",","setting","``","speedup","``","==","(","5,2",")","and","``","loops","``","==","(","5,1",")","means","that","5","iterations","are","performed","in","a","first","pass","where","scans","are","subsampled","by","an","isotropic","factor","5",",","followed","by","one","iteration","where","scans","are","subsampled","by","a","factor","2.","between_loops",":","None",",","int","or","sequence","of","ints","Similar","to","``","loops","``","for","between-run","motion","estimation",".","Determines","the","number","of","iterations","used","to","realign","scans","across","runs",",","a","procedure","similar","to","within-run","realignment","that","uses","the","mean","images","from","each","run",".","If","None",",","assumed","to","be","the","same","as","``","loops","``",".","The","setting","used","in","the","experiments","described","in","Roche",",","IEEE","TMI","2011",",","was",":","``","speedup","``","=","(","5",",","2",")",",","``","loops","``","=","(","5",",","1",")","and","``","between_loops","``","=","(","5",",","1",")",".","align_runs",":","bool","Determines","whether","between-run","motion","is","estimated","or","not",".","If","False",",","the","``","between_loops","``","argument","is","ignored",".","speedup",":","int","or","sequence","of","ints","Determines","an","isotropic","sub-sampling","factor",",","or","a","sequence","of","such","factors",",","applied","to","the","scans","to","perform","motion","estimation",".","If","a","sequence",",","several","estimation","passes","are","applied",".","refscan",":","None","or","int","Defines","the","number","of","the","scan","used","as","the","reference","coordinate","system","for","each","run",".","If","None",",","a","reference","coordinate","system","is","defined","internally","that","does","not","correspond","to","any","particular","scan",".","Note","that","the","coordinate","system","associated","with","the","first","run","is","always","borders",":","sequence","of","ints","Should","be","of","length","3",".","Determines","the","field","of","view","for","motion","estimation","in","terms","of","the","number","of","slices","at","each","extremity","of","the","reference","grid","that","are","ignored","for","motion","parameter","estimation",".","For","instance",",","``","borders","``","==","(","1,1,1",")","means","that","the","realignment","cost","function","will","not","take","into","account","voxels","located","in","the","first","and","last","axial\/sagittal\/coronal","slices","in","the","reference","grid",".","Please","note","that","this","choice","only","affects","parameter","estimation","but","does","not","affect","image","resampling","in","any","way",",","see","``","resample","``","method",".","optimizer",":","str","Defines","the","optimization","method",".","One","of","'simplex","'",",","'powell","'",",","'cg","'",",","'ncg","'",",","'bfgs","'","and","'steepest","'",".","xtol",":","float","Tolerance","on","variations","of","transformation","parameters","to","test","numerical","convergence",".","ftol",":","float","Tolerance","on","variations","of","the","intensity","comparison","metric","to","test","numerical","convergence",".","gtol",":","float","Tolerance","on","the","gradient","of","the","intensity","comparison","metric","to","test","numerical","convergence",".","Applicable","to","optimizers","'cg","'",",","'ncg","'",",","'bfgs","'","and","'steepest","'",".","stepsize",":","float","Step","size","to","approximate","the","gradient","and","Hessian","of","the","intensity","comparison","metric","w.r.t",".","transformation","parameters",".","Applicable","to","optimizers","'cg","'",",","'ncg","'",",","'bfgs'","and","'steepest","'",".","maxiter",":","int","Maximum","number","of","iterations","in","optimization",".","maxfun",":","int","Maximum","number","of","function","evaluations","in","maxfun","."]
code: def estimate(
      self,
      loops=5,
      between_loops=None,
      align_runs=True,
      speedup=5,
      refscan=0,
      borders=(1, 1, 1),
      optimizer="ncg",
      xtol=XTOL,
      ftol=FTOL,
      gtol=GTOL,
      stepsize=STEPSIZE,
      maxiter=MAXITER,
      maxfun=MAXFUN,
  ):
      """Estimate motion parameters.
  
      Parameters
      ----------
      loops : int or sequence of ints
          Determines the number of iterations performed to realign
          scans within each run for each pass defined by the
          ``speedup`` argument. For instance, setting ``speedup`` ==
          (5,2) and ``loops`` == (5,1) means that 5 iterations are
          performed in a first pass where scans are subsampled by an
          isotropic factor 5, followed by one iteration where scans
          are subsampled by a factor 2.
      between_loops : None, int or sequence of ints
          Similar to ``loops`` for between-run motion
          estimation. Determines the number of iterations used to
          realign scans across runs, a procedure similar to
          within-run realignment that uses the mean images from each
          run. If None, assumed to be the same as ``loops``.
          The setting used in the experiments described in Roche,
          IEEE TMI 2011, was: ``speedup`` = (5, 2), ``loops`` = (5,
          1) and ``between_loops`` = (5, 1).
      align_runs : bool
          Determines whether between-run motion is estimated or
          not. If False, the ``between_loops`` argument is ignored.
      speedup: int or sequence of ints
          Determines an isotropic sub-sampling factor, or a sequence
          of such factors, applied to the scans to perform motion
          estimation. If a sequence, several estimation passes are
          applied.
      refscan : None or int
          Defines the number of the scan used as the reference
          coordinate system for each run. If None, a reference
          coordinate system is defined internally that does not
          correspond to any particular scan. Note that the
          coordinate system associated with the first run is always
      borders : sequence of ints
          Should be of length 3. Determines the field of view for
          motion estimation in terms of the number of slices at each
          extremity of the reference grid that are ignored for
          motion parameter estimation. For instance,
          ``borders``==(1,1,1) means that the realignment cost
          function will not take into account voxels located in the
          first and last axial/sagittal/coronal slices in the
          reference grid. Please note that this choice only affects
          parameter estimation but does not affect image resampling
          in any way, see ``resample`` method.
      optimizer : str
          Defines the optimization method. One of 'simplex',
          'powell', 'cg', 'ncg', 'bfgs' and 'steepest'.
      xtol : float
          Tolerance on variations of transformation parameters to
          test numerical convergence.
      ftol : float
          Tolerance on variations of the intensity comparison metric
          to test numerical convergence.
      gtol : float
          Tolerance on the gradient of the intensity comparison
          metric to test numerical convergence. Applicable to
          optimizers 'cg', 'ncg', 'bfgs' and 'steepest'.
      stepsize : float
          Step size to approximate the gradient and Hessian of the
          intensity comparison metric w.r.t. transformation
          parameters. Applicable to optimizers 'cg', 'ncg', 'bfgs'
          and 'steepest'.
      maxiter : int
          Maximum number of iterations in optimization.
      maxfun : int
          Maximum number of function evaluations in maxfun.
      """
      if between_loops is None:
          between_loops = loops
      t = realign4d(
          self._runs,
          affine_class=self.affine_class,
          time_interp=self._time_interp,
          align_runs=align_runs,
          loops=loops,
          between_loops=between_loops,
          speedup=speedup,
          refscan=refscan,
          borders=borders,
          optimizer=optimizer,
          xtol=xtol,
          ftol=ftol,
          gtol=gtol,
          stepsize=stepsize,
          maxiter=maxiter,
          maxfun=maxfun,
      )
      (
          self._transforms,
          self._within_run_transforms,
          self._mean_transforms,
      ) = t
  
imports: import os
  import warnings
  import numpy
  from nibabel import io_orientation
  from nibabel.affines import apply_affine
  from ...core.image.image_spaces import as_xyz_image, make_xyz_image, xyz_affine
  from ...io.nibcompat import get_header
  from ..slicetiming import timefuncs
  from ._registration import _cspline_sample3d, _cspline_sample4d, _cspline_transform
  from .affine import Affine, Rigid
  from .optimizer import configure_optimizer, use_derivatives
  from .type_check import check_type, check_type_and_shape
label_desc: Use image node_id 3 for calling the Realign4d obj's underlying member method code with example usage: obj.estimate(loops, between_loops, align_runs, speedup, refscan, borders, optimizer, xtol, ftol, gtol, stepsize, maxiter, maxfun) without return types