class_docstr: Basis function-based reconstruction method
  
  Inverted encoding models (alternatively known as forward models) are used
  to reconstruct a feature represented in a N-dimensional space, here 2D,
  (e.g. position on a projector screen) from patterns across voxels in
  functional data. The model uses some number of idealized basis functions
  that cover the 2D space, and assumes that the transformation from
  stimulus feature (e.g. 2D spatial position) to basis function is one-
  to-one and invertible. The response of a voxel is expressed as the
  weighted sum of basis functions. In this implementation, basis functions
  were half-wave rectified sinusoid functions raised to some power (set by
  the user).
  
  The documentation will refer to the 'stimulus space' or 'stimulus domain',
  which should be a 2D space in consistent units (e.g. screen pixels,
  or degrees visual angle). The stimulus space is the domain in which the
  stimulus is reconstructed. We will refer to the each point in this 2D
  stimulus domain as a 'pixel'.
  
  The model:
  Inverted encoding models reconstruct a stimulus feature from
  patterns of BOLD activity by relating the activity in each
  voxel, B, to the values of hypothetical channels (or basis
  functions), C, according to Equation 1 below.
  
  (1)     B = W*C
  
  where W is a weight matrix that represents the relationship
  between BOLD activity and Channels. W must be estimated from
  training data; this implementation (and most described in the
  literature) uses linear regression to estimate W as in Equation
  2 below [note: inv() represents matrix inverse or
  pseudo-inverse].
  
  (2)     W_est = B_train*inv(C_train)
  
  The weights in W_est (short for "estimated") represent the
  contributions of each channel to the response of each voxel.
  Estimated channel responses can be computed given W_est and
  new voxel activity represented in matrix B_exp (short for
  "experiment") through inversion of Equation 1:
  
  (3)     C_est = inv(W_est)*B_exp
  
  Given estimated channel responses, C_est, it is straightforward
  to obtain the reconstructed feature value by summing over
  channels multiplied by their channel responses and taking the
  argmax (i.e. the feature associated with the maximum value).
  
  Using this model:
  Use fit() to estimate the weights of the basis functions given
  input data (e.g. beta values from fMRI data). This function
  will execute equation 2 above.
  
  Use predict() to compute predicted stimulus values
  from new functional data. This function computes estimated
  channel responses, as in equation 3, then computes summed
  channel output and finds the argmax (within the stimulus
  feature space) associated with those responses.
  
  Use score() to compute a measure of the error of the prediction
  based on known stimuli.
  
  Parameters
  ----------
  stim_xlim: list of 2 floats Specifies the minimum and maximum x-values
      of the area to be reconstructed. In order to be estimated properly, a
      stimulus must appear at these limits. Specifying limits outside the
      range of the stimuli can lead to spurious estimates.
  
  stim_ylim: list of 2 floats Specifies the minimum and maximum y-values
      of the area to be reconstructed. In order to be estimated properly, a
      stimulus must appear at these limits. Specifying limits outside the
      range of the stimuli can lead to spurious estimates.
  
  stimulus_resolution: float or list of 2 floats. If a single float is
      given, it will be expanded to a list (i.e. we will assume that the
      reconstructed area is composed of square pixels).
  
  stim_radius: float, or sequence of floats [n_stim], default None. If the
      user does not define the design matrix of the encoding model (e.g. C
      in B = W*C), it will be defined automatically on the assumption that
      each observation was for a 2D circular stimulus of some radius.
  
  chan_xlim: list of 2 floats, default None. Specifies the minimum and
      maximum x-values of the channels, or basis functions.
  
  chan_ylim: list of 2 floats, default None. Specifies the minimum and
      maximum y-values of the channels, or basis functions.
  
  channels: [n_channels, n_pixels] NumPy 2D array, default None. If None at
      initialization, it can be defined with
      either define_basis_functions_sqgrid() or
      define_basis_functions_trigrid(), each of which tiles the given 2D
      space with some grid (square or triangular/hexagonal, respectively).
      Alternatively, the user can specify their own channels.
  
  channel_exp: int, default 7. Basis function exponent. The exponent of the
      sinuoidal basis functions, which helps control their width.
  
  Attributes
  ----------
  channels: [n_channels, n_pixels] NumPy 2D array defining channels
  
  W_: sklearn.linear_model containing weight matrix that relates estimated
      channel responses to response data
  
  See get_params() for the rest of the attributes.
