Welcome to Neuropythy’s documentation!

Tools for analyzing and registering cortical meshes.

neuropythy.load(filename, format=None, **kwargs)
load(filename) yields the data contained in the file referenced by the given filename in a
neuropythy or neuropythy-friendly format.
load(filename, format) specifies that the given format should be used; this should be the name
of the importer (though a file extension that is recognized also will work).

Additionally, functions located in load.<format> may be used; so, for example, the following are equivalent calls:

load(filename, ‘nifti’) load.nifti(filename)

In fact, the load.nifti function is just the nifti importer, so help(load.nifti) will also yield documentation for the nifti importer.

Keyword options may be passed to load; these must match those accepted by the given import function.

neuropythy.save(filename, data, format=None, **kwargs)

save(filename, data) writes the given data to the given filename then yieds that filename. save(filename, data, format) specifies that the given format should be used; this should be the

name of the exporter (though a file extension that is recognized also will work).

Additionally, functions located in save.<format> may be used; so, for example, the following are equivalent calls:

save(filename, image, ‘nifti’) save.nifti(filename, image)

In fact, the save.nifti function is just the nifti exporter, so help(save.nifti) will also yield documentation for the nifti exporter.

Keyword options may be passed to save; these must match those accepted by the given export function.

neuropythy.to_nifti(obj, like=None, header=None, affine=None, extensions=Ellipsis, version=1)
to_nifti(obj) yields a Nifti2Image object that is as equivalent as possible to the given object
obj. If obj is a Nifti2Image already, then it is returned unmolested; other deduction rules are described below.
The following options are accepted:
  • like (default: None) may be provided to give a guide for the various header- and meta-data that is included in the image. If this is a nifti image object, its meta-data are used; if this is a subject, then the meta-data are deduced from the subject’s voxel and native orientation matrices. All other specific options below override anything deduced from the like argument.
  • header (default: None) may be a Nifti1 or Niti2 image header to be used as the nifti header or to replace the header in a new image.
  • affine (default: None) may specify the affine transform to be given to the image object.
  • extensions (default: Ellipsis) may specify a nifti extensions object that should be included in the header. The default value, Ellipsis, indicates that the extensions should not be changed, and that None should be used if extensions are not implied in obj (if, for example, obj is a data array rather than an image object with a header already.
  • version (default: 2) may be specified as 1 or 2 for a Nifti1Image or Nifti2Image object, respectively.
class neuropythy.Cortex(imm, *args, **kwargs)

Cortex is a class that handles a single cortical hemisphere; cortex tracks both the spherical registrations that can be used for cross-subject interpolation as well as the various surfaces and cortical layers that can be produced from the combined white/pial surfaces. Cortex is the go-to class for performing interpolation between subjects as it is a Topology object and thus knows how to search for common registrations for interpolation and comparison. Cortex also holds the required methods for creating map projections from spherical registrations.

Cortex(chirality, tess, surfaces, registrations) is typically used to initialize a cortex object. The chirality should be either ‘lh’ or ‘rh’; tess must be the tesselation of the cortex object. The surfaces and registrations arguments should both be (possibly lazy) maps whose values are the appropriate mesh objects. The surfaces must include ‘white’ and ‘pial’. If the registrations includes the key ‘native’ this is taken to be the default registration for the particular cortex object.

static chirality(ch)

cortex.chirality gives the chirality (‘lh’ or ‘rh’) for the given cortex.

from_image(image, surface='midgray', affine=None, method=None, fill=0, dtype=None, native_to_vertex_matrix=None)

cortex.from_image(image) is equivalent to cortex.midgray_surface.from_image(image). cortex.from_image(image, surface) uses the given surface (see also cortex.surface).

static midgray_surface(white_surface, pial_surface)

cortex.midgray_surface is the mesh representing the midgray surface half way between the white and pial surfaces.

static pial_surface(surfaces)

cortex.pial_surface is the mesh representing the pial surface of the given cortex.

static repr(chirality, tess, vertex_count)

cortex.repr is equivalent to repr(cortex).

surface(name='white')

cortex.surface() yields the white surface of the given cortex cortex.surface(name) yields the surface with the given name (e.g., ‘white’, ‘pial’,

‘inflated’, ‘midgray’).
cortex.surface(fraction) yields the surface that is <fraction> of the distance from white
to pial (0 is equivalent to ‘white’; 1 is equivalent to ‘pial’). Layers outside of the range 0-1 may be returned by following the vectors between white and pial surfaces, but they may have odd appearances, and this should not be confused with surface inflation.

cortex.surface([dist]) yields the layer that is the given distance from the white surface.

static surface_coordinates(surfs)

cortex.surface_coordinates is a mapping of the surface coordinates of the given cortex; this must include the surfaces ‘white’ and ‘pial’.

static surfaces(surface_coordinates, properties, tess)

cortex.surfaces is a mapping of the surfaces of the given cortex; this must include the surfaces ‘white’ and ‘pial’.

static validate_surfaces(surfaces)

validate_surfaces requires that the surfaces map contain the keys ‘white’ and ‘pial’.

static white_surface(surfaces)

cortex.white_surface is the mesh representing the white-matter surface of the given cortex.

static white_to_pial_vectors(white_surface, pial_surface)
cortex.white_to_pial_vectors is a (3 x n) matrix of the unit direction vectors that point
from the n vertices in the cortex’s white surface to their equivalent positions in the pial surface.
class neuropythy.Subject(imm, *args, **kwargs)

Subject is a class that tracks information about an individual subject. A Subject object keeps track of hemispheres (Cortex objects) as well as some information about the voxels (e.g., the gray_mask).

When declaring a subject, the hemispheres argument (hemis) should always include at least the keys ‘lh’ and ‘rh’. Images should, at a minimum, include the following in their images dictionary:

  • lh_gray_mask
  • rh_gray_mask
  • lh_white_mask
  • rh_white_mask

Alternately, the values with the same names may be overloaded in a daughter class.

Subject respects laziness in the hemis and images classes, and this mechanism is recommended as a way to lazily load subject data (see pimms.lazy_map).

static LH(hemis)

sub.LH is an alias for sub.hemis[‘lh’].

static RH(hemis)

sub.RH is an alias for sub.hemis[‘rh’].

cortex_to_image(data, hemi=None, method='linear', fill=0, dtype=None, affine=None, shape=None)
sub.cortex_to_image(data, hemi) projects the given cortical-surface data to the given
subject’s gray-matter voxels of the given hemisphere and returns the resulting numpy array.

sub.cortex_to_image((lh_data, rh_data)) projects into both hemispheres.

The following options may be given:
  • method (default: ‘linear’) specifies that a particular method should be used; valid options are ‘linear’, ‘heaviest’, and ‘nearest’. The ‘linear’ method uses the lh_vertex_to_voxel_linear_interpolation and rh_vertex_to_voxel_linear_interpolation matrices while ‘nearest’ uses the nearest-neighbor interpolation. The ‘heaviest’ method uses the highest-valued weight in the ‘linear’ interpolation matrix, which is equivalent to using nearest-neighbor interpolation after controlling for the depth of the voxel with respect to the vertices. The ‘linear’ method is generally preferred unless your data is discreet, in which the ‘heaviest’ method is generally best.
  • fill (default: 0) specifies the value to be assigned to all voxels not in the gray mask or voxels in the gray-mask that are missed by the interpolation method.
  • dtype (default: None) specifies the data type that should be exported. If None, this will be automatically set to np.float32 for floating-point data and np.int32 for integer data.
  • affine (default: None) specifies the affine transformation that should be used to align the cortical surfaces with the voxels. If None, then the subject’s vertex-to-voxel matrix will be used.
  • shape (default: None) specifies the dimensions of the output array; if None, then the subject’s image_dimensions is used.
static gray_indices(lh_gray_indices, rh_gray_indices)

sub.gray_indices is equivalent to numpy.where(sub.gray_mask).

static hemis(h)

sub.hemis is a persistent map of hemisphere names (‘lh’, ‘rh’, possibly others) for the given subject sub.

static image_dimensions(images)

sub.image_dimensions is a tuple of the size of an anatomical image for the given subject.

image_to_cortex(image, surface='midgray', hemi=None, affine=None, method=None, fill=0, dtype=None)
sub.image_to_cortex(image) is equivalent to the tuple
(sub.lh.from_image(image), sub.rh.from_image(image)).

sub.image_to_cortex(image, surface) uses the given surface (see also cortex.surface).

static images(imgs)

sub.images is a persistent map of MRImages tracked by the given subject sub.

static lh(hemis)

sub.lh is an alias for sub.hemis[‘lh’].

static lh_gray_indices(lh_gray_mask)

sub.lh_gray_indices is equivalent to numpy.where(sub.lh_gray_mask).

static lh_gray_mask(images)

sub.lh_gray_mask is an alias for sub.images[‘lh_gray_mask’].

static lh_vertex_to_voxel_heaviest_interpolation(lh_vertex_to_voxel_linear_interpolation)
sub.lh_gray_vertex_to_voxel_heaviest_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.lh_gray_indices.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel; the column in each row of the interpolation matrix with the highest weight is then given a value of 1 while all other rows are given values of 0. This is equivalent to performing nearest-neighbor interpolation while controlling for the depth of the voxel in the cortex.

static lh_vertex_to_voxel_linear_interpolation(lh_gray_indices, lh, image_dimensions, voxel_to_vertex_matrix)
sub.lh_gray_vertex_to_voxel_linear_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.lh_gray_indices.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel.

static lh_vertex_to_voxel_lines_interpolation(lh_gray_indices, lh, image_dimensions, vertex_to_voxel_matrix)
sub.lh_gray_vertex_to_voxel_lines_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.lh_gray_indices.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel.

static lh_vertex_to_voxel_nearest_interpolation(lh_gray_indices, lh, voxel_to_vertex_matrix)
sub.lh_gray_vertex_to_voxel_nearest_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.lh_gray_indices.

The method used is nearest-neighbors to either the closest pial or white surface vertex.

static lh_white_indices(lh_white_mask)

sub.lh_white_indices is a frozenset of the indices of the white voxels in the given subject’s lh, represented as 3-tuples.

static lh_white_mask(images)

sub.lh_white_mask is an alias for sub.images[‘lh_white_mask’].

static name(nm)

sub.name is the name of the subject sub.

static native_to_vertex_matrix(native_to_voxel_matrix, voxel_to_vertex_matrix)

sub.native_to_vertex_matrix is the affine transformation matrix that converts from the subject’s ‘native’ orientation to the vertex orientation.

static native_to_voxel_matrix(voxel_to_native_matrix)

sub.native_to_voxel_matrix is the inverse matrix of sub.voxel_to_native_matrix.

static path(p)

sub.path is the path of the subject’s data directory, if any.

path_join(*args)

sub.path_join(args…) is equivalent to os.path.join(sub.path, args…).

static repr(name, path)

sub.repr is the representation string returned by sub.__repr__().

static rh(hemis)

sub.rh is an alias for sub.hemis[‘rh’].

static rh_gray_indices(rh_gray_mask)

sub.rh_gray_indices is equivalent to numpy.where(sub.rh_gray_mask).

static rh_gray_mask(images)

sub.rh_gray_mask is an alias for sub.images[‘rh_gray_mask’].

static rh_vertex_to_voxel_heaviest_interpolation(rh_vertex_to_voxel_linear_interpolation)
sub.rh_gray_vertex_to_voxel_heaviest_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.rh_gray_indices.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel; the column in each row of the interpolation matrix with the highest weight is then given a value of 1 while all other rows are given values of 0. This is equivalent to performing nearest-neighbor interpolation while controlling for the depth of the voxel in the cortex.

static rh_vertex_to_voxel_linear_interpolation(rh_gray_indices, rh, image_dimensions, voxel_to_vertex_matrix)
sub.rh_gray_vertex_to_voxel_linear_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.rh_gray_indices.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel.

static rh_vertex_to_voxel_lines_interpolation(rh_gray_indices, rh, image_dimensions, vertex_to_voxel_matrix)
sub.rh_gray_vertex_to_voxel_lines_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.rh_gray_indices.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel.

static rh_vertex_to_voxel_nearest_interpolation(rh_gray_indices, rh, voxel_to_vertex_matrix)
sub.rh_gray_vertex_to_voxel_nearest_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.lh_gray_indices.

The method used is nearest-neighbors to either the closest pial or white surface vertex.

static rh_white_indices(rh_white_mask)

sub.rh_white_indices is a frozenset of the indices of the white voxels in the given subject’s rh, represented as 3-tuples.

static rh_white_mask(images)

sub.rh_white_mask is an alias for sub.images[‘rh_white_mask’].

static vertex_to_native_matrix(native_to_vertex_matrix)

sub.vertex_to_native_matrix is the inverse matrix of sub.native_to_vertex_matrix.

static vertex_to_voxel_linear_interpolation(lh_vertex_to_voxel_linear_interpolation, rh_vertex_to_voxel_linear_interpolation)
sub.rh_gray_vertex_to_voxel_linear_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.gray_indices. The vertex-values should be concatenated, LH values then RH values.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel.

static vertex_to_voxel_lines_interpolation(lh_vertex_to_voxel_lines_interpolation, rh_vertex_to_voxel_lines_interpolation)
sub.rh_gray_vertex_to_voxel_lines_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.gray_indices. The vertex-values should be concatenated, LH values then RH values.

The method works by projecting the vectors from the white surface vertices to the pial surface vertices into the the ribbon and weighting them by the fraction of the vector that lies in the voxel.

static vertex_to_voxel_matrix(voxel_to_vertex_matrix)

sub.vertex_to_voxel_matrix is the inverse matrix of sub.voxel_to_vertex_matrix.

static vertex_to_voxel_nearest_interpolation(lh_vertex_to_voxel_nearest_interpolation, rh_vertex_to_voxel_nearest_interpolation)
sub.rh_gray_vertex_to_voxel_nearest_interpolation is a scipy sparse matrix representing the
interpolation from the vertices into the voxels; the ordering of the voxels that is produced by the dot-product of this matrix with the vector of vertex-values is the same as the ordering used in sub.lh_gray_indices.

The method used is nearest-neighbors to either the closest pial or white surface vertex.

static voxel_to_native_matrix(mtx)

sub.voxel_to_vertex_matrix is the 4x4 affine transformation matrix that converts from a subject’s (0-indexed) voxel indices to that subject’s ‘native’ orientation; this is the orientation matrix used when exporting a subject’s images, and should be the orientation encoded in the subject’s image data.

static voxel_to_vertex_matrix(mtx)

sub.voxel_to_vertex_matrix is the 4x4 affine transformation matrix that converts from (i,j,k) indices in the subject’s image/voxel space to (x,y,z) coordinates in the subject’s cortical surface space.

static white_indices(lh_white_indices, rh_white_indices)

sub.white_indices is a frozenset of the indices of the white voxels in the given subject represented as 3-tuples.

neuropythy.retinotopy_data(m, source='any')
retinotopy_data(m) yields a dict containing a retinotopy dataset with the keys ‘polar_angle’,
‘eccentricity’, and any other related fields for the given retinotopy type; for example, ‘pRF_size’ and ‘variance_explained’ may be included for measured retinotopy datasets and ‘visual_area’ may be included for atlas or model datasets. The coordinates are always in the ‘visual’ retinotopy style, but can be reinterpreted with as_retinotopy.
retinotopy_data(m, source) may be used to specify a particular source for the data; this may be
either ‘empirical’, ‘model’, or ‘any’; or it may be a prefix/suffix beginning/ending with an _ character.
neuropythy.empirical_retinotopy_data(hemi, retino_type)

empirical_retinotopy_data(hemi, t) yields a numpy array of data for the given cortex object hemi and retinotopy type t; it does this by looking at the properties in hemi and picking out any combination that is commonly used to denote empirical retinotopy data. These common names are stored in _empirical_retintopy_names, in order of preference, which may be modified. The argument t should be one of ‘polar_angle’, ‘eccentricity’, ‘weight’.

neuropythy.predicted_retinotopy_data(hemi, retino_type)

predicted_retinotopy_data(hemi, t) yields a numpy array of data for the given cortex object hemi and retinotopy type t; it does this by looking at the properties in hemi and picking out any combination that is commonly used to denote empirical retinotopy data. These common names are stored in _predicted_retintopy_names, in order of preference, which may be modified. The argument t should be one of ‘polar_angle’, ‘eccentricity’, ‘visual_area’.

neuropythy.register_retinotopy(hemi, model='benson17', model_hemi=Ellipsis, polar_angle=None, eccentricity=None, weight=None, pRF_radius=None, weight_min=0.1, eccentricity_range=None, partial_voluming_correction=False, radius_weight=1, field_sign_weight=1, scale=1.0, sigma=Ellipsis, select='close', prior=None, resample=Ellipsis, radius=1.0471975511965976, max_steps=2000, max_step_size=0.05, method='random', yield_imap=False)
register_retinotopy(hemi) registers the given hemisphere object, hemi, to a model of V1, V2,
and V3 retinotopy, and yields a copy of hemi that is identical but additionally contains the registration ‘retinotopy’, whose coordinates are aligned with the model.

Registration attempts to align the vertex positions of the hemisphere’s spherical surface with a model of polar angle and eccentricity. This alignment proceeds through several steps and can be modified by several options. A description of these steps and options are provided here. For most cases, the default options should work relatively well.

Method:
  1. Prepare for registration by several intitialization substeps:
    1. Extract the polar angle, eccentricity and weight data from the hemisphere. These data are usually properties on the mesh and can be modifies by the options polar_angle, eccentricity, and weight, which can be either property names or list of property values. By default (None), a property is chosen using the functions neuropythy.vision.extract_retinotopy_argument with the default option set to ‘empirical’.
    2. If partial voluming correction is enabled (via the option partial_voluming_correction), multiply the weight by (1 - p) where p is hemi.partial_volume_factor.
    3. If there is a prior that is specified as a belief about the retinotopy, then a Registration is created for the hemisphere such that its vertices are arranged according to that prior (see also the prior option). Note that because hemi’s coordinates must always be projected into the registration specified by the model, the prior must be the name of a registration to which the model’s specified subject is also registered. This is clear in the case of an example. The default value for this is ‘retinotopy’; assuming that our model is specified on the fsaverage_sym, surface, the initial positions of the coordinates for the registration process would be the result of starting with hemi’s fsaverage_sym-aligned coordinates then warping these coordinates in a way that is equivalent to the warping from fsaverage_sym’s native spherical coordinates to fsaverage_sym’s retinotopy registration coordinates. Note that the retinotopy registration would usually be specified in a file in the fsaverage_sym subject’s surf directory: surf/lh.retinotopy.sphere.reg. If no prior is specified (option value None), then the vertices that are used are those aligned with the registration of the model, which will usually be ‘fsaverage’ or ‘fsaverage_sym’.
    4. If the option resample is not None, then the vertex coordinates are resampled onto either the fsaverage or fsaverage_sym’s native sphere surface. (The value of resample should be either ‘fsaverage’ or ‘fsaverage_sym’.) Resampling can prevent vertices that have been rearranged by alignment with the model’s specified registration or by application of a prior from beginning the alignment with very high initial gradients and is recommended for subject alignments. If resample is None then no changes are made.
    5. A 2D projection of the (possibly aligned, prior-warped, and resampled) cortical surface is made according to the projection parameters of the model. This map is the mesh that is warped to eventually fit the model.

  2. Perform the registration by running neuropythy.registration.mesh_register. This step consists of two major components.

    1. Create the potential function, which we will minimize. The potential function is a complex function whose inputs are the coordinates of all of the vertices and whose output is a potential value that increases both as the mesh is warped and as the vertices with retinotopy predictions get farther away from the positions in the model that their retinotopy values would predict they should lie. The balance of these two forces is best controlled by the option functional_scale. The potential function fundamentally consists of four terms; the first three describe mesh deformations and the last describes the model fit.

      • The edge deformation term is described for any vertices u and v that are connected by an edge in the mesh; it’s value is c/p (r(u,v) - r0(u,v))^2 where c is the edge_scale, p is the number of edges in the mesh, r(a,b) is the distance between vertices a and b, and r0(a,b) is the distance between a and b in the initial mesh.
      • The angle deformation term is described for any three vertices (u,v,w) that form an angle in the mesh; its value is c/m h(t(u,v,w), t0(u,v,w)) where c is the angle_scale argument, m is the number of angles in the mesh, t is the value of the angle (u,v,w), t0 is the value of the angle in the initial mesh, and h(t,t0) is an infinite-well function that asymptotes to positive infinity as t approaches both 0 and pi and is minimal when t = t0 (see the nben’s nben.mesh.registration.InfiniteWell documentation for more details).
      • The perimeter term prevents the perimeter vertices form moving significantly; this primarily prevents the mesh from wrapping in on itself during registration. The form of this term is, for any vertex u on the mesh perimeter, (x(u) - x0(u))^2 where x and x0 are the position and initial position of the vertex.
      • Finally, the functional term is minimized when the vertices best align with the retinotopy model.

    2. Register the mesh vertices to the potential function using the nben Java library. The particular parameters of the registration are method, max_steps, and max_step_size.

Options:
  • model specifies the instance of the retinotopy model to use; this must be an instance of the RegisteredRetinotopyModel class or a string that can be passed to the retinotopy_model() function (default: ‘standard’).
  • model_hemi specifies the hemisphere of the model; generally you shouldn’t have to set this unless you are using an fsaverage_sym model, in which case it should be set to None; in all other cases, the default value (Ellipsis) instructs the function to auto-detect the hemisphere.
  • polar_angle, eccentricity, pRF_radius, and weight specify the property names for the respective quantities; these may alternately be lists or numpy arrays of values. If weight is not given or found, then unity weight for all vertices is assumed. By default, each will check the hemisphere’s properties for properties with compatible names; it will prefer the properties PRF_polar_angle, PRF_ecentricity, and PRF_variance_explained if possible.
  • weight_min (default: 0.1) specifies the minimum value a vertex must have in the weight property in order to be considered as retinotopically relevant.
  • eccentricity_range (default: None) specifies that any vertex whose eccentricity is too low or too high should be given a weight of 0 in the registration.
  • partial_voluming_correction (default: True), if True, specifies that the value (1 - hemi.partial_volume_factor) should be applied to all weight values (i.e., weights should be down-weighted when likely to be affected by a partial voluming error).
  • field_sign_weight (default: 1) indicates the relative weight (between 0 and 1) that should be given to the field-sign as a method of determining which anchors have the strongest springs. A value of 1 indicates that the effective weights of anchors should be the geometric mean of the empirical retinotopic weight and field-sign-based weight; a value of 0 indicates that no attention should be paid to the field sign weight.
  • radius_weight (default: 1) indicates the relative weight (between 0 and 1) that should be given to the pRF radius as a method of determining which anchors have the strongest springs. A value of 1 indicates that the effective weights of anchors should be the geometric mean of the empirical retinotopic weight and pRF-radius-based weight; a value of 0 indicates that no attention should be paid to the radius-based weight.
  • sigma specifies the standard deviation of the Gaussian shape for the Schira model anchors; see retinotopy_anchors for more information.
  • scale (default: 1.0) specifies the strength of the functional constraints (i.e. the anchors: the part of the minimization responsible for ensuring that retinotopic coordinates are aligned); the anatomical constraints (i.e. the edges and angles: the part of the minimization responsible for ensuring that the mesh is not overly deformed) are always held at a strength of 1.0.
  • select specifies the select option that should be passed to retinotopy_anchors.
  • max_steps (default 8,000) specifies the maximum number of registration steps to run.
  • max_step_size (default 0.05) specifies the maxmim distance a single vertex is allowed to move in a single step of the minimization.
  • method (default ‘random’) is the method argument passed to mesh_register. This should be ‘random’, ‘pure’, or ‘nimble’. Generally, ‘random’ is recommended.
  • yield_imap (default: False) specifies whether the return value should be the new Mesh object or a pimms imap (i.e., a persistent mapping of the result of a pimms calculation) containing the meta-data that was used during the registration calculations. If this is True, then register_retinotopy will return immediately, and calculations will only be performed as the relevant data are requested from the returned imap. The item ‘predicted_mesh’ gives the return value when yield_imap is set to False.
  • radius (default: pi/3) specifies the radius, in radians, of the included portion of the map projection (projected about the occipital pole).
  • sigma (default Ellipsis) specifies the sigma argument to be passed onto the retinotopy_anchors function (see help(retinotopy_anchors)); the default value, Ellipsis, is interpreted as the default value of the retinotopy_anchors function’s sigma option.
  • prior (default: None) specifies the prior that should be used, if found, in the topology registrations for the subject associated with the retinotopy_model’s registration.
  • resample (default: Ellipsis) specifies that the data should be resampled to one of the uniform meshes, ‘fsaverage’ or ‘fsaverage_sym’, prior to registration; if None then no resampling is performed; if Ellipsis, then auto-detect either fsaverage or fsaverage_sym based on the model_hemi option (if it is None, fsaverage_sym, else fsaverage).
neuropythy.retinotopy_anchors(mesh, mdl, polar_angle=None, eccentricity=None, weight=None, weight_min=0.1, field_sign_weight=0, field_sign=None, radius_weight=0, radius_weight_source='Wandell2015', radius=None, model_field_sign=None, model_hemi=Ellipsis, scale=1, shape='Gaussian', suffix=None, sigma=[0.1, 2.0, 8.0], select='close')

retinotopy_anchors(mesh, model) is intended for use with the mesh_register function and the retinotopy_model() function and/or the RetinotopyModel class; it yields a description of the anchor points that tie relevant vertices the given mesh to points predicted by the given model object. Any instance of the RetinotopyModel class should work as a model argument; this includes SchiraModel objects as well as RetinotopyMeshModel objects such as those returned by the retinotopy_model() function. If the model given is a string, then it is passed to the retinotopy_model() function first.

Options:
  • polar_angle (default None) specifies that the given data should be used in place of the ‘polar_angle’ or ‘PRF_polar_angle’ property values. The given argument must be numeric and the same length as the the number of vertices in the mesh. If None is given, then the property value of the mesh is used; if a list is given and any element is None, then the weight for that vertex is treated as a zero. If the option is a string, then the property value with the same name isused as the polar_angle data.
  • eccentricity (default None) specifies that the given data should be used in places of the ‘eccentricity’ or ‘PRF_eccentricity’ property values. The eccentricity option is handled virtually identically to the polar_angle option.
  • weight (default None) specifies that the weight or scale of the data; this is handled generally like the polar_angle and eccentricity options, but may also be 1, indicating that all vertices with polar_angle and eccentricity values defined will be given a weight of 1. If weight is left as None, then the function will check for ‘weight’, ‘variance_explained’, ‘PRF_variance_explained’, and ‘retinotopy_weight’ values and will use the first found (in that order). If none of these is found, then a value of 1 is assumed.
  • weight_min (default 0) specifies that the weight must be higher than the given value inn order to be included in the fit; vertices with weights below this value have their weights truncated to 0.
  • scale (default 1) specifies a constant by which to multiply all weights for all anchors; the value None is interpreted as 1.
  • shape (default ‘Gaussian’) specifies the shape of the potential function (see mesh_register)
  • model_hemi (default: None) specifies the hemisphere of the model to load; if None, then looks for a non-specific model.
  • suffix (default None) specifies any additional arguments that should be appended to the potential function description list that is produced by this function; i.e., the retinotopy_anchors function produces a list, and the contents of suffix, if given and not None, are appended to that list (see mesh_register).
  • select (default ‘close’) specifies a function that will be called with two arguments for every vertex given an anchor; the arguments are the vertex label and the matrix of anchors. The function should return a list of anchors to use for the label (None is equivalent to lambda id,anc: anc). The parameter may alternately be specified using the string ‘close’: select=[‘close’, [k]] indicates that any anchor more than k times the average edge-length in the mesh should be excluded; a value of just [‘close’, k] on the other hand indicates that any anchor more than k distance from the vertex should be exlcuded. The default value, ‘close’, is equivalent to [‘close’, [40]].
  • sigma (default [0.1, 2.0, 4.0]) specifies how the sigma parameter should be handled; if None, then no sigma value is specified; if a single number, then all sigma values are assigned that value; if a list of three numbers, then the first is the minimum sigma value, the second is the fraction of the minimum distance between paired anchor points, and the last is the maximum sigma — the idea with this form of the argument is that the ideal sigma value in many cases is approximately 0.25 to 0.5 times the distance between anchors to which a single vertex is attracted; for any anchor a to which a vertex u is attracted, the sigma of a is the middle sigma-argument value times the minimum distance from a to all other anchors to which u is attracted (clipped by the min and max sigma).
  • field_sign_weight (default: 0) specifies the amount of weight that should be put on the retinotopic field of the model as a method of attenuating the weights on those anchors whose empirical retinotopic values and predicted model locations do not match. The weight that results is calculated from the difference in empirical field-sign for each vertex and the visual area field sign based on the labels in the model. The higher the field-sign weight, (approaching 1) the more the resulting value is a geometric mean of the field-sign-based weight and the original weights. As this value approaches 0, the resulting weights are more like the original weights.
  • radius_weight (default: 0) specifies the amount of weight that should be put on the receptive field radius of the model as a method of attenuating the weights on those anchors whose empirical retinotopic values and predicted model locations do not match. The weight that results is calculated from the difference in empirical RF radius for each vertex and the predicted RF radius based on the labels in the model. The higher the radius weight, (approaching 1) the more the resulting value is a geometric mean of the field-sign-based weight and the original weights. As this value approaches 0, the resulting weights are more like the original weights.
  • radius_weight_source (default: ‘Wandell2015’) specifies the source for predicting RF radius; based on eccentricity and visual area label.
Example:

# The retinotopy_anchors function is intended for use with mesh_register, as follows: # Define our Schira Model: model = neuropythy.registration.SchiraModel() # Make sure our mesh has polar angle, eccentricity, and weight data: mesh.prop(‘polar_angle’, polar_angle_vertex_data); mesh.prop(‘eccentricity’, eccentricity_vertex_data); mesh.prop(‘weight’, variance_explained_vertex_data); # register the mesh using the retinotopy and model: registered_mesh = neuropythy.registration.mesh_register(

mesh, [‘mesh’, retinotopy_anchors(mesh, model)], max_step_size=0.05, max_steps=2000)
neuropythy.retinotopy_model(name='benson17', hemi=None, radius=1.2566370614359172, sphere_radius=100.0, search_paths=None, update=False)

