4.1. cfmap package

4.1.1. cfmap.CF_mapping module

cfmap.CF_mapping.optimize_connfield_dfree(gf, r2_threshold=0.05, sigma_bounds=[(0.1, 20.0)], method='L-BFGS-B', tol=0.001, verbose=True)[source]

Optimize connective field parameters using BFGS starting from grid search results. Only optimizes sigma while keeping vertex center fixed (standard CF approach).

Parameters:

  • gf (CFFitter) – The CFFitter object after grid_fit has been run

  • r2_threshold (float) – R² threshold for optimization (default 0.05)

  • verbose (bool) – Print progress information

Returns:

Contains optimized parameters:

  • ’vertex_indices’: Fixed vertex centers from grid search

  • ’sigma’: Optimized sigma values

  • ’beta’: Optimized beta (amplitude) values

  • ’baseline’: Optimized baseline values

  • ’r2’: r2 values for optimized fits

Return type:

dict

cfmap.CF_mapping.optimize_connfield_gdescent(gf, r2_threshold=0.05, sigma_bounds=(0.1, 20.0), learning_rate=0.01, max_iterations=1000, convergence_threshold=0.0001, batch_size=128, verbose=True)[source]

GPU-accelerated PARALLEL CF optimization using TensorFlow.

cfmap.CF_mapping.optimize_connfield_joint(gf, r2_threshold=0.05, sigma_bounds=(0.1, 20.0), max_outer_iterations=3, max_inner_iterations=300, search_radius=10.0, batch_size=256, learning_rate=0.01, verbose=True)[source]

GPU-parallelized alternating position-sigma optimization.

Processes multiple sites in parallel on GPU for both: 1. Position search (vectorized evaluation) 2. Sigma optimization (batched gradient descent)

Returns:

Contains optimized parameters and cycle-wise statistics

Return type:

dict

cfmap.CF_mapping.plot_convergence_summary_table(cycle_stats)[source]

Create a summary table of convergence statistics.

cfmap.CF_mapping.compare_cf_results(results_A, results_B, ecc_pRF, pol_pRF, target_roi_mask, flatmaps, colors_ecc, colors_polar, h='lh', r2_threshold=0.1, ecc_div=2, figsize=(16, 8), dpi=300)[source]

Compare connective field results from grid search vs optimization.

Parameters:

  • results_A (dict) – Dictionary with keys ‘centers’, ‘sigma’, ‘r2’

  • results_B (dict) – Dictionary with keys ‘centers’, ‘sigma’, ‘r2’

  • ecc_pRF (np.array) – Eccentricity values for source vertices

  • pol_pRF (np.array) – Polar angle values for source vertices

  • sub_target_mask (np.array) – Boolean mask for target vertices

  • flatmaps (dict) – Dictionary of flatmap objects

  • colors_ecc (dict) – Eccentricity color palette

  • colors_polar (dict) – Polar angle color palette

  • h (str) – Hemisphere (‘lh’ or ‘rh’)

  • r2_threshold (float) – R² threshold for visualization

  • figsize (tuple) – Figure size

  • dpi (int) – Figure DPI

Returns:

Comparison figure

Return type:

matplotlib.figure.Figure

4.1.2. cfmap.color_palettes module

cfmap.color_palettes.get_color_palettes()[source]

Returns color palettes for eccentricity and polar angle mappings.

Returns:

Dictionary containing eccentricity and polar palettes in various formats

Return type:

dict

4.1.3. cfmap.pRF_processing module

cfmap.pRF_processing.plot_prf_maps(prf_results, flatmaps, colors_ecc, colors_polar, h, max_sigma=3, r2_threshold=0.15)[source]

Plots pRF parameter maps (eccentricity, polar angle, sigma, and R²) on a cortical flatmap.

Parameters:

  • prf_results (pd.DataFrame) – DataFrame containing pRF parameters with columns ‘x’, ‘y’, ‘sd’, ‘r2’.

  • flatmaps (dict) – Dictionary of flatmaps for hemispheres, e.g., flatmaps[h].

  • colors_ecc (dict) – Color palette for eccentricity with ‘matplotlib_cmap’ and ‘hex’ keys.

  • colors_polar (dict) – Color palette for polar angle with ‘matplotlib_cmap’ and ‘hex’ keys.

  • h (str) – Hemisphere identifier, e.g., ‘lh’ or ‘rh’.

  • max_sigma (float, optional) – Maximum sigma value for colorbar scaling (default: 3).

  • r2_threshold (float, optional) – R² threshold for alpha scaling (default: 0.15).

Returns:

fig – The created figure object.

Return type:

matplotlib.figure.Figure

cfmap.pRF_processing.plot_prf_histograms(x, y, sigma, total_rsq, r2_threshold=0.0, ylims=None, xlims=None, bins=200)[source]

Plot histograms of pRF parameters.

Parameters:

  • x (array_like) – X coordinates of pRF centers.

  • y (array_like) – Y coordinates of pRF centers.

  • sigma (array_like) – pRF size values.

  • total_rsq (array_like) – R² values.

  • r2_threshold (float, optional) – Minimum R² to include (default: 0.0).

  • ylims (list of tuples, optional) – List of 4 tuples for y-axis limits [(y0_min, y0_max), (y1_min, y1_max), …].

  • xlims (list of tuples, optional) – List of 4 tuples for x-axis limits [(x0_min, x0_max), (x1_min, x1_max), …].

  • bins (int or list, optional) – Number of bins or list of 4 bin specifications (default: 200).

Returns:

fig – The created figure object.

Return type:

matplotlib.figure.Figure

cfmap.pRF_processing.plot_roi_retMap(ecc_map, pol_map, mask, titles, flatmaps, colors_ecc, colors_polar, h)[source]

Plots eccentricity and polar angle maps on a cortical flatmap.

Parameters:

  • ecc_map (array_like) – Eccentricity values for each vertex.

  • pol_map (array_like) – Polar angle values for each vertex.

  • mask (array_like) – Boolean mask to apply to the plots.

  • titles (list of str) – List containing two title strings for eccentricity and polar angle plots.

  • flatmaps (dict) – Dictionary of flatmaps for hemispheres.

  • colors_ecc (dict) – Color palette for eccentricity.

  • colors_polar (dict) – Color palette for polar angle.

  • h (str) – Hemisphere identifier (e.g., ‘lh’ or ‘rh’).