From 3b12818ce440720f3c19820f4567517cb8ab8a5a Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Wed, 8 May 2024 07:21:58 -0400 Subject: [PATCH 1/3] fix warnings and errors --- bids/reports/report.py | 24 ++++++++++++++---------- bids/variables/variables.py | 13 ++++++++----- doc/api.rst | 12 +----------- doc/conf.py | 1 + doc/examples/statsmodels_tutorial.md | 22 +++++++++++----------- doc/layout/index.rst | 2 +- 6 files changed, 36 insertions(+), 38 deletions(-) diff --git a/bids/reports/report.py b/bids/reports/report.py index 53a164cbd..c085800ec 100644 --- a/bids/reports/report.py +++ b/bids/reports/report.py @@ -18,16 +18,20 @@ class BIDSReport: (str), a dictionary, or None. If None, loads and uses default configuration information. Keys in the dictionary include: - 'dir': a dictionary for converting encoding direction strings - (e.g., j-) to descriptions (e.g., anterior to - posterior) - 'seq': a dictionary of sequence abbreviations (e.g., EP) and - corresponding names (e.g., echo planar) - 'seqvar': a dictionary of sequence variant abbreviations - (e.g., SP) and corresponding names (e.g., spoiled) - - Warning - ------- + + 'dir': + a dictionary for converting encoding direction strings + (e.g., j-) to descriptions (e.g., anterior to + posterior) + 'seq': + a dictionary of sequence abbreviations (e.g., EP) and + corresponding names (e.g., echo planar) + 'seqvar': + a dictionary of sequence variant abbreviations + (e.g., SP) and corresponding names (e.g., spoiled) + + Warnings + -------- pybids' automatic report generation is experimental and currently under active development, and as such should be used with caution. Please remember to verify any generated report before putting it to use. diff --git a/bids/variables/variables.py b/bids/variables/variables.py index 6aadcb7e8..e711c65eb 100644 --- a/bids/variables/variables.py +++ b/bids/variables/variables.py @@ -659,12 +659,15 @@ def merge_variables(variables, **kwargs): A list of Variables to merge. kwargs Optional keyword arguments to pass onto the class-specific merge() call. + Possible args: - - sampling_rate (int, str): The sampling rate to use if resampling - of DenseRunVariables is necessary for harmonization. If - 'highest', the highest sampling rate found will be used. This - argument is only used when passing DenseRunVariables in the - variables list. + + sampling_rate (int, str): + The sampling rate to use if resampling + of DenseRunVariables is necessary for harmonization. If + 'highest', the highest sampling rate found will be used. This + argument is only used when passing DenseRunVariables in the + variables list. Returns ------- diff --git a/doc/api.rst b/doc/api.rst index f65cc86d3..c1eb12c9b 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -24,8 +24,6 @@ API Reference .. currentmodule:: bids -.. _calibration_ref: - :mod:`bids.modeling`: Model specification for BIDS datasets ------------------------------------------------------------ @@ -56,8 +54,6 @@ API Reference .. currentmodule:: bids -.. _calibration_ref: - :mod:`bids.variables`: Variables -------------------------------------------------- @@ -80,8 +76,6 @@ API Reference .. currentmodule:: bids -.. _calibration_ref: - :mod:`bids.config`: PyBIDS Configuration utilities -------------------------------------------------- @@ -97,8 +91,6 @@ API Reference .. currentmodule:: bids -.. _calibration_ref: - :mod:`bids.utils`: Utility functions -------------------------------------------------- @@ -112,6 +104,4 @@ API Reference bids.utils.make_bidsfile -.. currentmodule:: bids - -.. _calibration_ref: +.. currentmodule:: bids \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index a2545dc75..f96a8656c 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -68,6 +68,7 @@ autosummary_generate = True autodoc_default_flags = ['members', 'inherited-members'] add_module_names = False +numpydoc_class_members_toctree = False # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/examples/statsmodels_tutorial.md b/doc/examples/statsmodels_tutorial.md index 8b3ce7799..941d66088 100644 --- a/doc/examples/statsmodels_tutorial.md +++ b/doc/examples/statsmodels_tutorial.md @@ -11,7 +11,7 @@ kernelspec: name: python3 --- -## Executing and inspecting StatsModels with `pybids.modeling` +# Executing and inspecting StatsModels with `pybids.modeling` A minimalistic tutorial illustrating usage of the tools in the `bids.modeling` module—most notably, `BIDSStatsModelsGraph` and its various components. ```{code-cell} ipython3 @@ -27,7 +27,7 @@ from os.path import join import json ``` -### Load BIDSLayout +## Load BIDSLayout Standard stuff: load the `BIDSLayout` object (we'll use the ds005 dataset bundled with PyBIDS tests) and read in one of the included model files (`ds005/models/ds-005_type-test_model.json`). ```{code-cell} ipython3 @@ -37,21 +37,21 @@ json_file = join(layout_path, 'models', 'ds-005_type-test_model.json') spec = json.load(open(json_file, 'r')) ``` -### Initialize the graph +## Initialize the graph The `BIDSStatsModelsGraph` is the primary interface to design data, model constructions, etc. We build it from a `BIDSLayout` and the contents of a JSON model file. ```{code-cell} ipython3 graph = BIDSStatsModelsGraph(layout, spec) ``` -### Load variables from BIDS dataset +## Load variables from BIDS dataset We will typically want to load variables into BIDS "collections" from the BIDS project. The `scan_length` argument is only necessary here because the test dataset doesn't actually include nifti image headers, so duration of scans can't be inferred. In typical use, you can call this without arguments. ```{code-cell} ipython3 graph.load_collections(scan_length=480) ``` -### Access specific nodes +## Access specific nodes Now that the graph is loaded, we can start interacting with its nodes. We'll typically start with the root node, which will usually contain the run-level model information. We can either access the `.root_node`, or use `get_node()` to get the node by its unique name (defined in the JSON file). ```{code-cell} ipython3 @@ -59,7 +59,7 @@ Now that the graph is loaded, we can start interacting with its nodes. We'll typ root_node = graph.root_node ``` -### Inspect `BIDSVariableCollection` +## Inspect `BIDSVariableCollection` +++ @@ -82,7 +82,7 @@ We can take a look at the individual variable objects as well: first_sub.variables ``` -### Executing a node +## Executing a node We can "run" each node to produce design matrices for each unique combination of entities/inputs we want. This is determined by the grouping structure. When working with the API directly, this is indicated via the `group_by` argument to a `.run()` method. In this case, we're indicating that the design information should be set up separately for every unique combination of `run` and `subject`. Note that we need to include `subject` even though this is a strictly run-level model, because if we only pass `['run']`, there will only be 3 separate analyses conducted: one for run 1, one for run 2, and one for run 3. Whereas what we actually want is for the procedure to be done separately for each unique combination of the 3 runs and 16 subjects (i.e., 48 times). @@ -94,7 +94,7 @@ Note that we need to include `subject` even though this is a strictly run-level outputs = root_node.run(group_by=['run', 'subject'], force_dense=False, transformation_history=True) ``` -### Node outputs +## Node outputs +++ @@ -141,7 +141,7 @@ There's a 1-to-1 mapping from rows in `.X` to rows in `.metadata`. This means yo +++ -### Transformation History +## Transformation History +++ @@ -178,7 +178,7 @@ ts[1].output.variables ts[1].output.variables['RT'].to_df(entities=False) ``` -### Traversing the graph +## Traversing the graph So far we've executed the root node, which by definition required no inputs from any previous node. But in typical workflows, we'll be passing outputs from one node in as inputs to another. For example, we often want to take the run-level parameter estimates and pass them to a subject-level model that does nothing but average over runs within each subject. This requires us to somehow traverse the graph based on the edges specified in the BIDS-StatsModel document. We can do that by taking advantage of each node's `.children` attribute, which contains a list of `BIDSStatsModelsEdge` named tuples that specify an edge between two nodes. ```{code-cell} ipython3 @@ -194,7 +194,7 @@ next_node.level, next_node.name We assign the first connected node to `next_node`, and print out its `level` and `name` for inspection (both are session). -### Passing in inputs +## Passing in inputs Armed with that, we can run the session node and proceed and before. However, there's a twist: whereas the root node only needs to know about variables loaded directly from the `BIDSLayout` (which we achieved with that `.load_collections()` call earlier), the session node can't get the inputs it needs from the `BIDSLayout`, because there aren't any (at least in this particular dataset). What we want to do at the session level is average over our run-level estimates within-session. But to do that, we need to actually pass in information about those runs! The way we do this is to pass, as the first argument to `.run()`, a list of `ContrastInfo` objects informing our node about what inputs it should use to construct its design matrices. The typical use pattern is to pass one concatenated list containing *all* of the outputs from the previous level that we want to pass on. Note that we may not want to pass *all* of the outputs forward. For example, suppose that 2 out of 48 run-level models failed during the estimation process. We might not want to keep passing information about those 2 runs forward, as we can't compute them. So we can always filter the list of `ContrastInfo` objects we received from the previous node before we pass them on to the next node. (We could also do other things, like rename each `ContrastInfo` to use whatever naming scheme our software prefers; modifying the entities; and so on. But we won't do any of that here.) diff --git a/doc/layout/index.rst b/doc/layout/index.rst index f66acfd23..fbbc266e3 100644 --- a/doc/layout/index.rst +++ b/doc/layout/index.rst @@ -1,4 +1,4 @@ -.. _reports: +.. _layout: ===================================================== ``layout``: Querying BIDS datasets From d20f84a379e4a9eddd047fe396298a9952087736 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Wed, 8 May 2024 07:56:21 -0400 Subject: [PATCH 2/3] update intersphinx and silence orphan documents --- doc/analysis/index.rst | 5 ++--- doc/conf.py | 18 +++++++++--------- doc/includes/big_toc_css.rst | 2 ++ doc/includes/bigger_toc_css.rst | 2 ++ doc/tune_toc.rst | 2 ++ pyproject.toml | 2 +- 6 files changed, 18 insertions(+), 13 deletions(-) diff --git a/doc/analysis/index.rst b/doc/analysis/index.rst index 09d99d490..141db010c 100644 --- a/doc/analysis/index.rst +++ b/doc/analysis/index.rst @@ -15,7 +15,7 @@ .. _overview: An overview of the analysis module -=========================================== +================================== .. topic:: **BIDS models** @@ -44,10 +44,9 @@ contrasts. .. _SPM: https://www.fil.ion.ucl.ac.uk/spm/ .. _Nipype: https://nipype.readthedocs.io -.. _quickstart: Quickstart -============= +========== A simple example of standard usage follows. We assume that we have a root folder containing a BIDS-compliant project in ``/bidsproject``, as well as a BIDS-Models JSON specification in ``model.json``. diff --git a/doc/conf.py b/doc/conf.py index f96a8656c..6f236a3be 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -49,20 +49,20 @@ ] intersphinx_mapping = { - 'https://docs.python.org/3.5': None, - 'https://docs.scipy.org/doc/numpy': None, - 'https://docs.scipy.org/doc/scipy/reference': None, - 'https://matplotlib.org/': None, - 'https://scikit-learn.org/0.17': None, - 'https://nipy.org/nibabel/': None, - 'https://pandas.pydata.org/pandas-docs/stable/': None, - 'https://neurosynth.readthedocs.io/en/latest/': None, + 'python': ('https://docs.python.org/3.5', None), + 'numpy' : ('https://docs.scipy.org/doc/numpy', None), + 'scipy' : ('https://docs.scipy.org/doc/scipy/reference', None), + "matplotlib" : ('https://matplotlib.org/', None), + "scikit-learn" : ('https://scikit-learn.org/0.17', None), + "nibabel" : ('https://nipy.org/nibabel/', None), + "pandas" : ('https://pandas.pydata.org/pandas-docs/stable/', None), + "neurosynth" : ('https://neurosynth.readthedocs.io/en/latest/', None), } intersphinx_timeout = 5 # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '2.2.0' +needs_sphinx = '6.2.0' # Generate stubs autosummary_generate = True diff --git a/doc/includes/big_toc_css.rst b/doc/includes/big_toc_css.rst index a2e41ff27..3a1144ddc 100644 --- a/doc/includes/big_toc_css.rst +++ b/doc/includes/big_toc_css.rst @@ -2,6 +2,8 @@ File to ..include in a document with a big table of content, to give it 'style' +:orphan: + .. raw:: html