Merge pull request #10 from neurostuff/mkda

MKDA Chi Squared tutorial, December blog post, and How to run instructions

Author: adelavega

blog/2024-1-2-new-year.md

@@ -0,0 +1,56 @@
+---
+title: New Year Updates
+authors: alejandro
+tags: [neurosynth]
+---
+Hello Neurosynth Users,
+
+Happy New Year! 
+
+2023 was a very exciting year for Neurosynth, having launched our Compose platform to the public and announced it on social media. In the December we’ve saw **over 500 new user visits**, with **200 users signing up for an account**! 🚀
+
+Help us keep this growth going by [sharing our announcement](./blog/announcing-ns-compose) with your colleagues. 🧑‍🔬
+
+# 🌟 What’s New 🌟
+
+We’ve also continued to introduce new features and improve the user experience. Here’s some highlights:
+
+### Large-scale association tests
+
+A key feature that set Neurosynth aside were large-scale association maps (previously known as “reverse inference”).
+
+Whereas a typical meta-analysis tells you if activity is consistently reported in a target set of studies, an association test tells you if **activation occurs more consistently in this set of studies versus a large and diverse reference sample**. 
+
+That's important, because this allows you to control for base rate differences between regions. Certain regions, such as the insula or lateral PFC for instance, play a very broad role in cognition, and hence are consistently activated for many different tasks and cognitive states. Thus, if you see insula activity in your meta-analysis, you might erroneously conclude that the insula is involved in the cognitive state you're studying. A large-scale association test lets you determine if the activity you observe in a region occurs *more consistently* in your meta-analysis than in other studies, making it possible to make more confident claims that a given region is involved in a particular process, and isn't involved in just about every task.
+
+Previously association tests were available for the automatically generated maps on neurosynth.org. **Now you can perform large-scale association tests for your custom meta-analyses in Neurosynth Compose.**
+
+We have created a full primer and tutorial on MKDA Chi-Squared, including an example from a recent meta-analysis on social processing. Check it out!
+
+import Button from '@mui/material/Button';
+
+<Button variant="contained" color="primary" href='tutorial/advanced/mkda_association'>
+    MKDA Chi-Squared Tutorial 🧑‍🎓
+</Button>
+
+### UX Enhancements ✨
+
+Based on your valuable feedback, we've made numerous bug fixes and improvements: 
+
+* **Simplified Curation**: The review import page has been removed, and summary information is now added directly to the tag step.
+
+* **Searching UI**: We've replaced the dropdown with a selection gallery, making it easier to choose your preferred search method, and we now auto-generate search import names. In addition, resolving duplicates is skipped if none are present. 
+
+* **Improved Editing Workflow**: The editing interface has been improved, streamlining the extraction process. 
+
+* **Various UX Improvements and Fixes**: We fixed many papercuts, especially in the *Extraction* phase.
+
+
+We hope you enjoy these changes.
+
+Email us any [feedback](mailto:[email protected]), or ask a question on [NeuroStars](https://neurostars.org/tag/neurosynth-compose) if you have issues.
+
+
+Cheers,
+
+The Neurosynth Team 🧠

docs/guide/walkthrough/Studies/Searching.md renamed to docs/guide/Explore/Searching.md

@@ -0,0 +1,26 @@
+---
+title: Explore
+sidebar_position: 1
+---
+
+# Explore
+
+Here, you can browse and search existing public `Studies`, `StudySets` and `Meta-Analyses` created on the platform. 
+
+## Studies
+
+The `Studies` page lets you browse and search all studies that exist on the NeuroStore server. This interface is similar to what you'll see when importing studies into your `Project`. However, here it's simply provided for your browsing pleasure. 
+
+For more information on how advanced search functionally, see [Searching Studies](./Explore/Searching)
+
+## StudySets and Meta-Analyses
+
+For `StudySets` and `Meta-Analyses`, you can browse and search any user-contributed items, including those from other users. 
+
+Note that although you see all publically available items, you cannot edit somebody else's content. 
+
+:::note
+We are currently working on a way to allow users to fork other users' `StudySets` and `Meta-Analyses` to create their own versions.
+Stay tuned!
+::::
+

docs/guide/Explore/index.mdx

@@ -15,7 +15,7 @@ After the curation phase is complete, the user is redirected to the extraction p
 Here, the extraction phase starts when 
 a wizard that pops up and guides the user through the process of initializing the extraction phase. On top of creating the 
 initial [**annotation columns**](./Extraction#annotations), this wizard also guides the user through the
-process of [**ingestion** ](./Extraction#ingestion) of the curated studies to create a new [**studyset**](../../glossary#studyset).
+process of [**ingestion** ](./Extraction#ingestion) of the curated studies to create a new [**studyset**](../glossary#studyset).
 
 ## Ingestion
 

docs/guide/walkthrough/Project/Curation.md renamed to docs/guide/Project/Curation.md

@@ -11,9 +11,8 @@ Within a project you will be able to:
  1. **[Curate](./Project/Curation)** studies of interest and select the ones to be included in the meta-analysis 
  2. **[Extract](./Project/Extraction)** the relevant data such as activation coordinates and other meta-data
  3. **[Specify](./Project/Specification)** the algorithm and corrector you would like to use
- 4. **Run** the meta-analysis and **View** the results
 
-In each project, you can define a define a single StudySe (i.e. a collection of related studies), and one or more MetaAnalysis specifications.
+In each project, you can define a define a single StudySet (i.e. a collection of related studies), and one or more MetaAnalysis specifications.
 
 
 You can open a specific project by logging in, navigating to the 

docs/guide/walkthrough/Project/Extraction.md renamed to docs/guide/Project/Extraction.md

@@ -0,0 +1,85 @@
+---
+title: Running Analyses
+sidebar_position: 2
+---
+
+# Running Analyses
+
+You have a several options for running the analysis. In all cases, you will need your unique `<meta-analysis-id>`, which you can access for each Meta-Analysis within your Project.
+
+![Meta-analysis run](/tutorial/ma_run.png)
+
+Under the hood, analyses are managed by the [nsc-runner](https://github.com/neurostuff/nsc-runner) Python package, and executed by the [NiMARE](https://nimare.readthedocs.io/en/stable/) (Neuroimaging Meta-Analysis Research Environment) Python package. 
+
+## Google Colab
+
+[![text](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/neurostuff/neurosynth-compose-notebook/blob/main/run_and_explore.ipynb)
+
+The easiest way to run an analysis is to use the [Google Colab](https://colab.research.google.com/) notebook linked above.
+
+The provided notebook runs entirely in the cloud, and does not require any local installation of software.
+To use simply paste your analysis ID into the first cell (`META_ID`), and using the Toolbar selet (Runtime -> Run All) 
+or the keyboard shortcut (Ctrl or ⌘ + F9) to run the notebook.
+
+![Colab notebook](/guide/nsc_colab_notebook.png)
+
+The notebook will install all required software, run the analysis, and upload the results to Neurosynth Compose.
+Once the analysis is complete, you can use the notebook to explore the results using the interative report, download an archive 
+of the results, or browse the results in the Neurosynth Compose web interface, in the Meta-Analysis section of your Project.
+
+:::tip
+The Colab notebook has limited and varying freely available resources, and may not be able to run large analyses.
+If your analysis fails, try running it again, or using one of the other methods below.
+:::
+
+## Docker 
+
+The easiest way to run analyses locally is to use the `nsc-runner` [Docker](https://www.docker.com/) image provided by Neurosynth Compose.
+
+Docker is a containerization technology that allows you to run software in a consistent environment, regardless of the underlying operating system.
+
+To run the Docker image, you will need to install Docker on your local machine.
+Instructions for installing Docker can be found [here](https://docs.docker.com/get-docker/).
+
+Once Docker is installed, you can run your analysis using the using the following command:
+
+```
+docker run -it -v -v /local/dir:/results ghcr.io/neurostuff/nsc-runner:latest <meta-analysis-id>
+```
+
+where `/local/dir` is the path to a local directory where you would like to save the results of your analysis, and `<meta-analysis-id>` is the ID of the meta-analysis you would like to run.
+
+The Docker image will download all required software, run the analysis, and upload the results to Neurovault & Neurosynth Compose.
+An HTML report will be saved in the results directory, and the results will be available in the Meta-Analysis section of your Project on Neurosynth Compose.
+
+### Updating the Docker image
+
+For every release of `nsc-runner`, we publish a corresponding Docker image.
+
+You can manually download a specific neuroscout-cli release as follows:
+
+```
+docker pull ghcr.io/neurostuff/nsc-runner:<version>
+```
+
+where `<version>` is the version of `nsc-runner` that you want to download. If you omit version, the latest stable version will be downloaded.
+
+You can see the tags available for download on [GitHub](https://github.com/neurostuff/compose-runner/pkgs/container/nsc-runner)
+
+## Manually prepared environment using pip 
+
+:::warning
+Manually installing `nsc-runner` may be difficult due to complex dependencies in the SciPy stack, or fMRI-specific tooling. Proceed only if you know what you’re doing.
+:::
+
+Use pip to install `nsc-runner` from PyPI:
+
+```
+pip install nsc-runner
+```
+
+and then run the analysis using the following command:
+
+```
+nsc-runner <meta-analysis-id>
+```

docs/guide/walkthrough/Project/Specification.md renamed to docs/guide/Project/Specification.md

@@ -1,6 +1,6 @@
 ---
 title: Glossary
-sidebar_position: 1
+sidebar_position: 3
 ---
 
 # Glossary