class_docstr_tok: ["Basis","function-based","reconstruction","method","Inverted","encoding","models","(","alternatively","known","as","forward","models",")","are","used","to","reconstruct","a","feature","represented","in","a","N-dimensional","space",",","here","2D",",","(","e.g",".","position","on","a","projector","screen",")","from","patterns","across","voxels","in","functional","data",".","The","model","uses","some","number","of","idealized","basis","functions","that","cover","the","2D","space",",","and","assumes","that","the","transformation","from","stimulus","feature","(","e.g",".","2D","spatial","position",")","to","basis","function","is","one-","to-one","and","invertible",".","The","response","of","a","voxel","is","expressed","as","the","weighted","sum","of","basis","functions",".","In","this","implementation",",","basis","functions","were","half-wave","rectified","sinusoid","functions","raised","to","some","power","(","set","by","the","user",")",".","The","documentation","will","refer","to","the","'stimulus","space","'","or","'stimulus","domain","'",",","which","should","be","a","2D","space","in","consistent","units","(","e.g",".","screen","pixels",",","or","degrees","visual","angle",")",".","The","stimulus","space","is","the","domain","in","which","the","stimulus","is","reconstructed",".","We","will","refer","to","the","each","point","in","this","2D","stimulus","domain","as","a","'pixel","'",".","The","model",":","Inverted","encoding","models","reconstruct","a","stimulus","feature","from","patterns","of","BOLD","activity","by","relating","the","activity","in","each","voxel",",","B",",","to","the","values","of","hypothetical","channels","(","or","basis","functions",")",",","C",",","according","to","Equation","1","below",".","(","1",")","B","=","W","*","C","where","W","is","a","weight","matrix","that","represents","the","relationship","between","BOLD","activity","and","Channels",".","W","must","be","estimated","from","training","data",";","this","implementation","(","and","most","described","in","the","literature",")","uses","linear","regression","to","estimate","W","as","in","Equation","2","below","[","note",":","inv","(",")","represents","matrix","inverse","or","pseudo-inverse","]",".","(","2",")","W_est","=","B_train","*","inv","(","C_train",")","The","weights","in","W_est","(","short","for","``","estimated","''",")","represent","the","contributions","of","each","channel","to","the","response","of","each","voxel",".","Estimated","channel","responses","can","be","computed","given","W_est","and","new","voxel","activity","represented","in","matrix","B_exp","(","short","for","''","experiment","''",")","through","inversion","of","Equation","1",":","(","3",")","C_est","=","inv","(","W_est",")","*","B_exp","Given","estimated","channel","responses",",","C_est",",","it","is","straightforward","to","obtain","the","reconstructed","feature","value","by","summing","over","channels","multiplied","by","their","channel","responses","and","taking","the","argmax","(","i.e",".","the","feature","associated","with","the","maximum","value",")",".","Using","this","model",":","Use","fit","(",")","to","estimate","the","weights","of","the","basis","functions","given","input","data","(","e.g",".","beta","values","from","fMRI","data",")",".","This","function","will","execute","equation","2","above",".","Use","predict","(",")","to","compute","predicted","stimulus","values","from","new","functional","data",".","This","function","computes","estimated","channel","responses",",","as","in","equation","3",",","then","computes","summed","channel","output","and","finds","the","argmax","(","within","the","stimulus","feature","space",")","associated","with","those","responses",".","Use","score","(",")","to","compute","a","measure","of","the","error","of","the","prediction","based","on","known","stimuli",".","Parameters","--","--","--","--","--","stim_xlim",":","list","of","2","floats","Specifies","the","minimum","and","maximum","x-values","of","the","area","to","be","reconstructed",".","In","order","to","be","estimated","properly",",","a","stimulus","must","appear","at","these","limits",".","Specifying","limits","outside","the","range","of","the","stimuli","can","lead","to","spurious","estimates",".","stim_ylim",":","list","of","2","floats","Specifies","the","minimum","and","maximum","y-values","of","the","area","to","be","reconstructed",".","In","order","to","be","estimated","properly",",","a","stimulus","must","appear","at","these","limits",".","Specifying","limits","outside","the","range","of","the","stimuli","can","lead","to","spurious","estimates",".","stimulus_resolution",":","float","or","list","of","2","floats",".","If","a","single","float","is","given",",","it","will","be","expanded","to","a","list","(","i.e",".","we","will","assume","that","the","reconstructed","area","is","composed","of","square","pixels",")",".","stim_radius",":","float",",","or","sequence","of","floats","[","n_stim","]",",","default","None",".","If","the","user","does","not","define","the","design","matrix","of","the","encoding","model","(","e.g",".","C","in","B","=","W","*","C",")",",","it","will","be","defined","automatically","on","the","assumption","that","each","observation","was","for","a","2D","circular","stimulus","of","some","radius",".","chan_xlim",":","list","of","2","floats",",","default","None",".","Specifies","the","minimum","and","maximum","x-values","of","the","channels",",","or","basis","functions",".","chan_ylim",":","list","of","2","floats",",","default","None",".","Specifies","the","minimum","and","maximum","y-values","of","the","channels",",","or","basis","functions",".","channels",":","[","n_channels",",","n_pixels","]","NumPy","2D","array",",","default","None",".","If","None","at","initialization",",","it","can","be","defined","with","either","define_basis_functions_sqgrid","(",")","or","define_basis_functions_trigrid","(",")",",","each","of","which","tiles","the","given","2D","space","with","some","grid","(","square","or","triangular\/hexagonal",",","respectively",")",".","Alternatively",",","the","user","can","specify","their","own","channels",".","channel_exp",":","int",",","default","7",".","Basis","function","exponent",".","The","exponent","of","the","sinuoidal","basis","functions",",","which","helps","control","their","width",".","Attributes","--","--","--","--","--","channels",":","[","n_channels",",","n_pixels","]","NumPy","2D","array","defining","channels","W_",":","sklearn.linear_model","containing","weight","matrix","that","relates","estimated","channel","responses","to","response","data","See","get_params","(",")","for","the","rest","of","the","attributes","."]
docstr: Defines a 2D inverted encoding model object.
  
  While the parameters defining the domain in which to reconstruct
  the stimuli are required (e.g. all `stim_*` inputs), the parameters
  to define the channels (`chan*`) are optional, in case the user
  wishes to define their own channels (a.k.a basis functions).
  
  
  Parameters
  ----------
  stim_xlim: sequence of 2 float values, specifying the lower & upper
      limits on the horizontal axis, respectively.
  stim_ylim: sequence of 2 float values, specifying the lower & upper
      limits on the vertical axis, respectively.
  stimulus_resolution: a float or sequence of 2 floats, specifying the
      number of pixels that exist in the x- and y- directions.
  stim_radius: float, default None. The radius in pixels, assuming that
      the stimulus is circular. If None, the user must either define it
      before running fit(), or pass in a custom C in B = W*C.
  chan_xlim: sequence of 2 float values, default None. Specifies the
      lower & upper limits of the channels in the horizontal axis. If
      None, the user must define this before using the class functions
      to create basis functions, or pass in custom-defined channels.
  chan_ylim: sequence of 2 float values, default None. Specifies the
      lower & upper limits of the channels in the vertical axis. If
      None, the user must define this before using the class functions
      to create basis functions, or pass in custom-defined channels.
  channel_exp: float or int, default None. The exponent for a
      sinusoidal basis function. If None, it must be set before the
      channels or defined, or pass in custom-defined channels.
