Repository: neurostuff/NiMARE
Pull request #919: [ENH] convert sample sizes
Author: login: jdkent
Created: 2025-03-11T01:25:24Z | Merged: 2025-03-11T21:24:20Z

<!---
This is a suggested pull request template for NiMARE.
It's designed to capture information we've found to be useful in reviewing pull requests.

If there is other information that would be helpful to include, please don't hesitate to add it!

Please also label your pull request with the relevant tags.
See here for more information and a list of available options:
https://github.com/neurostuff/NiMARE/blob/main/CONTRIBUTING.md#pull-requests
-->

<!-- Please indicate after the # which issue you're closing with this PR.
This is helpful for the maintainers AND will magically close the issue when this
pull request is merged!
https://help.github.com/articles/closing-issues-using-keywords -->
references: https://neurostars.org/t/using-neurosynth-compose-and-annotations/32191/2

<!-- Please give a brief overview of what has changed in the PR.
If you're not sure what to write, consider it a note to the maintainers to indicate
what they should be looking for when they review the pull request. -->
Changes proposed in this pull request:
- add `sample_sizes` as an analysis metadata variable that can be used to transfer over to a NiMARE dataset

## Summary by Sourcery

Adds support for 'sample_sizes' as an analysis metadata variable that can be used to transfer over to a NiMARE dataset.

Enhancements:
- Adds validation for sample sizes to ensure they are in the correct format (list, tuple, int, or float).
- Improves error handling and type checking for annotations to ensure they are dictionaries.


Diff:
diff --git a/nimare/io.py b/nimare/io.py
index 7ea42d092..0d5efff82 100644
--- a/nimare/io.py
+++ b/nimare/io.py
@@ -62,13 +62,45 @@ def _analysis_to_dict(study, analysis):
                 "z": [p.z for p in analysis.points] or [None],
             },
         }
-        sample_size = study.metadata.get("sample_size")
-        if sample_size:
-            result["metadata"]["sample_sizes"] = [sample_size]
+
+        sample_sizes = analysis.metadata.get("sample_sizes")
+        sample_size = None
+
+        # Validate sample sizes if present
+        if sample_sizes is not None and not isinstance(sample_sizes, (list, tuple)):
+            raise TypeError(
+                f"Expected sample_sizes to be list or tuple, but got {type(sample_sizes)}"
+            )
+
+        if not sample_sizes:
+            # Try to get single sample size from analysis or study metadata
+            sample_size = analysis.metadata.get("sample_size")
+            if sample_size is None:
+                sample_size = study.metadata.get("sample_size")
+
+            # Validate single sample size if present
+            if sample_size is not None and not isinstance(sample_size, (int, float)):
+                raise TypeError(f"Expected sample_size to be numeric, but got {type(sample_size)}")
+
+        # Add sample size info to result if available
+        if sample_sizes or sample_size is not None:
+            try:
+                result["metadata"]["sample_sizes"] = sample_sizes or [sample_size]
+            except TypeError as e:
+                raise TypeError(f"Error converting sample size data to list: {str(e)}") from e
+
+        # Handle annotations if present
         if analysis.annotations:
             result["labels"] = {}
-            for annotation in analysis.annotations.values():
-                result["labels"].update(annotation)
+            try:
+                for annotation in analysis.annotations.values():
+                    if not isinstance(annotation, dict):
+                        raise TypeError(
+                            f"Expected annotation to be dict, but got {type(annotation)}"
+                        )
+                    result["labels"].update(annotation)
+            except (TypeError, AttributeError) as e:
+                raise ValueError(f"Invalid annotation format: {str(e)}") from e
 
         return result
 
