From 70bc4f4fac82b2d3022ebe0d541cf56dea818289 Mon Sep 17 00:00:00 2001 From: B-Sevchik <78758419+B-Sevchik@users.noreply.github.com> Date: Thu, 23 Jan 2025 10:15:52 -0500 Subject: [PATCH 1/2] Update installation instructions to use miniforge (#375) * update installation instructions to use miniforge * edit miniforge installation instructions to specify which sections are for developers * edited CONTRIBUTING.rst instructions to use miniforge instead of venv * link to contributors guide in installation.rst * fixed weird formatting error in installation.rst * Update docs/installation.rst Co-authored-by: Taylor Salo * Update docs/installation.rst Co-authored-by: Taylor Salo --------- Co-authored-by: Taylor Salo Co-authored-by: Taylor Salo --- CONTRIBUTING.rst | 8 ++++---- docs/installation.rst | 24 +++++++++++++++--------- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8597fc6fc..21c6be1c4 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -63,11 +63,11 @@ Ready to contribute? Here's how to set up `cubids` for local development. $ git clone git@github.com:your_name_here/cubids.git -3. Install your local copy into a virtualenv. - Assuming you have virtualenvwrapper installed, - this is how you set up your fork for local development:: +3. Install your local copy into a miniforge environment. + This is how you set up your fork for local development:: - $ mkvirtualenv cubids + $ mamba create -n cubids python=3.12 + $ mamba activate cubids $ cd cubids/ $ python setup.py develop diff --git a/docs/installation.rst b/docs/installation.rst index b8c323e7f..53e5d4734 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -8,16 +8,15 @@ Installation .. note:: We **strongly recommend** using ``CuBIDS`` with environment management. - For this, we recommend `miniconda `_ - (`miniforge `_ for M1 Chip Mac Machines). + For this, we recommend `miniforge `_. -Once you've installed conda, -initialize a new conda environment (for example, named ``cubids``) as follows: +Once you've installed mamba, +initialize a new mamba environment (for example, named ``cubids``) as follows: .. code-block:: console - $ conda create -n cubids python=3.12 pip - $ conda activate cubids + $ mamba create -n cubids python=3.12 pip + $ mamba activate cubids You are now ready to install CuBIDS. You can do so in one of two ways. @@ -29,8 +28,7 @@ To obtain ``CuBIDS`` locally, we can use ``pip`` to download our software from t $ pip install CuBIDS -Alternatively, -you can clone the source code for ``CuBIDS`` from our `GitHub repository`_ using the following command: +Alternatively, you can clone the source code for ``CuBIDS`` from our `GitHub repository`_ using the following command: .. code-block:: console @@ -43,13 +41,14 @@ Once you have a copy of the source, you can install it with: $ cd CuBIDS $ pip install -e . + We will now need to install some dependencies of ``CuBIDS``. To do this, we first must install deno to run `bids-validator`. We can accomplish this using the following command: .. code-block:: console - $ conda install deno + $ mamba install deno The new schema-based ``bids-validator`` doesn't need to be installed and will be implemented automatically when `cubids validate` is called @@ -75,6 +74,13 @@ and will be implemented automatically when `cubids validate` is called For more information, you can read: https://bids-validator.readthedocs.io/en/latest/user_guide/command-line.html +.. tip:: + If you want to modify the CuBIDS codebase + (e.g., if you are looking to contribute to CuBIDS), + please follow the installation instructions in + `our contributing guidelines `_. + + We also recommend using ``CuBIDS`` with the optional ``DataLad`` version control capabilities. We use ``DataLad`` throughout our walkthrough of the CuBIDS Workflow on :doc:`the Example Walkthrough page `. From bc269f46f2b229e86b9f3076c2d850ff7fbde58b Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Thu, 23 Jan 2025 10:33:08 -0500 Subject: [PATCH 2/2] Add FAQ page (#388) * Add FAQ page. * Update docs. * Fix docs. * Add more info to FAQ. --- .gitignore | 1 + cubids/data/references.bib | 0 cubids/metadata_merge.py | 1 + docs/api.rst | 42 +++++++++++++++++++------------------- docs/conf.py | 13 +++++------- docs/contributing.rst | 1 + docs/faq.rst | 29 ++++++++++++++++++++++++++ docs/index.rst | 5 ++--- docs/usage.rst | 2 +- 9 files changed, 61 insertions(+), 33 deletions(-) create mode 100644 cubids/data/references.bib create mode 100644 docs/contributing.rst create mode 100644 docs/faq.rst diff --git a/.gitignore b/.gitignore index 336385a09..95e4fe37a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +docs/generated/ cubids/_version.py *.DS_Store diff --git a/cubids/data/references.bib b/cubids/data/references.bib new file mode 100644 index 000000000..e69de29bb diff --git a/cubids/metadata_merge.py b/cubids/metadata_merge.py index f3decd19a..e46879b30 100644 --- a/cubids/metadata_merge.py +++ b/cubids/metadata_merge.py @@ -304,6 +304,7 @@ def group_by_acquisition_sets(files_tsv, output_prefix, acq_group_level, is_long """Find unique sets of Key/Param groups across subjects. This writes out the following files: + - _AcqGrouping.tsv: A tsv with the mapping of subject/session to acquisition group. - _AcqGrouping.json: A data dictionary for the AcqGrouping.tsv. diff --git a/docs/api.rst b/docs/api.rst index b4d81eac6..f42f71c20 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -25,17 +25,17 @@ API :toctree: generated/ :template: function.rst - cubids.workflows.validate - cubids.workflows.bids_sidecar_merge - cubids.workflows.group - cubids.workflows.apply - cubids.workflows.datalad_save - cubids.workflows.undo - cubids.workflows.copy_exemplars - cubids.workflows.add_nifti_info - cubids.workflows.purge - cubids.workflows.remove_metadata_fields - cubids.workflows.print_metadata_fields + workflows.validate + workflows.bids_sidecar_merge + workflows.group + workflows.apply + workflows.datalad_save + workflows.undo + workflows.copy_exemplars + workflows.add_nifti_info + workflows.purge + workflows.remove_metadata_fields + workflows.print_metadata_fields ********************************************** @@ -48,11 +48,11 @@ API :toctree: generated/ :template: function.rst - cubids.metadata_merge.check_merging_operations - cubids.metadata_merge.merge_without_overwrite - cubids.metadata_merge.merge_json_into_json - cubids.metadata_merge.get_acq_dictionary - cubids.metadata_merge.group_by_acquisition_sets + metadata_merge.check_merging_operations + metadata_merge.merge_without_overwrite + metadata_merge.merge_json_into_json + metadata_merge.get_acq_dictionary + metadata_merge.group_by_acquisition_sets *********************************** @@ -65,8 +65,8 @@ API :toctree: generated/ :template: function.rst - cubids.validator.build_validator_call - cubids.validator.build_subject_paths - cubids.validator.run_validator - cubids.validator.parse_validator_output - cubids.validator.get_val_dictionary + validator.build_validator_call + validator.build_subject_paths + validator.run_validator + validator.parse_validator_output + validator.get_val_dictionary diff --git a/docs/conf.py b/docs/conf.py index 9da1b27fb..124af6f2f 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -73,7 +73,7 @@ # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = ".rst" +source_suffix = {".rst": "restructuredtext"} # The master toctree document. master_doc = "index" @@ -171,13 +171,10 @@ _python_doc_base = "https://docs.python.org/" + _python_version_str intersphinx_mapping = { "python": (_python_doc_base, None), - "numpy": ("https://numpy.org/doc/stable/", (None, "./_intersphinx/numpy-objects.inv")), - "scipy": ( - "https://docs.scipy.org/doc/scipy/reference", - (None, "./_intersphinx/scipy-objects.inv"), - ), - "sklearn": ("https://scikit-learn.org/stable", (None, "./_intersphinx/sklearn-objects.inv")), - "matplotlib": ("https://matplotlib.org/", (None, "https://matplotlib.org/objects.inv")), + "numpy": ("https://numpy.org/doc/stable/", None), + "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None), + "sklearn": ("https://scikit-learn.org/stable", None), + "matplotlib": ("https://matplotlib.org/stable/", None), "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), "pybids": ("https://bids-standard.github.io/pybids/", None), "nibabel": ("https://nipy.org/nibabel/", None), diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 000000000..3bdd7dc21 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 000000000..edf1e5cfe --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,29 @@ +========================== +Frequently Asked Questions +========================== + + +-------------------------------------- +Does CuBIDS work on all BIDS datasets? +-------------------------------------- + +CuBIDS relies on many hardcoded rules and data types, +so it may not work on all BIDS datasets. +Some datatypes, such as EEG or iEEG, are not yet supported, +nor are some configurations of supported datatypes, such as multi-echo fMRI. + +If you encounter an issue, please open an issue on the CuBIDS GitHub repository. + + +----------------------------------------------------- +How do the developers determine what features to add? +----------------------------------------------------- + +CuBIDS is primarily developed to curate large-scale datasets in order to be used by the PennLINC team. +This means that we will naturally prioritize features that are useful to us. +However, we are always open to suggestions and contributions from the community, +and will of course consider features that do not directly benefit us. + +If you want to request support for a new modality or niche data feature, +please open an issue on the CuBIDS GitHub repository. +We are more likely to add support for a new feature if you can point us toward a dataset that we can use to test it. diff --git a/docs/index.rst b/docs/index.rst index 3a9d5b9d4..6f8fa7c0b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,8 +13,7 @@ Contents usage cli example - ../CONTRIBUTING - ../AUTHORS - ../HISTORY + contributing + faq glossary api diff --git a/docs/usage.rst b/docs/usage.rst index 4696221c6..25b3dba77 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -110,7 +110,7 @@ but it keeps track of every file's assignment to Entity and Parameter Groups. .. _acqgrouptsv: Modifying Entity and Parameter Group Assignments ---------------------------------------------- +------------------------------------------------ Sometimes we see that there are important differences in acquisition parameters within a Entity Set. If these differences impact how a pipeline will process the data,