.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/01_datasets/08_fetch_neurostore.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_01_datasets_08_fetch_neurostore.py>`
        to download the full example code or to run this example in your browser via JupyterLite.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_01_datasets_08_fetch_neurostore.py:


.. _datasets_neurostore:

===============================
Download NeuroStore coordinates
===============================

`NeuroStore <https://neurostore.org>`_ is the maintained, continuously-updated database of
neuroimaging coordinates behind `Neurosynth Compose <https://compose.neurosynth.org>`_, and it is
where new NiMARE analyses should get their coordinate data.

NeuroStore publishes periodic snapshots of the whole database as
`studyset releases <https://neurostore.org/api/neurostore-studyset-releases/>`_: archives of
parquet tables that load straight into a :class:`~nimare.nimads.Studyset`
(see :ref:`parquet_studyset` for the file layout). :func:`~nimare.extract.fetch_neurostore`
downloads, checksums, and extracts one of those releases for you.

.. note::
    Reading the parquet tables requires ``pyarrow``, which NiMARE ships as an extra::

        pip install nimare[parquet]

.. warning::
    :func:`~nimare.extract.fetch_neurosynth` (see :ref:`datasets_databases`) downloads a frozen
    snapshot of Neurosynth, whose coordinates were extracted in 2018. It is deprecated and will be
    removed in NiMARE 1.0.0. Keep using it only to reproduce published Neurosynth analyses, or to
    get the Neurosynth term annotations that NiMARE's Neurosynth-based decoders need.

For information about where these files will be downloaded to on your machine,
see :doc:`../../fetching`.

.. GENERATED FROM PYTHON SOURCE LINES 35-37

Start with the necessary imports
-----------------------------------------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 37-41

.. code-block:: Python

    import os

    from nimare.extract import fetch_neurostore, fetch_neurostore_releases


.. GENERATED FROM PYTHON SOURCE LINES 42-46

See which releases are available
-----------------------------------------------------------------------------
NeuroStore publishes dated releases (one per month) plus a rolling ``nightly`` build.
Each entry reports when it was built and how much data it holds.

.. GENERATED FROM PYTHON SOURCE LINES 46-52

.. code-block:: Python

    for release in fetch_neurostore_releases():
        print(
            f"{release['version']:>10} ({release['release_type']}): "
            f"{release['study_count']} studies, built {release['built_at']}"
        )


.. GENERATED FROM PYTHON SOURCE LINES 53-61

Download the most recent release
-----------------------------------------------------------------------------
``version="latest"`` (the default) takes the most recent dated release. Pass
``version="nightly"`` for the rolling build, or an explicit version such as
``version="2026-09"`` to pin an analysis to a specific snapshot.

The release is cached on disk, so re-running this is cheap; pass ``overwrite=True``
to force a fresh download.

.. GENERATED FROM PYTHON SOURCE LINES 61-70

.. code-block:: Python

    out_dir = os.path.abspath("../example_data/")
    os.makedirs(out_dir, exist_ok=True)

    studyset = fetch_neurostore(data_dir=out_dir)
    print(studyset)
    print(f"Studyset ID: {studyset.id}")
    print(f"Number of studies: {len(studyset.study_ids)}")
    print(f"Number of analyses: {len(studyset.ids)}")


.. GENERATED FROM PYTHON SOURCE LINES 71-75

Inspect the coordinates
-----------------------------------------------------------------------------
The Studyset exposes the standard table views, so the release is ready for
filtering, annotation, and meta-analysis.

.. GENERATED FROM PYTHON SOURCE LINES 75-77

.. code-block:: Python

    print(studyset.coordinates.head())


.. GENERATED FROM PYTHON SOURCE LINES 78-82

Keep the extracted files instead
-----------------------------------------------------------------------------
``return_type="files"`` skips loading and returns the path to the extracted parquet
directory, which can be loaded later with ``Studyset(path)``.

.. GENERATED FROM PYTHON SOURCE LINES 82-86

.. code-block:: Python

    release_dir = fetch_neurostore(data_dir=out_dir, return_type="files")
    print(release_dir)
    print(sorted(os.listdir(release_dir)))


.. GENERATED FROM PYTHON SOURCE LINES 87-92

Download a single studyset instead of the whole database
-----------------------------------------------------------------------------
To fetch one curated studyset (for example, one assembled in Neurosynth Compose)
rather than a full release, use :func:`~nimare.io.fetch_neurostore_studyset` with the
studyset's NeuroStore ID.


.. _sphx_glr_download_auto_examples_01_datasets_08_fetch_neurostore.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: lite-badge

      .. image:: images/jupyterlite_badge_logo.svg
        :target: ../../lite/lab/index.html?path=auto_examples/01_datasets/08_fetch_neurostore.ipynb
        :alt: Launch JupyterLite
        :width: 150 px

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 08_fetch_neurostore.ipynb <08_fetch_neurostore.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 08_fetch_neurostore.py <08_fetch_neurostore.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 08_fetch_neurostore.zip <08_fetch_neurostore.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_