docstr_tok: ["Defines","a","2D","inverted","encoding","model","object",".","While","the","parameters","defining","the","domain","in","which","to","reconstruct","the","stimuli","are","required","(","e.g",".","all","`","stim_","*","`","inputs",")",",","the","parameters","to","define","the","channels","(","`","chan","*","`",")","are","optional",",","in","case","the","user","wishes","to","define","their","own","channels","(","a.k.a","basis","functions",")",".","Parameters","--","--","--","--","--","stim_xlim",":","sequence","of","2","float","values",",","specifying","the","lower","&","upper","limits","on","the","horizontal","axis",",","respectively",".","stim_ylim",":","sequence","of","2","float","values",",","specifying","the","lower","&","upper","limits","on","the","vertical","axis",",","respectively",".","stimulus_resolution",":","a","float","or","sequence","of","2","floats",",","specifying","the","number","of","pixels","that","exist","in","the","x-","and","y-","directions",".","stim_radius",":","float",",","default","None",".","The","radius","in","pixels",",","assuming","that","the","stimulus","is","circular",".","If","None",",","the","user","must","either","define","it","before","running","fit","(",")",",","or","pass","in","a","custom","C","in","B","=","W","*","C.","chan_xlim",":","sequence","of","2","float","values",",","default","None",".","Specifies","the","lower","&","upper","limits","of","the","channels","in","the","horizontal","axis",".","If","None",",","the","user","must","define","this","before","using","the","class","functions","to","create","basis","functions",",","or","pass","in","custom-defined","channels",".","chan_ylim",":","sequence","of","2","float","values",",","default","None",".","Specifies","the","lower","&","upper","limits","of","the","channels","in","the","vertical","axis",".","If","None",",","the","user","must","define","this","before","using","the","class","functions","to","create","basis","functions",",","or","pass","in","custom-defined","channels",".","channel_exp",":","float","or","int",",","default","None",".","The","exponent","for","a","sinusoidal","basis","function",".","If","None",",","it","must","be","set","before","the","channels","or","defined",",","or","pass","in","custom-defined","channels","."]
code: def __init__(
      self,
      stim_xlim,
      stim_ylim,
      stimulus_resolution,
      stim_radius=None,
      chan_xlim=None,
      chan_ylim=None,
      channels=None,
      channel_exp=7,
  ):
      """Defines a 2D inverted encoding model object.
  
      While the parameters defining the domain in which to reconstruct
      the stimuli are required (e.g. all `stim_*` inputs), the parameters
      to define the channels (`chan*`) are optional, in case the user
      wishes to define their own channels (a.k.a basis functions).
  
  
      Parameters
      ----------
      stim_xlim: sequence of 2 float values, specifying the lower & upper
          limits on the horizontal axis, respectively.
      stim_ylim: sequence of 2 float values, specifying the lower & upper
          limits on the vertical axis, respectively.
      stimulus_resolution: a float or sequence of 2 floats, specifying the
          number of pixels that exist in the x- and y- directions.
      stim_radius: float, default None. The radius in pixels, assuming that
          the stimulus is circular. If None, the user must either define it
          before running fit(), or pass in a custom C in B = W*C.
      chan_xlim: sequence of 2 float values, default None. Specifies the
          lower & upper limits of the channels in the horizontal axis. If
          None, the user must define this before using the class functions
          to create basis functions, or pass in custom-defined channels.
      chan_ylim: sequence of 2 float values, default None. Specifies the
          lower & upper limits of the channels in the vertical axis. If
          None, the user must define this before using the class functions
          to create basis functions, or pass in custom-defined channels.
      channel_exp: float or int, default None. The exponent for a
          sinusoidal basis function. If None, it must be set before the
          channels or defined, or pass in custom-defined channels.
  
      """
      # Automatically expand stimulus_resolution if only one value is given.
      # This will create a square field  of view (FOV) for the
      # reconstruction.
      if not isinstance(stimulus_resolution, list):  # make FOV square
          stimulus_resolution = [
              stimulus_resolution,
              stimulus_resolution,
          ]
      if (len(stim_xlim) != 2) or (len(stim_ylim) != 2):
          raise ValueError(
              "Stimulus limits should be a sequence, 2 values"
          )
      self.stim_fov = [stim_xlim, stim_ylim]
      self.stim_pixels = [
          np.linspace(
              stim_xlim[0], stim_xlim[1], stimulus_resolution[0]
          ),
          np.linspace(
              stim_ylim[0], stim_ylim[1], stimulus_resolution[1]
          ),
      ]
      self.xp, self.yp = np.meshgrid(
          self.stim_pixels[0], self.stim_pixels[1]
      )
      self.stim_radius_px = stim_radius
      self.channels = channels
      if self.channels is None:
          self.n_channels = None
      else:
          self.n_channels = self.channels.shape[0]
      if chan_xlim is None:
          chan_xlim = stim_xlim
          logger.info(
              "Set channel x-limits to stimulus x-limits", stim_xlim
          )
      if chan_ylim is None:
          chan_ylim = stim_ylim
          logger.info(
              "Set channel y-limits to stimulus y-limits", stim_ylim
          )
      self.channel_limits = [chan_xlim, chan_ylim]
      self.channel_exp = channel_exp
      self._check_params()
  
imports: import logging
  import warnings
  import numpy
  import scipy.stats
  from sklearn.base import BaseEstimator
  from sklearn.metrics.pairwise import cosine_distances, euclidean_distances
  from ..utils.utils import circ_dist
label_desc: Use image node_id 1 to create a new InvertedEncoding2D object from inherited base classes: BaseEstimator with example: obj = InvertedEncoding2D(stim_xlim, stim_ylim, stimulus_resolution, stim_radius, chan_xlim, chan_ylim, channels, channel_exp)