README.md

dag_prf_utils repository

This repository is a collection of useful tools (mainly) for analysing and visualising PRF data. It is designed to work with prfpy

Credit due to many people - (TODO: do this properly)

Much stolen from:

Jurjen Heij; https://github.com/gjheij/linescanning Nibabel Nilearn Pycortex prfpy (of course)

In active development

This package is still in development and its API might change.

Installation

Basic setup - you'll need to add prfpy or whatever is compatible

Just run the usual

pip install -e .

Full setup - download some of my other packages / forks of other peoples stuff

[1] Create a new environment

conda create -n env_name ipython

[2] Activate the environment

conda activate env_name

[3] Setup your config file

Do you want to install the other git packages? Do you want to install using pip, conda or mamba? Set all of that here

[4] Run the install script. This will also download some other useful tools.

bash shell/dpu_setup setup

Overview of files

cmap_functions

Ways of interacting with matplotib cmaps, making your own custom cmaps etc. Could be useful if you want to plot specific things on the surface. Stores custom cmaps in "cmaps.json". You can use this for plotting in python, but also in freesurfer for making overlays.

utils

Mainly generic tools - for searching for files, some mathematical stuff which comes up again and again in PRF analyses (converting between cartesian and polar coordinates etc; calculating rsq...).

prfpy_functions

In addition there are a couple of prfpy specific tools, i.e., Prf1T1M, etc., which are designed to load the outputs of prfpy models and hold them in easily manipulatable ways.

plot functions

Several functions useful for plotting PRF properties around the visual field. All focus on matplotlib

surface plotting and meshes

I have collected together a bunch of wrapper functions to make it easier to plot data on the cortical surface. This will of course require that you have surface data (i.e., run freesurfer); and any data you want to plot will need to be in a vertex wise format.

In my experience different tools are useful for different things.

• freeview -> best for drawing ROIs. Also for those who want to do things quickly; and aren't interested into digging deeply into python / various dependencies. Keeps it simple(-ish)

• pycortex -> most beautiful (and probably the best in general) many ways to easily flip between different surfaces

For the nerdiest of nerds...

• plotly -> Allows to be saved as simple .html files. Can be nice to send to participants, a copy of their brains which they can scroll through very simply. Possibility of creating app-like interactions with Dash and flask...
• .ply format -> put everything into one relatively low memory file
• blender -> again, some intense nerdery here. A great way to waste your time.

For all these methods it is important to think about:

• mesh: what is the mesh being used (it will mainly be 'inflated' or 'pial'). What is the actual shape that you want to look at
• data: what do you want to plot on the mesh (e.g., polar angle, eccentricity. needs to be vertex wise). What colormap do you want to use. What mask do you want to use? (binary, only plot data for PRFs above a certain rsquared?; or do you want to weight the transparency of the data by a certain factor (again possibly rsquared),or some combination
• colormaps (all of those from matplotlib. Also options to create your own using my cmap tools)
• 'under_surface': if you are masking some of the data, what do you want to be shown in the gaps? Maybe the curvature of the cortex? Depth?

With this in mind here are a summary of some of the options.

Freeview based surface plotting

• requires freeview
• Specify the data, the mesh, and the mask (you can only use binary masking, the option for varying the transparency is not available here).
• scripts will create a custom surf file, and the command (which contains the colormap info) to open it in freeview
• The colormap can be anything from matplotlib (or one of your own). Just specify the min and max values.
• You can also specify the camera angle for when freeview opens, and ask it to automatically take a picture of the surface. This can be useful if you want to iterate through several subjects/surface plots and save the figures as pngs, but can't be bothered to sit and click again and again...

Pycortex

• A basic wrapper for pycortex (largely stolen from Jurjen Heij linescanning toolbox).
• Can use arbitrary colormaps. Also plot ROIs directly from freesurfer
• Option to save to files which can be opened any time straight away

Plotly format

• requires plotly library. And maybe dash if you want to dig into that
• can do all the basics (interactive surfaces, colored as you wish )
• can also plot inline with a notebook

Blender

• requires freesurfer and blender
• The script will load the inflated and pial mesh, with the option to slide between the 2 (i.e. customize how inflated you want the surface to be)
• You can load several colormaps at once, and flip between them
• If you are feeling adventurous, you can even create an animation over time, (e.g., plot timecourse info on the surface). This is a bit experimental, and may take up a lot of data and computing power. I haven't fully explored it.

For blender you can install using: https://www.blender.org/download/ For meshlab you can install using: https://www.meshlab.net/#download

Generic .ply format

• requires freesurfer
• Specify the data, the mesh, and the mask (including an option for variable transparency).
• can create a single .ply file (per hemisphere), which contains all the information about the mesh (vx coordinates, face id); the data values for each vertex, and a color value for each vertex (determined by the data, and specified colormap).
• This can be opened by most 3D viewing software (e.g., meshlab, blender)...

In active development

Stuff may well change.