{"id":15893073,"url":"https://github.com/constantjin/photographer-data-analysis","last_synced_at":"2026-05-06T15:45:03.834Z","repository":{"id":256684207,"uuid":"845915889","full_name":"constantjin/photographer-data-analysis","owner":"constantjin","description":"Python/R scripts for neural/behavioral data analysis from the Photographer Paradigm","archived":false,"fork":false,"pushed_at":"2024-09-12T09:23:49.000Z","size":3865,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-08T08:14:57.805Z","etag":null,"topics":["behavioral-data","bids-apps","fmri-data-analysis","python","r"],"latest_commit_sha":null,"homepage":"https://bspl.korea.ac.kr","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/constantjin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-22T07:14:13.000Z","updated_at":"2024-09-12T10:02:18.000Z","dependencies_parsed_at":"2024-09-12T12:56:03.273Z","dependency_job_id":null,"html_url":"https://github.com/constantjin/photographer-data-analysis","commit_stats":null,"previous_names":["constantjin/photographer-data-analysis"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constantjin%2Fphotographer-data-analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constantjin%2Fphotographer-data-analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constantjin%2Fphotographer-data-analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constantjin%2Fphotographer-data-analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/constantjin","download_url":"https://codeload.github.com/constantjin/photographer-data-analysis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246863583,"owners_count":20846278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["behavioral-data","bids-apps","fmri-data-analysis","python","r"],"created_at":"2024-10-06T08:07:01.708Z","updated_at":"2026-05-06T15:44:58.811Z","avatar_url":"https://github.com/constantjin.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Photographer Paradigm Data Analysis Scripts\n\nPython/R scripts for neural/behavioral data from the [Photographer Paradigm](https://github.com/constantjin/photographer-experimental-paradigm)\n\n## References\n\n  - **Jin, S.**, Lee, J., \u0026 Lee, J. H. Historical Feedback Representations Robustly Guide Learning. Organization for Human Brain Mapping (OHBM) 2024. Seoul, Korea.\n  - **Jin, S.**, Lee, J., \u0026 Lee, J. H. How to Be a Good Photographer: Multi-modal Learning In a Real-life Environment. OHBM 2023. Montreal, Canada. **[Oral Presentation]**\n\n## Requirements\n\n### Neural and behavioral data\n\nThe orignal neural and behavioral data acquired from the Photographer experiment through 2022 and 2023 are available on request from the corresponding author. Please contact us with respect to the BSPL \"[Contact Us](https://bspl-ku.github.io/contact/)\" page. \n\n- **Update**\n  - Preprocessed behavioral data, cross-validated cluster mask files, and second-level RSA results for the second-level analysis or R visualization scripts would be open to public after our manuscript is submitted.\n\n### Dependencies\n\n- Python 3.10.8\n    - If you use [asdf](https://asdf-vm.com/) for toolchain management, you can run `asdf install` from the project root. \n\n    - We use [Poetry](https://python-poetry.org/) for dependency management.\n        - Please install dependencies by running `poetry install` from the project root.\n\n- R \u003e= 4.2.2\n    - Session Information\n\n        ```R\n        R version 4.4.1 (2024-06-14 ucrt)\n        Platform: x86_64-w64-mingw32/x64\n        Running under: Windows 11 x64 (build 22631)\n\n        Matrix products: default\n\n\n        locale:\n        [1] LC_COLLATE=Korean_Korea.utf8  LC_CTYPE=Korean_Korea.utf8    LC_MONETARY=Korean_Korea.utf8 LC_NUMERIC=C                 \n        [5] LC_TIME=Korean_Korea.utf8    \n\n        time zone: Asia/Seoul\n        tzcode source: internal\n\n        attached base packages:\n        [1] stats     graphics  grDevices utils     datasets  methods   base     \n\n        other attached packages:\n        [1] slider_0.3.1        glue_1.7.0          emmeans_1.10.4      AICcmodavg_2.3-3    broom.mixed_0.2.9.5 lmerTest_3.1-3     \n        [7] lme4_1.1-35.5       Matrix_1.7-0        ggpubr_0.6.0        rstatix_0.7.2       ggnewscale_0.5.0    ggforce_0.4.2      \n        [13] see_0.9.0           report_0.5.9        parameters_0.22.2   performance_0.12.3  modelbased_0.8.8    insight_0.20.4     \n        [19] effectsize_0.8.9    datawizard_0.12.3   correlation_0.8.5   bayestestR_0.14.0   easystats_0.7.3     lubridate_1.9.3    \n        [25] forcats_1.0.0       stringr_1.5.1       dplyr_1.1.4         purrr_1.0.2         readr_2.1.5         tidyr_1.3.1        \n        [31] tibble_3.2.1        ggplot2_3.5.1       tidyverse_2.0.0    \n        ```\n\n- [AFNI](https://afni.nimh.nih.gov/) for neuroimaging analysis\n\n## First-level analysis\n\n### Goal\n\n- Run block-/trial-wise GLM\n- Perform searchlight representational similarity analysis (RSA)\n- Conduct one-sample t-tests on individual RSA maps\n\n### Prerequisites\n\n- Preprocessed fMRI data via fMRIPRep\n    - Note: We used the following docker command to preprocess the BIDS dataset:\n\n        ```bash\n        docker run -it --rm -v ${PWD}:/data nipreps/fmriprep:23.0.2 /data/bids /data/bids/derivatives/fmriprep-23.0.2-reconall participant -w /data/tmp/workdir --skip-bids-validation --fs-license-file /data/bids/derivatives/license.txt --output-spaces MNI152NLin2009cAsym:res-2 MNI152NLin2009cAsym --stop-on-first-crash\n        ```\n\n- `photographer_config.toml` in the `[BIDS root]/bids/code` directory \n    - We manage analysis parameters/choices in a separate toml file.\n    - Please refer to our `photographer_config.toml` file in the BIDS data directories.\n    - You can find documentations for keys in the config file from the [`first-level/utils/types.py`](first-level/utils/types.py).\n\n- MNI152NLin2009cAsym gray matter (GM) templete\n    - You can download the template file from [this link](http://www.bic.mni.mcgill.ca/~vfonov/icbm/2009/mni_icbm152_nlin_asym_09c_nifti.zip).\n    - Decompress the ZIP file and you can find the `mni_icbm152_gm_tal_nlin_asym_09c.nii` file.\n    - Please update the `mask.mni_gm_template_path` key from the `photographer_config.toml` file accordingly.\n\n### Command\n\nSince the `first-level` package is designed as a BIDS-App, you can run first-level tasks using the following command:\n\n```\nusage: python -m first-level [-h] [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] \n                             [--config-file CONFIG_FILE]\n                             -t TASK_NAME\n                             bids_dir output_dir {participant}\n\nPhotographer Data First-level Analysis\n\nPositional arguments:\n  bids_dir              The BIDS root directory.\n  output_dir            The analysis output directory. It should be (bids_dir)/derivatives/first-level\n  {participant}         Processing stage. Only \"participant\" is accepted. I believe this is in the BIDS-Apps spec?\n\nOptions:\n  -h, --help            show this help message and exit\n\nBIDS-related argument:\n  --participant-label, --participant_label\n                        A single participant label or a space-separated participant labels.\n\nFirst-level analysis-related arguments:\n  -t, --task TASK_NAME\n                        A first-level analysis task to run.\n  --config-file, --config_file CONFIG_FILE\n                        A config file (toml) path. If not specified, we will try to find photographer_config.toml in (bids_dir)/code.\n```\n\n### Tasks\n\n\u003e Note that the `Order` column represents recommended task orders.\n\n| Order | Task Name | Description |\n| ----- | --------- | ----------- |\n| 1 | `glm.prepare_task_stim` | Prepare task-related GLM regressors from behavioral data. |\n| 2 | `glm.prepare_confound` | Prepare nuisance GLM regressors from fMRIPrep confounds. |\n| 3 | `glm.run_block_wise_glm` | Run block-wise GLM (GLM1) for univariate analysis. |\n| 4 | `glm.run_trial_wise_glm` | Run trial-wise GLM (GLM2) for multivariate (RSA) analysis. |\n| 5 | `mask.prepare_gm_mask` | Prepare a gray matter (GM) mask from the MNI152NLin2009cAsym GM template. |\n| 6 | `behavior.prepare_behavioral_data` | Preprocess behavioral data into a CSV file and include object detection results. |\n| 7 | `rsa.prepare_feedback_neural_data` | Aggregate trial-wise feedback event beta maps from GLM 2 into a numpy array (NPY) file |\n| 8 | `rsa.prepare_feedback_model_rdm` | Prepare feedback history model RDMs from the preprocessed behavioral data. |\n| 9 | `rsa.run_feedback_rsa` | Run searchlight RSA on feedback event beta maps and feedback history model RDMs. |\n| 10 | `stat.run_univariate_ttest` | Conduct t-tests on individual beta maps from GLM 1 (univariate analysis) |\n| 11 | `stat.run_feedback_rsa_ttest` | Conduct t-tests on individual feedback history RSA maps. |\n| 12 | `stat.extract_feedback_rsa_cluster_mask` | Compute corrected cluster masks from feedback history RSA statistical maps. |\n\n### Acknowledgments\n\n- [fMRIPrep GitHub](https://github.com/nipreps/fmriprep) for the BIDS-App structure reference.\n- [Minseok Choi](https://github.com/BigJade-C) originally implemented codes for computing searchlight spheres (`first-level/utils/searchlight.py`).\n\n## Second-level analysis\n\n### Goal\n\n- Identify cross-validated RSA clusters across both subgroups (i.e., Discovery and Validation group)\n- Perform second-level RSA (using both feedback history and exploration models) on the robust RSA clusters (i.e., MiOG and IFG) representing feedback history information\n\n### Scripts (IPython Notebook)\n\n\u003e Please refer to notes and comments in each .ipynb script for detailed information.\n\n- [`1_cross_validated_rsa_clusters.ipynb`](second-level/1_cross_validated_rsa_clusters.ipynb): Compute cross-validated cluster masks; Identify Feedback History clusters (i.e., MiOG and IFG) from the cross-validated cluster masks\n\n- [`2_visualization_of_rsa_clusters.ipynb`](second-level/2_visualization_of_rsa_clusters.ipynb): Plot surface-based mapping for the cross-validated RSA clusters\n\n- [`3_run_second_level_rsa.ipynb`](second-level/3_run_second_level_rsa.ipynb): Run second-level RSA on the Feedback History clusters using feedback history or exploration model RDMs\n\n### Data and outputs\n\n- Data\n  - `photographer_exploration_info.csv`\n    - For exploration model RDMs, we extracted exploration times, exploration distances, and coordinates for the capture locations from the etime files. This file is needed for the second-level RSA.\n\n- Outputs\n  - Cross-validated (feedback history) RSA cluster masks\n    - For the Recent-2 Trial, Recent-3 Trial, and Feedback History (Recent-2 Trial \u0026 Recent-3 Trial) models\n    - Will be stored in `second-level/output/cross_validated_cluster_mask`\n    - We additionally identified two main RSA clusters, the MiOG and IFG, representing both Recent-2 Trial and Recent-3 Trial models.\n\n  - CSV files for second-level RSA results\n    - Note: Second-level RSA are restricted in the Feedback History clusters (i.e., MiOG and IFG regions).\n    - Paths for storing RSA results\n      - RSA using exploration models: `second-level/output/second_level_rsa/exploration_second_level`\n      - Partial correlation RSA using feedback history models: `second-level/output/second_level_rsa/partial_feedback_history_second_level`\n      - Partial correlation RSA using Capture Distance model: `second-level/output/second_level_rsa/partial_feedback_history_second_level`\n\n### Acknowledgments\n\n- [`surfplot`](https://github.com/danjgale/surfplot) for surface-based mapping\n  - Gale, Daniel J., Vos de Wael., Reinder, Benkarim, Oualid, \u0026 Bernhardt, Boris. (2021). Surfplot: Publication-ready brain surface figures (v0.1.0). Zenodo. https://doi.org/10.5281/zenodo.5567926\n  - Vos de Wael R, Benkarim O, Paquola C, Lariviere S, Royer J, Tavakol S, Xu T, Hong S-J, Langs G, Valk S, Misic B, Milham M, Margulies D, Smallwood J, Bernhardt BC. 2020. BrainSpace: a toolbox for the analysis of macroscale gradients in neuroimaging and connectomics datasets. *Communications Biology*. 3:103. https://doi.org/10.1038/s42003-020-0794-7\n\n- [`neuromaps`](https://github.com/netneurolab/neuromaps) for volume-to-surface transformation (i.e., MNI152 to fsLR)\n  - Buckner, R. L., Krienen, F. M., Castellanos, A., Diaz, J. C., \u0026 Yeo, B. T. (2011). The organization of the human cerebellum estimated by intrinsic functional connectivity. *Journal of Neurophysiology*, 106(5), 2322-2345. https://doi.org/10.1152/jn.00339.2011\n  - Wu, J., Ngo, G. H., Greve, D., Li, J., He, T., Fischl, B., Eickhoff, S. B., \u0026 Yeo, B. T. T. (2018). Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate systems. *Human Brain Mapping*  39(9), 3793-3808. https://doi.org/10.1002/hbm.24213\n\n\n## R visualization scripts\n\n### Goal\n\n- Visualize behavioral data from the Photographer paradigm and perform validation of feedback and validation of learning\n- Visualize second-level RSA results with respect to the clusters (MiOG or IFG) and subgroups (Discovery or Validation)\n\n### Scripts (R Notebook)\n\n\u003e Please refer to notes and comments in each notebook for detailed information.\n\n- [`1_photographer_behavioral_analysis.Rmd`](R_visualization/1_photographer_behavioral_analysis.Rmd) / [`.md`](R_visualization/1_photographer_behavioral_analysis.md): Perform statistical tests and visualize the behavioral data\n\n- [`2_photographer_second_level_RSA_visualization.Rmd`](R_visualization/2_photographer_second_level_RSA_visualization.Rmd) / [`.md`](R_visualization/2_photographer_second_level_RSA_visualization.md): Visualize second-level RSA results (i.e., individual and mean RSA correlations) for each RSA cluster and subgroup\n\n### Data and outputs\n\n- Data\n  - `group_*_behavior_feedback.csv`\n    - Preprocessed behavioral data files from the `behavior.prepare_behavioral_data` task of the first-level analysis.\n  \n  - Second-level RSA CSV files\n    - The same data copied from the second-level analysis (see the [Data and outputs](#data-and-outputs) section in the second-level analysis).\n\n- Outputs\n  - PNG files (300 dpi) representing figures. Most of them are separated by the subgroup name and/or RSA cluster name.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstantjin%2Fphotographer-data-analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstantjin%2Fphotographer-data-analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstantjin%2Fphotographer-data-analysis/lists"}