gemprf 0.1.1__tar.gz

gemprf-0.1.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023-2025, Siddharth Mittal, Medical University of Vienna
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

gemprf-0.1.1/MANIFEST.in

@@ -0,0 +1,22 @@
+# Include package data (ONLY specify the non-python files that need to be included)
+# Include config files
+recursive-include gem/configs *.xml *.h5
+
+# Include CUDA kernels
+recursive-include gem/kernels *.cu *.ptx
+
+# Exclude tests and test data
+recursive-exclude gem/tests *
+recursive-exclude gem/tests/temp *
+recursive-exclude gem/tests/testdata *
+
+# Exclude cache and compiled artifacts
+recursive-exclude gem/__pycache__ *
+recursive-exclude __pycache__ *
+recursive-exclude gem/**/*.pyc
+recursive-exclude gem/**/*.pyo
+recursive-exclude gem/**/*.nbc
+recursive-exclude gem/**/*.nbi
+
+# Misc OS garbage
+exclude .DS_Store

gemprf-0.1.1/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: gemprf
+Version: 0.1.1
+Summary: A Python library for population receptive field (pRF) analysis
+Author-email: Siddharth Mittal <siddharth.mittal@meduniwien.ac.at>
+License: BSD 3-Clause License
+Project-URL: Homepage, https://gemprf.github.io/
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h5py==3.13.0
+Requires-Dist: joblib==1.4.2
+Requires-Dist: matplotlib==3.10.1
+Requires-Dist: nibabel==5.3.2
+Requires-Dist: numba==0.61.0
+Requires-Dist: numba_kdtree==0.6.0
+Requires-Dist: numpy==2.1.3
+Requires-Dist: nvidia_ml_py==12.570.86
+Requires-Dist: pandas==2.2.3
+Requires-Dist: pynvml==12.0.0
+Requires-Dist: scipy==1.15.2
+Requires-Dist: xmltodict==0.14.2
+Dynamic: license-file
+
+Welcome to **GEM-pRF** - a standalone, plug-and-play software for population receptive field (pRF) mapping, designed for **large-scale data analysis with high accuracy**.
+
+
+To understand the theoretical foundations and details of how the software works, please refer to our paper: 👉[Mittal et al (2025), ](https://www.biorxiv.org/content/10.1101/2025.05.16.654560v1)*[GEM-pRF: GPU-Empowered Mapping of Population Receptive Fields for Large-Scale fMRI Analysis](https://www.biorxiv.org/content/10.1101/2025.05.16.654560v1)*
+
+
+## Documentation
+
+An official documentation is coming soon ([GEM-pRF documentation link](https://gemprf.github.io/))! Meanwhile, to get the mathematical foundation of the software, you may refer to the [GEM-pRF paper](https://www.biorxiv.org/content/10.1101/2025.05.16.654560v1).
+
+
+## Installation
+
+GEM-pRF requires the GPU access for the data processing. At the moment, GEM uses CUDA libraries to acess/process data on NVIDIA GPUs.
+
+> \[!WARNING\]
+>
+> Please check your system has compatible NVIDIA GPU available.
+
+### Step-by-Step Guide
+
+**Step 1. Install dependencies**
+
+* Create or activate your preferred Python/Conda environment.
+* Install all required dependencies listed in `requirements.txt`:
+
+```bash
+pip install -r requirements.txt
+```
+
+
+**Step 2. Download GEM-pRF code**
+
+* Clone the repository:
+
+```bash
+git clone https://github.com/siddmittal/GEMpRF.git
+cd GEMpRF
+```
+
+
+## Running GEM-pRF
+
+
+> \[!CAUTION\]
+> Before proceeding, make sure to install the required python dependencies as specified in the `requirements.txt` file
+
+GEM-pRF is written as a **standalone software**. It comes with an XML configuration file. Once you configure your XML file (see [sample config](https://github.com/siddmittal/GEMpRF/blob/main/gem/configs/analysis_configs/analysis_config.xml)), you can directly run the software.
+
+### 🔹 **Option A: Run from terminal**
+
+
+
+
+1. Open a terminal (e.g. Anaconda Prompt).
+2. Activate the environment with the dependencies installed.
+3. Navigate to the GEM-pRF folder.
+4. Run:
+
+   ```bash
+   python run_gem.py PATH_TO_YOUR_XML_CONFIG_FILE
+   ```
+
+
+### 🔹 **Option B: Run from IDE (e.g. VS Code)**
+
+
+
+
+1. Open the downloaded GEM-pRF folder in VS Code.
+2. Edit the `run_gem.py` script to specify the path to your XML config file.
+3. Run the script directly from the IDE.
+
+

gemprf-0.1.1/README.md

@@ -0,0 +1,74 @@
+Welcome to **GEM-pRF** - a standalone, plug-and-play software for population receptive field (pRF) mapping, designed for **large-scale data analysis with high accuracy**.
+
+
+To understand the theoretical foundations and details of how the software works, please refer to our paper: 👉[Mittal et al (2025), ](https://www.biorxiv.org/content/10.1101/2025.05.16.654560v1)*[GEM-pRF: GPU-Empowered Mapping of Population Receptive Fields for Large-Scale fMRI Analysis](https://www.biorxiv.org/content/10.1101/2025.05.16.654560v1)*
+
+
+## Documentation
+
+An official documentation is coming soon ([GEM-pRF documentation link](https://gemprf.github.io/))! Meanwhile, to get the mathematical foundation of the software, you may refer to the [GEM-pRF paper](https://www.biorxiv.org/content/10.1101/2025.05.16.654560v1).
+
+
+## Installation
+
+GEM-pRF requires the GPU access for the data processing. At the moment, GEM uses CUDA libraries to acess/process data on NVIDIA GPUs.
+
+> \[!WARNING\]
+>
+> Please check your system has compatible NVIDIA GPU available.
+
+### Step-by-Step Guide
+
+**Step 1. Install dependencies**
+
+* Create or activate your preferred Python/Conda environment.
+* Install all required dependencies listed in `requirements.txt`:
+
+```bash
+pip install -r requirements.txt
+```
+
+
+**Step 2. Download GEM-pRF code**
+
+* Clone the repository:
+
+```bash
+git clone https://github.com/siddmittal/GEMpRF.git
+cd GEMpRF
+```
+
+
+## Running GEM-pRF
+
+
+> \[!CAUTION\]
+> Before proceeding, make sure to install the required python dependencies as specified in the `requirements.txt` file
+
+GEM-pRF is written as a **standalone software**. It comes with an XML configuration file. Once you configure your XML file (see [sample config](https://github.com/siddmittal/GEMpRF/blob/main/gem/configs/analysis_configs/analysis_config.xml)), you can directly run the software.
+
+### 🔹 **Option A: Run from terminal**
+
+
+
+
+1. Open a terminal (e.g. Anaconda Prompt).
+2. Activate the environment with the dependencies installed.
+3. Navigate to the GEM-pRF folder.
+4. Run:
+
+   ```bash
+   python run_gem.py PATH_TO_YOUR_XML_CONFIG_FILE
+   ```
+
+
+### 🔹 **Option B: Run from IDE (e.g. VS Code)**
+
+
+
+
+1. Open the downloaded GEM-pRF folder in VS Code.
+2. Edit the `run_gem.py` script to specify the path to your XML config file.
+3. Run the script directly from the IDE.
+
+

gemprf-0.1.1/gem/__init__.py

@@ -0,0 +1,10 @@
+from . import model
+from .model import *
+
+from . import tools
+from .tools import *
+
+from . import space
+from .space import *
+
+from .run_gem import run

gemprf-0.1.1/gem/analysis/__init__.py

@@ -0,0 +1,6 @@
+class my_class(object):
+    pass
+
+
+
+

gemprf-0.1.1/gem/analysis/prf_analysis.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+"""
+
+"@Author  :   Siddharth Mittal",
+"@Version :   1.0",
+"@Contact :   siddharth.mittal@meduniwien.ac.at",
+"@License :   (C)Copyright 2024, Medical University of Vienna",
+"@Desc    :   None",
+        
+"""
+
+import numpy as np
+import cupy as cp
+from typing import List
+
+from gem.model.prf_model import PRFModel
+from gem.model.selected_prf_model import SelectedPRFModel
+from gem.model.prf_stimulus import Stimulus
+from gem.space.PRFSpace import PRFSpace
+from gem.utils.hpc_cupy_utils import HpcUtils as gpu_utils
+
+  
+class PRFAnalysis():
+    def __init__(self, prf_space : PRFSpace, stimulus : Stimulus) -> None:
+        self.__prf_points = prf_space
+        self.__stimulus = stimulus
+        self.__model_signals_batches = None
+        self.__dervatives_signals_batches_list = None
+        self.__error_e = None
+        self.__error_de_dtheta_list = None # contains a list of all derivative errors w.r.t each parameter
+
+    @property
+    def prf_points(self)-> PRFSpace:
+        return self.__prf_points
+
+    @property
+    def stimulus(self)-> Stimulus:
+        return self.__stimulus
+
+    @property
+    def orthonormalized_S_batches(self)-> List[cp.ndarray]:
+        return self.__model_signals_batches
+    
+    @orthonormalized_S_batches.setter
+    def orthonormalized_S_batches(self, new_value)-> None:
+        self.__model_signals_batches = new_value
+
+    @property
+    def orthonormalized_dS_dtheta_batches_list(self)-> List[List[cp.ndarray]]:
+        return self.__dervatives_signals_batches_list
+    
+    @orthonormalized_dS_dtheta_batches_list.setter
+    def orthonormalized_dS_dtheta_batches_list(self, new_value)-> None:
+        self.__dervatives_signals_batches_list = new_value
+
+    @property
+    def error_e(self)-> cp.ndarray:
+        return self.__error_e
+    
+    @error_e.setter
+    def error_e(self, new_value)-> None:
+        self.__error_e = new_value
+
+    @property
+    def error_de_dtheta_list(self)-> List[cp.ndarray]:
+        return self.__error_de_dtheta_list
+    
+    @error_de_dtheta_list.setter
+    def error_de_dtheta_list(self, new_value)-> None:
+        self.__error_de_dtheta_list = new_value
+
+    

gemprf-0.1.1/gem/analysis/prf_r2_variance_explain.py

@@ -0,0 +1,101 @@
+import numpy as np
+import cupy as cp
+from gem.tools.json_file_operations import JsonMgr
+from gem.utils.hpc_cupy_utils import HpcUtils as Utils
+from gem.model import prf_model
+from gem.signals.signal_synthesizer import SignalSynthesizer
+from gem.model.prf_model import GaussianModelParams
+from gem.utils.gem_gpu_manager import GemGpuManager as ggm
+
+class R2:
+    @classmethod
+    def get_r2_new_method_with_epsilon_as_Fx(cls, Y_signals_gpu, O_gpu, epsilon_results_cpu):    
+        r2 = []
+        R_Rt_gpu = cp.eye(O_gpu.shape[0]) - O_gpu
+
+        num_y_signals = len(epsilon_results_cpu)
+        for yIdx in range (num_y_signals):
+            y = Y_signals_gpu[:, yIdx]
+            yty = y.T @ y
+            ystar = O_gpu @ y
+            ystarT_ystar_inv = (ystar.T @ ystar) ** (-1)            
+            e = (float(epsilon_results_cpu[yIdx])) ** 2 #<----------------------------------
+            yt_RRt_y = (y.T @ R_Rt_gpu) @ y
+            r2_gpu = 1 - ((yty - e - yt_RRt_y) * ystarT_ystar_inv)
+            r2.append(float(r2_gpu))
+
+        return r2   
+
+    @classmethod
+    def get_r2_num_den_method_with_epsilon_as_yTs(cls, Y_signals_gpu, O_gpu, refined_matching_results, refined_S_cpu):  
+        with cp.cuda.Device(ggm.get_instance().default_gpu_id):  
+            numerators_gpu , denominators_gpu = cls.get_r2_numerator_denominator_terms(Y_signals_gpu, O_gpu, refined_matching_results, refined_S_cpu)
+            r2_results_gpu = 1 - (numerators_gpu / denominators_gpu)
+
+            return cp.asnumpy(r2_results_gpu)   
+
+    @classmethod # R2 numerator = (yty - e - yt_RRt_y)    
+    def get_r2_numerator_denominator_terms(cls, Y_signals_gpu, O_gpu, refined_matching_results, refined_signals_cpu: np.ndarray): 
+        with cp.cuda.Device(ggm.get_instance().default_gpu_id):
+            refined_signals_gpu = cp.asarray(refined_signals_cpu)
+            num_y_signals = Y_signals_gpu.shape[1]
+
+            R_Rt_gpu = cp.eye(O_gpu.shape[0]) - O_gpu
+
+            # Compute yty for each signal
+            yty = cp.sum(Y_signals_gpu ** 2, axis=0)
+
+            # Compute ystar and ystarT_ystar
+            ystar = O_gpu @ Y_signals_gpu
+            ystarT_ystar = cp.sum(ystar ** 2, axis=0)
+
+            # Check for NaN refined results
+            nan_mask = np.isnan(refined_matching_results).all(axis=1)
+            nan_mask = cp.asarray(nan_mask)
+
+            # Check for zero signals
+            s = refined_signals_gpu
+            zero_mask = np.all(refined_signals_cpu == 0, axis=1)
+            zero_mask = cp.asarray(zero_mask)
+
+            # Compute s_star
+            s_star = O_gpu @ s.T  # shape: [timepoints, num_signals]
+
+            # Normalize s_star to get s_prime
+            s_prime = s_star * (cp.sum(s_star ** 2, axis=0) ** (-0.5)) 
+
+            # Compute error-term e = (y.T @ s_prime)^2
+            e = cp.sum(Y_signals_gpu * s_prime, axis=0) ** 2 #<----------------------------------
+
+            # Compute yt_RRt_y
+            # # yt_RRt_y = cp.sum(Y_signals_gpu * (R_Rt_gpu @ Y_signals_gpu), axis=0)
+            yt_R = Y_signals_gpu * (R_Rt_gpu @ Y_signals_gpu)
+            yt_RRt_y = cp.sum(yt_R, axis=0)
+
+            # Compute final numerator and denominator
+            num = yty - e - yt_RRt_y
+            den = ystarT_ystar
+
+            # Apply masks for nan/zero
+            num = cp.where(nan_mask, 2.0, num)
+            num = cp.where(zero_mask & ~nan_mask, 3.0, num)
+            den = cp.where(nan_mask | zero_mask, 1.0, den)
+
+            return num, den
+
+    @classmethod
+    def format_in_json_format(cls, r2_results, refined_matching_results, refined_signal_timecourses, refined_signals_present = True):
+        json_data_results_with_r2 = []
+
+        # default r2 value
+        for i in range((len(refined_matching_results))):
+            r2 = float(r2_results[i])            
+            muX, muY, sigma = refined_matching_results[i]    
+            if refined_signals_present:
+                refined_signal_timecourse = refined_signal_timecourses[i]
+            else:        
+                refined_signal_timecourse = np.array([None])
+            json_entry = JsonMgr.args2jsonEntry(muX, muY, sigma, r2, refined_signal_timecourse)    
+            json_data_results_with_r2.append(json_entry)    
+
+        return json_data_results_with_r2   

gemprf-0.1.1/gem/configs/__init__.py

@@ -0,0 +1,6 @@
+class my_class(object):
+    pass
+
+
+
+

gemprf-0.1.1/gem/configs/analysis_configs/analysis_config.xml

@@ -0,0 +1,124 @@
+<!-- XML representation of JSON data -->
+<!-- 
+    "@Author  :   Siddharth Mittal",
+    "@Version :   1.0",
+    "@Contact :   siddharth.mittal@meduniwien.ac.at",
+    "@License :   (C)Copyright 2024, Medical University of Vienna"
+-->
+
+<!-- NOTE for Analysis: For DUMMY/Analsis, set correct Visual field at two positions, one for the <stimulus> and another for <search_space>-->
+
+
+<root>
+  <!-- Path information -->
+  <path_to_append>.../</path_to_append>
+  <refine_fitting enable="True" refinefit_on_gpu="True"/> <!-- Execute refine fitting on GPU if sufficient GPU memory is available -->
+
+  <!-- Stimulus data -->
+  <stimulus>
+    <!-- File path for stimulus -->
+    <directory>/ceph/mri.meduniwien.ac.at/projects/physics/fmri/data/stimsim24/BIDS/derivatives/prfprepare/analysis-01/sub-001/stimuli</directory>    
+    <visual_field>9</visual_field> <!-- Visual field Radius, NOTE: Use "10" for simulated data, else "9" -->
+    <width>101</width>
+    <height>101</height>
+    <binarization enable="False" threshold="0"/> <!-- stimulus will be binarized if enabled, all values above threshold will be set to 1 and below to 0 -->	
+    
+    <!-- Compute model signals with high-res stimulus then downsample: "num_frames_downsampled" = your fMRI timecourse length, "slice_time_ref" for details see https://www.alivelearn.net/?p=1037 -->
+    <high_temporal_resolution enable="false" num_frames_downsampled="240" slice_time_ref="0.5"/>
+  </stimulus>
+
+  <!-- Input Data -->
+  <input_datasrc>    
+    <BIDS enable="True" run_type="individual"> <!-- Set to "True" if the input data is organized in BIDS format, select "individual" or "concatenated" run type -->
+      <basepath>/ceph/mri.meduniwien.ac.at/projects/physics/fmri/data/stimsim24/BIDS</basepath>
+      <append_to_basepath>derivatives, prfprepare</append_to_basepath> <!-- specify if the "analysis-xx"  -->          
+      <!-- <basepath>D:/results/fmri/generic/</basepath>           -->
+
+      <!-- Directory name for results; backups created with timestamp if overwrite="True" -->
+      <results_anaylsis_id overwrite="False">GEMpRF</results_anaylsis_id>
+            
+      <!-- 
+        NOTE: Case sensitive, provide the exact values!!!
+        For the analysis, sub, ses, task, run, hemi,
+        either provide comma separated values or specify "all" (to go through every available analysis) 
+        Sample: <analysis>01, 02</analysis> or <analysis>all</analysis>
+      -->
+      <analysis>01</analysis>
+      <sub>001, 002</sub>
+      <hemi>all</hemi>
+
+      <!--INDIVIDUAL Task/stimulus Analysis-->
+      <individual>
+        <task>bar</task> <!--name of the stimulus, this will be used to find the file in the stimulus directory, ONLY one value is allowed-->  
+        <ses>001nn</ses> <!-- comma separated values or specify "all" -->        
+        <run>01, 02</run> <!-- comma separated values or specify "all" -->
+      </individual>
+
+      <!--CONCATENATED Analysis-->
+      <concatenated>
+        <concatenate_item>
+          <ses>001</ses> <!-- ONLY one value is allowed-->
+          <task>bar</task> <!-- ONLY one value is allowed-->
+          <run>02</run> <!-- ONLY one value is allowed-->
+        </concatenate_item>
+        <concatenate_item>
+          <ses>001</ses>
+          <task>bar</task>
+          <run>04</run>
+        </concatenate_item>
+      </concatenated>       
+    </BIDS>
+
+    <!--OR, make Bids False and specify directly single/multiple filepaths -->
+    <fixed_paths>
+      <measured_data_filepath> <!-- Measured input data filepaths -->
+        <filepath>/ceph/mri.meduniwien.ac.at/projects/physics/fmri/data/tests/gem_generic_test/BIDS/sub-001/ses-3n2/func/sub-001_ses-3n2_task-prf_acq-normal_run-01_bold.nii.gz</filepath>
+        <filepath>dummy////sub-001/ses-3n2/func/sub-001_ses-3n2_task-prf_acq-normal_run-01_bold.nii.gz</filepath>
+      </measured_data_filepath>              
+      <results> <!-- Results filepaths realted  -->
+        <basepath>/ceph/mri.meduniwien.ac.at/projects/physics/fmri/data/tests/gem_generic_test/derivatives/prfanalyze-gem/analysis-01/sub-001/ses-3n2/</basepath> <!-- Base path for results -->    
+        <custom_filename_postfix>_[gem-new_data-simulated_v1_151x151x8_refine-validation]</custom_filename_postfix> <!-- Custom filename postfix -->    
+        <prepend_date>True</prepend_date> <!-- Flag to prepend date -->
+      </results>
+    </fixed_paths>
+  </input_datasrc>
+
+  <!-- Analysis Model -->
+  <pRF_model>    
+    <model>2d_gaussian</model> <!-- 2d_gauss, (DoG, CSS not avaiable at the moment) -->
+  </pRF_model>
+
+  <!-- Measured data section -->
+  <measured_data>
+    <width>101</width>
+    <height>101</height>
+    <batches>200</batches>    
+  </measured_data>
+
+  <!-- GPU configuration -->
+  <gpu>
+    <!-- Default GPU -->
+    <default_gpu>0</default_gpu>
+    <!-- Additional available GPUs -->
+    <additional_available_gpus>
+      <gpu>1</gpu>
+      <gpu>2</gpu>
+      <gpu>3</gpu>
+    </additional_available_gpus>
+  </gpu>
+
+  <!-- Search space information -->
+  <search_space write_debug_info="false">    
+    <!-- if the user wants to use custom HRF, pRF sizes or Spatial grid, provide the filepath to the H5 file and the keys for each parameter -->
+    <optional_analysis_params enable="False" filepath="DIR_PATH/analysis_additional_params.h5">
+      <hrf use_from_file="True" key="analysis_params/hrf_values"/>
+      <sigmas use_from_file="True" key="analysis_params/sigmas"/>
+      <spatial_grid_xy use_from_file="True" key="analysis_params/spatial_grid_xy"/>
+    </optional_analysis_params>
+    
+    <!-- if the user wants to generate a rectilinear grid within the GEM-pRF program, specify the default values below. Please NOTE that these values will ONLY be used if their corresponding optional_analysis_params = False -->
+    <default_hrf t="(0, 45)" TR="auto" peak_delay="6.16" under_shoot_delay="12.0" peak_disp="0.85" under_disp="0.82" peak_to_undershoot="2.15" normalize="true"/> <!-- SPM parameters, "t" is fed to np.arange(start, stop, step), "step" represents the TR value, set it to a lower value in case of high temporal stimulus. If TR = "auto" then, its value will be read from the stimulus file -->
+    <default_spatial_grid visual_field_radius="13.5" num_horizontal_prfs="151" num_vertical_prfs="151"/>
+    <default_sigmas num_sigmas="16" min_sigma="0.5" max_sigma="5"/>
+  </search_space>
+</root>