retinotopy_model() yields a standard retinotopy model of V1, V2, and V3 as well as other areas (depending on the options). The model itself is represented as a RegisteredRetinotopyModel object, which may internally store a set of meshes with values at the vertices that define the polar angle and eccentricity, or as another object (such as with the SchiraModel). The mesh models are loaded from files in the neuropythy lib directory. Because the model’s class is RegisteredRetinotopyModel, so the details of the model’s 2D projection onto the cortical surface are included in the model.

The following options may be given:
  • name (default: ‘benson17’) indicates the name of the model to load; the Benson17 model is included with the neuropythy library along with various others. If name is a filename, this file is loaded (must be a valid fmm or fmm.gz file). Currently, models that are included with neuropythy are: Benson17, Benson17-uncorrected, Schira10, and Benson14 (which is identical to Schira10, as Schira10 was used by Benson14).
  • hemi (default: None) specifies that the model should go with a particular hemisphere, either ‘lh’ or ‘rh’. Generally, model files are names lh.<model>.fmm.gz or rh.<model>.fmm.gz, but models intended for the fsaverage_sym don’t necessarily get a prefix. Note that you can leave this as none and just specify that the model name is ‘lh.model’ instead.
  • radius, sphere_radius (defaults: pi/2.5 and 100.0, respectively) specify the radius of the projection (on the surface of the sphere) and the radius of the sphere (100 is the radius for Freesurfer spheres). See neuropythy.registration.load_fmm_model for mode details.
  • search_paths (default: None) specifies directories in which to look for fmm model files. No matter what is included in these files, the neuropythy library’s folders are searched last.
