diff --git a/docs/guide/Project/Results.md b/docs/guide/Project/Results.md new file mode 100644 index 0000000..4eaf784 --- /dev/null +++ b/docs/guide/Project/Results.md @@ -0,0 +1,33 @@ +--- +title: Results +sidebar_position: 4 +--- + +# Results + +This section will guide you on how to view, browse, and interpret the results of your meta-analysis. + +## Viewing Your Results + +Once your meta-analysis is complete, the results are automatically uploaded to both Neurosynth Compose and NeuroVault. You can view your results either in the cloud or within the environment where the analysis was run. + +To access your results, click the **NeuroVault Collection Link**. This link will direct you to a NeuroVault collection that contains all the images generated by the algorithm you selected for your analysis. + +For a detailed reference on the taxonomy of filenames generated by NiMARE, please refer to the [NiMARE documentation on outputs](https://nimare.readthedocs.io/en/stable/outputs.html). + +## Understanding the Outputs + +The results page will display a list of all images produced by your meta-analysis. These include unthresholded statistical maps, which allow for more flexible post-hoc thresholding based on your specific needs. + +### Interpreting Cluster-Level Corrected Maps + +It’s important to note that NiMARE outputs **unthresholded statistical maps**. This means you may need to apply your own thresholding to identify significant clusters. However, for cluster-level corrected maps, the output can sometimes cause confusion. + +Cluster-level correction is a method where the significance of a voxel cluster is determined after applying a voxel-wise cluster-defining threshold. In cluster-level corrected maps: +- Non-significant voxels are set to zero after applying the threshold. +- Each cluster that survives the cluster-defining threshold is assigned a single value, which is applied uniformly across all voxels in the cluster. + +Even clusters with relatively high p-values (i.e., less significant clusters) may still appear in the map, provided they surpass the initial cluster-defining threshold. As a result, some clusters may appear in the map even though they may not be highly significant at the overall level. + + +For further details on thresholding and interpreting the outputs, consult the [NiMARE documentation](https://nimare.readthedocs.io). diff --git a/docs/guide/Project/Running.md b/docs/guide/Project/Running.md index bc060bb..b5b5715 100644 --- a/docs/guide/Project/Running.md +++ b/docs/guide/Project/Running.md @@ -89,3 +89,12 @@ and then run the analysis using the following command: ``` nsc-runner ``` + +--- + +# Viewing and intepreting your results + +After successfully running your meta-analysis, results will be uploaded back to Neurosynth Compose and NeuroVault, where you can interactively view and interpret your results. +See the next section in the documentation for more detais. + +--- \ No newline at end of file diff --git a/docs/guide/Project/Specification.md b/docs/guide/Project/Specification.md index 263979d..4f2882b 100644 --- a/docs/guide/Project/Specification.md +++ b/docs/guide/Project/Specification.md @@ -3,6 +3,61 @@ title: Specification sidebar_position: 2 --- -## Work in progress! +# Meta-Analysis Specification -We're still working on completing the documentation for this. Please check back later. +Now that your studyset's studies have all the necessary information (metadata, coordinates, annotations), you can configure and run a meta-analysis! + +A wizard will guide you through the following key steps of meta-analysis specification. + + + + +### 1) **Select the Algorithm and Corrector** + *Choose the algorithm for your meta-analysis and, optionally, select a statistical correction method (corrector).* + + Neurosynth-Compose supports several meta-analysis algorithms, powered by NiMARE, a Python library for neuroimaging meta-analysis. + For an overview to the coordinate-based meta-analysis methods supported by NiMARE, [refer to this guide](https://nimare.readthedocs.io/en/stable/cbma.html). + + Supported coordinate-based methods include: + + - **MKDADensity** (default): Multi-Kernel Density Analysis. A popular density-based meta-analysis algorithm. Creates a binary sphere around each coordinate. + - **ALE**: Activation Likelihood Estimation, convolves coordinates with a 3D Gaussian distribution. + - **MKDAChi2**: Allows you to compare your meta-analysis studies with a larger reference set of studies. It tests whether a higher proportion of studies in your meta-analysis activate a specific voxel compared to a larger population of studies that were not included. For more details, [**see the MKDAChi2 Association tutorial**](/compose-docs/tutorial/advanced/mkda_association) + + For each algorithm, a default set of arguments is used, but you can easily modify them. For a complete reference on available arguments, see the [NiMARE API Docs](https://nimare.readthedocs.io/en/latest/api.html#nimare-meta-meta-analytic-algorithms). + +Next, select a method for [multiple comparisons correction](https://nimare.readthedocs.io/en/latest/cbma.html#multiple-comparisons-correction): + + + - **FDRCorrector** (default): False Discovery Rate correction. + - **FWECorrector**: Family-Wise Error Rate correction. We strongly recommend using FWECorrector for publication-quality results with 10,000s iteration if possible. This is computationally intensive however, hence not the default option. + +![Wizard 1](/guide/specification_wizard1.png) + + +### 2) **Select Analyses** + Now you will select which studies & analyses you want to include in your meta-analysis. To do so, select the annotation column for inclusion, which determines which analyses are used in the meta-analysis. By default, the "included" column contains all studies and analyses, but you can modify this based on your needs by editing `Annotations` in the Extraction step. + + A preview of the included studies based on the selected annotation column will be displayed. + +![Wizard 2](/guide/specification_wizard2.png) + + +### 3) **Meta-Analysis Details** + Enter a name and description for your meta-analysis to help you find it later. A default name will be provided, but you can customize it as needed. + +### 4) **Review** + Finally, you can review your selected options before creating your specification. + +![Wizard 3 Review](/guide/specification_wizard3.png) + +### 5) **Finalize** + To complete the specification process, click the "Create Meta-Analysis Specification" button. + +--- + +## Running the Meta-Analysis + +After clicking "Create Meta-Analysis Specification," you will be taken to a page displaying the status of your running analyses. Refer to the next section of the documentation for details on running and monitoring your meta-analysis. + +--- diff --git a/static/guide/specification_wizard1.png b/static/guide/specification_wizard1.png new file mode 100644 index 0000000..58a3da1 Binary files /dev/null and b/static/guide/specification_wizard1.png differ diff --git a/static/guide/specification_wizard2.png b/static/guide/specification_wizard2.png new file mode 100644 index 0000000..1ee96bd Binary files /dev/null and b/static/guide/specification_wizard2.png differ diff --git a/static/guide/specification_wizard3.png b/static/guide/specification_wizard3.png new file mode 100644 index 0000000..99d1265 Binary files /dev/null and b/static/guide/specification_wizard3.png differ