diff --git a/nimare/tests/test_io.py b/nimare/tests/test_io.py
index fdc3da632..d1207d041 100644
--- a/nimare/tests/test_io.py
+++ b/nimare/tests/test_io.py
@@ -22,6 +22,60 @@ def test_convert_nimads_to_dataset(example_nimads_studyset, example_nimads_annot
     assert isinstance(dset2, nimare.dataset.Dataset)
 
 
+def test_convert_nimads_to_dataset_sample_sizes(
+    example_nimads_studyset, example_nimads_annotation
+):
+    """Conversion of nimads JSON to nimare dataset."""
+    studyset = Studyset(example_nimads_studyset)
+    for study in studyset.studies:
+        for analysis in study.analyses:
+            analysis.metadata["sample_sizes"] = [2, 20]
+
+    dset = io.convert_nimads_to_dataset(studyset)
+
+    assert isinstance(dset, nimare.dataset.Dataset)
+    assert "sample_sizes" in dset.metadata.columns
+
+
+def test_convert_nimads_to_dataset_single_sample_size(
+    example_nimads_studyset, example_nimads_annotation
+):
+    """Test conversion of nimads JSON to nimare dataset with a single sample size value."""
+    studyset = Studyset(example_nimads_studyset)
+    for study in studyset.studies:
+        for analysis in study.analyses:
+            analysis.metadata["sample_size"] = 20
+
+    dset = io.convert_nimads_to_dataset(studyset)
+
+    assert isinstance(dset, nimare.dataset.Dataset)
+    assert "sample_sizes" in dset.metadata.columns
+
+
+def test_analysis_to_dict_invalid_sample_sizes_type(example_nimads_studyset):
+    """Test _analysis_to_dict raises ValueError when sample_sizes is not a list/tuple."""
+    studyset = Studyset(example_nimads_studyset)
+    # Set sample_sizes to an int rather than list/tuple
+    for study in studyset.studies:
+        for analysis in study.analyses:
+            analysis.metadata["sample_sizes"] = 5
+    with pytest.raises(TypeError):
+        # Trigger conversion which internally calls _analysis_to_dict
+        io.convert_nimads_to_dataset(studyset)
+
+
+def test_analysis_to_dict_invalid_annotations_format(example_nimads_studyset):
+    """Test _analysis_to_dict raises ValueError when annotations are in an invalid format."""
+    studyset = Studyset(example_nimads_studyset)
+    # Here we assume that the annotation is expected to be a dict
+    # Set annotation to an invalid format (e.g., a string)
+    for study in studyset.studies:
+        for analysis in study.analyses:
+            analysis.metadata["annotations"] = "invalid_format"
+    with pytest.raises(TypeError):
+        io.convert_nimads_to_dataset(studyset)
+
+
 def test_convert_sleuth_to_dataset_smoke():
     """Smoke test for Sleuth text file conversion."""
     sleuth_file = os.path.join(get_test_data_path(), "test_sleuth_file.txt")


Reviews:
user: login: sourcery-ai[bot]
body: Hey @jdkent - I've reviewed your changes - here's some feedback:

**Overall Comments**:
- Consider consolidating the sample size handling logic to reduce redundancy.
- It might be good to add a test case that covers the scenario where `sample_size` is in study metadata.

<details>
<summary>Here's what I looked at during the review</summary>

- 🟡 **General issues**: 1 issue found
- 🟢 **Security**: all looks good
- 🟡 **Testing**: 2 issues found
- 🟡 **Complexity**: 1 issue found
- 🟢 **Documentation**: all looks good
</details>

***

<details>
<summary>Sourcery is free for open source - if you like our reviews please consider sharing them ✨</summary>

- [X](https://twitter.com/intent/tweet?text=I%20just%20got%20an%20instant%20code%20review%20from%20%40SourceryAI%2C%20and%20it%20was%20brilliant%21%20It%27s%20free%20for%20open%20source%20and%20has%20a%20free%20trial%20for%20private%20code.%20Check%20it%20out%20https%3A//sourcery.ai)
- [Mastodon](https://mastodon.social/share?text=I%20just%20got%20an%20instant%20code%20review%20from%20%40SourceryAI%2C%20and%20it%20was%20brilliant%21%20It%27s%20free%20for%20open%20source%20and%20has%20a%20free%20trial%20for%20private%20code.%20Check%20it%20out%20https%3A//sourcery.ai)
- [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://sourcery.ai)
- [Facebook](https://www.facebook.com/sharer/sharer.php?u=https://sourcery.ai)

</details>

<sub>
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
</sub>
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-11T01:26:39Z

Review comments:
diff_hunk: @@ -62,13 +62,45 @@ def _analysis_to_dict(study, analysis):
                 "z": [p.z for p in analysis.points] or [None],
             },
         }
-        sample_size = study.metadata.get("sample_size")
-        if sample_size:
-            result["metadata"]["sample_sizes"] = [sample_size]
+
+        sample_sizes = analysis.metadata.get("sample_sizes")
+        sample_size = None
+
+        # Validate sample sizes if present
+        if sample_sizes is not None and not isinstance(sample_sizes, (list, tuple)):
+            raise TypeError(
path: nimare/io.py
user: login: sourcery-ai[bot]
body: **suggestion (bug_risk):** Review broad exception handling for annotations.

The try/except block around updating the 'labels' dictionary catches TypeError and AttributeError broadly and re-raises them as ValueError. This might mask issues that are not related to annotation formatting. Consider narrowing the exception scope to only the operations you expect might fail.
created_at: 2025-03-11T01:26:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -22,6 +22,21 @@ def test_convert_nimads_to_dataset(example_nimads_studyset, example_nimads_annot
     assert isinstance(dset2, nimare.dataset.Dataset)
 
 
+def test_convert_nimads_to_dataset_sample_sizes(
+    example_nimads_studyset, example_nimads_annotation
+):
+    """Conversion of nimads JSON to nimare dataset."""
+    studyset = Studyset(example_nimads_studyset)
+    for study in studyset.studies:
+        for analysis in study.analyses:
+            analysis.metadata["sample_sizes"] = [2, 20]
+
+    dset = io.convert_nimads_to_dataset(studyset)
+
+    assert isinstance(dset, nimare.dataset.Dataset)
+    assert "sample_sizes" in dset.metadata.columns
path: nimare/tests/test_io.py
user: login: sourcery-ai[bot]
body: **suggestion (testing):** Add tests for edge cases and error handling.

It would be beneficial to include tests that cover edge cases and error conditions within the `_analysis_to_dict` function, such as when `sample_sizes` is not a list/tuple, `sample_size` is not numeric, or when annotations have an invalid format.  This ensures that the error handling logic is robust and functions as expected.

Suggested implementation:

```python
def test_convert_nimads_to_dataset_sample_sizes(
    example_nimads_studyset, example_nimads_annotation
):
    """Conversion of nimads JSON to nimare dataset."""
    studyset = Studyset(example_nimads_studyset)
    for study in studyset.studies:
        for analysis in study.analyses:
            analysis.metadata["sample_sizes"] = [2, 20]

```

```python
import pytest
from nimare import io, dataset  # adjust imports as needed
from nimare.dataset import Dataset
from nimare.io import _analysis_to_dict  # assuming _analysis_to_dict is accessible for testing


```

```python
def test_analysis_to_dict_invalid_sample_sizes_type(example_nimads_studyset):
    """Test _analysis_to_dict raises ValueError when sample_sizes is not a list/tuple."""
    studyset = Studyset(example_nimads_studyset)
    # Set sample_sizes to an int rather than list/tuple
    for study in studyset.studies:
        for analysis in study.analyses:
            analysis.metadata["sample_sizes"] = 5
    with pytest.raises(ValueError):
        # Trigger conversion which internally calls _analysis_to_dict
        io.convert_nimads_to_dataset(studyset)


def test_analysis_to_dict_non_numeric_sample_sizes(example_nimads_studyset):
    """Test _analysis_to_dict raises ValueError when sample_sizes contains non-numeric values."""
    studyset = Studyset(example_nimads_studyset)
    # Set sample_sizes to a list with non-numeric value
    for study in studyset.studies:
        for analysis in study.analyses:
            analysis.metadata["sample_sizes"] = [2, "twenty"]
    with pytest.raises(ValueError):
        io.convert_nimads_to_dataset(studyset)


def test_analysis_to_dict_invalid_annotations_format(example_nimads_studyset):
    """Test _analysis_to_dict raises ValueError when annotations are in an invalid format."""
    studyset = Studyset(example_nimads_studyset)
    # Here we assume that the annotation is expected to be a dict
    # Set annotation to an invalid format (e.g., a string)
    for study in studyset.studies:
        for analysis in study.analyses:
            analysis.metadata["annotations"] = "invalid_format"
    with pytest.raises(ValueError):
        io.convert_nimads_to_dataset(studyset)

```

These tests assume that the underlying _analysis_to_dict function (or the conversion process in io.convert_nimads_to_dataset) performs robust type checking and raises a ValueError when encountering:
1. sample_sizes that is not a list/tuple,
2. sample_sizes with non-numeric values, and
3. annotations with an unexpected format.
You may need to adjust the exception type or the input modifications to match your actual implementation of error handling.
Also, ensure that the test file has access to the Studyset class and the necessary fixture definitions (example_nimads_studyset, example_nimads_annotation) or import them as needed.
created_at: 2025-03-11T01:26:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -22,6 +22,21 @@
     assert isinstance(dset2, nimare.dataset.Dataset)
 
 
+def test_convert_nimads_to_dataset_sample_sizes(
+    example_nimads_studyset, example_nimads_annotation
+):
+    """Conversion of nimads JSON to nimare dataset."""
+    studyset = Studyset(example_nimads_studyset)
+    for study in studyset.studies:
+        for analysis in study.analyses:
+            analysis.metadata["sample_sizes"] = [2, 20]
path: nimare/tests/test_io.py
user: login: sourcery-ai[bot]
body: **suggestion (testing):** Add test for single sample size.

Consider adding a test case where the `sample_size` is a single value instead of a list to ensure both code paths are tested.

Suggested implementation:

```python
def test_convert_nimads_to_dataset_single_sample_size(
    example_nimads_studyset, example_nimads_annotation
):
    """Test conversion of nimads JSON to nimare dataset with a single sample size value."""
    studyset = Studyset(example_nimads_studyset)
    for study in studyset.studies:
        for analysis in study.analyses:
            analysis.metadata["sample_sizes"] = 20

    dset = io.convert_nimads_to_dataset(studyset)

    assert isinstance(dset, nimare.dataset.Dataset)
    assert "sample_sizes" in dset.metadata.columns

def test_convert_sleuth_to_dataset_smoke():

```

Make sure your test runner picks up the new test function. You may need to adjust the placement of the new test according to your project's test suite conventions.
created_at: 2025-03-11T01:26:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -62,13 +62,45 @@
                 "z": [p.z for p in analysis.points] or [None],
             },
         }
-        sample_size = study.metadata.get("sample_size")
path: nimare/io.py
user: login: sourcery-ai[bot]
body: **issue (complexity):** Consider extracting the inline sample size and annotation validations into helper functions to improve readability and reduce nesting.

```markdown
Consider extracting the inline sample size and annotation validations into small helper functions. This will reduce nesting and improve readability. For example, you could do the following:

```python
def validate_sample_sizes(analysis_metadata, study_metadata):
    sample_sizes = analysis_metadata.get("sample_sizes")
    if sample_sizes is not None and not isinstance(sample_sizes, (list, tuple)):
        raise TypeError(
            f"Expected sample_sizes to be list or tuple, but got {type(sample_sizes)}"
        )
    if not sample_sizes:
        sample_size = analysis_metadata.get("sample_size") or study_metadata.get("sample_size")
        if sample_size is not None and not isinstance(sample_size, (int, float)):
            raise TypeError(
                f"Expected sample_size to be numeric, but got {type(sample_size)}"
            )
        return [sample_size] if sample_size is not None else None
    return sample_sizes

def validate_annotations(annotations):
    labels = {}
    for annotation in annotations.values():
        if not isinstance(annotation, dict):
            raise TypeError(
                f"Expected annotation to be dict, but got {type(annotation)}"
            )
        labels.update(annotation)
    return labels
```

Then simplify your main code as follows:

```python
sample_sizes_validated = validate_sample_sizes(analysis.metadata, study.metadata)
if sample_sizes_validated:
    try:
        result["metadata"]["sample_sizes"] = sample_sizes_validated
    except TypeError as e:
        raise TypeError(f"Error converting sample size data to list: {str(e)}") from e

if analysis.annotations:
    try:
        result["labels"] = validate_annotations(analysis.annotations)
    except (TypeError, AttributeError) as e:
        raise ValueError(f"Invalid annotation format: {str(e)}") from e
```

These changes isolate the validation logic into focused units, reducing complexity while preserving functionality.
```
created_at: 2025-03-11T01:26:39Z
author_association: CONTRIBUTOR

PR comments:
user: login: sourcery-ai[bot]
created_at: 2025-03-11T01:25:29Z
body: <!-- Generated by sourcery-ai[bot]: start review_guide -->

## Reviewer's Guide by Sourcery

This pull request introduces the ability to use `sample_sizes` as an analysis metadata variable when converting NiMADS data to a NiMARE dataset. It also includes validation and error handling improvements for sample sizes and annotations. The implementation involves modifying the `_analysis_to_dict` function in `nimare/io.py` to handle `sample_sizes` and adding a new test case in `nimare/tests/test_io.py` to verify the functionality.

#### Sequence diagram for converting analysis to dictionary with sample sizes

```mermaid
sequenceDiagram
  participant Study
  participant Analysis
  participant Result

  Analysis->>Analysis: Get sample_sizes from metadata
  alt sample_sizes is None or empty
    Analysis->>Analysis: Get sample_size from analysis metadata
    alt sample_size is None
      Analysis->>Study: Get sample_size from study metadata
    end
  end
  Analysis->>Result: Add sample_sizes to result metadata
  Result-->>Analysis: Return result
```

#### Updated class diagram for Analysis metadata handling

```mermaid
classDiagram
  class Study {
    metadata: dict
  }
  class Analysis {
    metadata: dict
    annotations: dict
  }
  class Result {
    metadata: dict
    labels: dict
  }
  Analysis --|> Study : Gets sample_size from
  Analysis --|> Result : Adds sample_sizes to
  Analysis --|> Result : Adds annotations to
  note for Analysis "Handles sample_sizes and annotations from metadata"
```

### File-Level Changes

| Change | Details | Files |
| ------ | ------- | ----- |
| Added support for `sample_sizes` as an analysis metadata variable when converting NiMADS to a NiMARE dataset. | <ul><li>Added validation to ensure `sample_sizes` is a list or tuple.</li><li>Added logic to extract a single `sample_size` from analysis or study metadata if `sample_sizes` is not available.</li><li>Added validation to ensure a single `sample_size` is numeric.</li><li>Added `sample_sizes` to the result metadata.</li><li>Added a test case to verify the correct conversion of `sample_sizes` from NiMADS to a NiMARE dataset.</li></ul> | `nimare/io.py`<br/>`nimare/tests/test_io.py` |
| Improved error handling for annotations. | <ul><li>Added a check to ensure that each annotation is a dictionary.</li><li>Improved the error message when an invalid annotation format is encountered.</li></ul> | `nimare/io.py` |

---

<details>
<summary>Tips and commands</summary>

#### Interacting with Sourcery

- **Trigger a new review:** Comment `@sourcery-ai review` on the pull request.
- **Continue discussions:** Reply directly to Sourcery's review comments.
- **Generate a GitHub issue from a review comment:** Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with `@sourcery-ai issue` to create an issue from it.
- **Generate a pull request title:** Write `@sourcery-ai` anywhere in the pull
  request title to generate a title at any time. You can also comment
  `@sourcery-ai title` on the pull request to (re-)generate the title at any time.
- **Generate a pull request summary:** Write `@sourcery-ai summary` anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment `@sourcery-ai summary` on the pull request to
  (re-)generate the summary at any time.
- **Generate reviewer's guide:** Comment `@sourcery-ai guide` on the pull
  request to (re-)generate the reviewer's guide at any time.
- **Resolve all Sourcery comments:** Comment `@sourcery-ai resolve` on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
- **Dismiss all Sourcery reviews:** Comment `@sourcery-ai dismiss` on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  `@sourcery-ai review` to trigger a new review!
- **Generate a plan of action for an issue:** Comment `@sourcery-ai plan` on
  an issue to generate a plan of action for it.

#### Customizing Your Experience

Access your [dashboard](https://app.sourcery.ai) to:
- Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
- Change the review language.
- Add, remove or edit custom review instructions.
- Adjust other review settings.

#### Getting Help

- [Contact our support team](mailto:support@sourcery.ai) for questions or feedback.
- Visit our [documentation](https://docs.sourcery.ai) for detailed guides and information.
- Keep in touch with the Sourcery team by following us on [X/Twitter](https://x.com/SourceryAI), [LinkedIn](https://www.linkedin.com/company/sourcery-ai/) or [GitHub](https://github.com/sourcery-ai).

</details>

<!-- Generated by sourcery-ai[bot]: end review_guide -->
author_association: CONTRIBUTOR
user: login: codecov[bot]
created_at: 2025-03-11T16:06:43Z
body: ## [Codecov](https://app.codecov.io/gh/neurostuff/NiMARE/pull/919?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff) Report
Attention: Patch coverage is `68.18182%` with `7 lines` in your changes missing coverage. Please review.
> Project coverage is 88.15%. Comparing base [(`895c154`)](https://app.codecov.io/gh/neurostuff/NiMARE/commit/895c1545cfb354358a5db755e8e2ab8c80d22f9c?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff) to head [(`42b749c`)](https://app.codecov.io/gh/neurostuff/NiMARE/commit/42b749c6eee074b4f76fa7bda8849b9003d77f42?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff).

| [Files with missing lines](https://app.codecov.io/gh/neurostuff/NiMARE/pull/919?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff) | Patch % | Lines |
|---|---|---|
| [nimare/io.py](https://app.codecov.io/gh/neurostuff/NiMARE/pull/919?src=pr&el=tree&filepath=nimare%2Fio.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff#diff-bmltYXJlL2lvLnB5) | 68.18% | [7 Missing :warning: ](https://app.codecov.io/gh/neurostuff/NiMARE/pull/919?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff) |

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff             @@
##             main     #919      +/-   ##
==========================================
- Coverage   88.23%   88.15%   -0.08%     
==========================================
  Files          48       48              
  Lines        6383     6400      +17     
==========================================
+ Hits         5632     5642      +10     
- Misses        751      758       +7     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/neurostuff/NiMARE/pull/919?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=neurostuff).

<details><summary>🚀 New features to boost your workflow: </summary>

- ❄ [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
</details>
author_association: NONE