neuropythy.neighborhood_cortical_magnification(mesh, coordinates)

neighborhood_cortical_magnification(mesh, visual_coordinates) yields a list of neighborhood- based cortical magnification values for the vertices in the given mesh if their visual field coordinates are given by the visual_coordinates matrix (must be like [x_values, y_values]). If either x-value or y-value of a coordinate is either None or numpy.nan, then that cortical magnification value is numpy.nan.

neuropythy.as_retinotopy(data, output_style='visual', units=Ellipsis, prefix=None, suffix=None)
as_retinotopy(data) converts the given data, if possible, into a 2-tuple, (polar_angle, eccen),
both in degrees, with 0 degrees of polar angle corresponding to the upper vertical meridian and negative values corresponding to the left visual hemifield.
as_retinotopy(data, output_style) yields the given retinotopy data in the given output_style;
as_retinotopy(data) is equivalent to as_retinotopy(data, ‘visual’).

This function is intended as a general conversion routine between various sources of retinotopy data. All lookups are done in a case insensitive manner. Data may be specified in any of the following ways:

  • A cortical mesh containing recognized properties (such as ‘polar_angle’ and ‘eccentricity’ or ‘latitude’ and ‘longitude’.
  • A dict with recognized fields.
  • A tuple of (polar_angle, eccentricity) (assumed to be in ‘visual’ style).
  • A numpy vector of complex numbers (assumed in ‘complex’ style).
  • An n x 2 or 2 x n matrix whose rows/columns are (polar_angle, eccentricity) values (assumed in ‘visual’ style).
The following output_styles are accepted:
  • ‘visual’: polar-axis: upper vertical meridian
    positive-direction: clockwise fields: [‘polar_angle’ (degrees), ‘eccentricity’ (degrees)]
  • ‘spherical’: polar-axis: right horizontal meridian
    positive-direction: counter-clockwise fields: [‘theta’ (radians), ‘rho’ (radians)]
  • ‘standard’: polar-axis: right horizontal meridian
    positive-direction: counter-clockwise fields: [‘angle’ (radians), ‘eccentricity’ (degrees)]
  • ‘cartesian’: axes: x/y correspond to RHM/UVM
    positive-direction: left/up fields: (‘x’ (radians), ‘y’ (radians))
  • ‘geographical’: axes: x/y correspond to RHM/UVM
    positive-direction: left/up fields: (‘longitude’ (degrees), ‘latitude’ (degrees))
  • ‘complex’: axes: x/y correspond to RHM/UVM
    positive-direction: left/up fields: longitude (degrees) + I*latitude (degrees)
  • ‘complex-rad’: axes: x/y correspond to RHM/UVM
    positive-direction: left/up fields: longitude (radians) + I*latitude (radians)
  • ‘visual-rad’: polar-axis: upper vertical meridian
    positive-direction: clockwise fields: [‘angle’ (radians), ‘eccentricity’ (radians)]
The following options may be given:
  • units (Ellipsis) specifies the unit that should be assumed (degrees or radians); if Ellipsis is given, then auto-detect the unit if possible. This may be a map whose keys are ‘polar_angle’ and ‘eccentricity’ (or the equivalent titles in data) and whose keys are the individual units.
  • prefix (None) specifies a prefix that is required for any keys or property names.
  • suffix (None) specifies a suffix that is required for any keys or property names.
neuropythy.freesurfer_subject(name)

subject(name) yields a freesurfer Subject object for the subject with the given name. Subjects are cached and not reloaded. Note that subects returned by freesurfer_subject() are always persistent Immutable objects; this means that you must create a transient version of the subject to modify it via the member function sub.transient(). Better, you can make copies of the objects with desired modifications using the copy method.

neuropythy.to_mgh(obj, like=None, header=None, affine=None, extra=Ellipsis)
to_mgh(obj) yields an MGHmage object that is as equivalent as possible to the given object obj.
If obj is an MGHImage already and no changes are requested, then it is returned unmolested; otherwise, the optional arguments can be used to edit the header, affine, and exta.
The following options are accepted:
  • like (default: None) may be provided to give a guide for the various header- and meta-data that is included in the image. If this is a nifti image object, its meta-data are used; if this is a subject, then the meta-data are deduced from the subject’s voxel and native orientation matrices. All other specific options below override anything deduced from the like argument.
  • header (default: None) may be a Nifti1 or Niti2 image header to be used as the nifti header or to replace the header in a new image.
  • affine (default: None) may specify the affine transform to be given to the image object.
  • extra (default: Ellipsis) may specify an extra mapping for storage with the image data; the default value Ellipsis indicates that such a mapping should be left as is if it already exists in the obj or in the like option and should otherwise be empty.

Indices and tables