.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/02_meta-analysis/plot_run_meta-analysis.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_02_meta-analysis_plot_run_meta-analysis.py>`
        to download the full example code.

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

.. _sphx_glr_auto_examples_02_meta-analysis_plot_run_meta-analysis.py:


.. _meta_basics:

=====================================
The Basics of Running a Meta-Analysis
=====================================

Here we walk through the basic steps of running a meta-analysis with PyMARE.

.. GENERATED FROM PYTHON SOURCE LINES 13-15

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

.. GENERATED FROM PYTHON SOURCE LINES 15-19

.. code-block:: Python

    from pprint import pprint

    from pymare import core, datasets, estimators








.. GENERATED FROM PYTHON SOURCE LINES 20-27

Load the data
-----------------------------------------------------------------------------
We will use the :footcite:t:`michael2013non` dataset, which comes from the
metadat library :footcite:p:`white2022metadat`.

We only want to do a mean analysis, so we won't have any covariates except for
an intercept.

.. GENERATED FROM PYTHON SOURCE LINES 27-31

.. code-block:: Python

    data, meta = datasets.michael2013()
    dset = core.Dataset(data=data, y="yi", v="vi", X=None, add_intercept=True)
    dset.to_df()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>y</th>
          <th>v</th>
          <th>intercept</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>0.23</td>
          <td>0.038539</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>1</th>
          <td>-0.04</td>
          <td>0.007195</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>2</th>
          <td>0.23</td>
          <td>0.016788</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>3</th>
          <td>0.11</td>
          <td>0.019805</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>4</th>
          <td>-0.04</td>
          <td>0.003913</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>5</th>
          <td>0.05</td>
          <td>0.002331</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>6</th>
          <td>0.31</td>
          <td>0.022049</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>7</th>
          <td>0.10</td>
          <td>0.024691</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>8</th>
          <td>0.33</td>
          <td>0.025544</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>9</th>
          <td>-0.05</td>
          <td>0.009700</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>10</th>
          <td>0.18</td>
          <td>0.009267</td>
          <td>1.0</td>
        </tr>
        <tr>
          <th>11</th>
          <td>-0.02</td>
          <td>0.009692</td>
          <td>1.0</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 32-58

Now we fit a model
-----------------------------------------------------------------------------
You must first initialize the estimator, after which you can use
:meth:`~pymare.estimators.estimators.BaseEstimator.fit` to fit the model to
numpy arrays, or
:meth:`~pymare.estimators.estimators.BaseEstimator.fit_dataset` to fit it to
a :class:`~pymare.core.Dataset`.

.. tip::
  We generally recommend using
  :meth:`~pymare.estimators.estimators.BaseEstimator.fit_dataset` over
  :meth:`~pymare.estimators.estimators.BaseEstimator.fit`.

  There are a number of methods, such as
  :meth:`~pymare.results.MetaRegressionResults.get_heterogeneity_stats` and
  :meth:`~pymare.results.MetaRegressionResults.permutation_test`,
  which only work when the Estimator is fitted to a Dataset.

  However, :meth:`~pymare.estimators.estimators.BaseEstimator.fit` requires
  less memory than :meth:`~pymare.estimators.estimators.BaseEstimator.fit_dataset`,
  so it can be useful for large-scale meta-analyses,
  such as neuroimaging image-based meta-analyses.

The :meth:`~pymare.estimators.estimators.BaseEstimator.summary` function
will return a :class:`~pymare.results.MetaRegressionResults` object,
which contains the results of the analysis.

.. GENERATED FROM PYTHON SOURCE LINES 58-62

.. code-block:: Python

    est = estimators.WeightedLeastSquares().fit_dataset(dset)
    results = est.summary()
    results.to_df()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>name</th>
          <th>estimate</th>
          <th>se</th>
          <th>z-score</th>
          <th>p-value</th>
          <th>ci_0.025</th>
          <th>ci_0.975</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>intercept</td>
          <td>0.052993</td>
          <td>0.026738</td>
          <td>1.981957</td>
          <td>0.047484</td>
          <td>0.000588</td>
          <td>0.105399</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 63-67

We can also extract some useful information from the results object
-----------------------------------------------------------------------------
The :meth:`~pymare.results.MetaRegressionResults.get_heterogeneity_stats`
method will calculate heterogeneity statistics.

.. GENERATED FROM PYTHON SOURCE LINES 67-69

.. code-block:: Python

    pprint(results.get_heterogeneity_stats())





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    {'H': array([1.19590745]),
     'I^2': array([30.07944649]),
     'Q': array([15.73214091]),
     'p(Q)': array([0.15136996])}




.. GENERATED FROM PYTHON SOURCE LINES 70-72

The :meth:`~pymare.results.MetaRegressionResults.get_re_stats` method will
estimate the confidence interval for :math:`\tau^2`.

.. GENERATED FROM PYTHON SOURCE LINES 72-74

.. code-block:: Python

    pprint(results.get_re_stats())





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    {'ci_l': array([0.]), 'ci_u': array([0.04013725]), 'tau^2': 0.0}




.. GENERATED FROM PYTHON SOURCE LINES 75-77

The :meth:`~pymare.results.MetaRegressionResults.permutation_test` method
will run a permutation test to estimate more accurate p-values.

.. GENERATED FROM PYTHON SOURCE LINES 77-80

.. code-block:: Python

    perm_results = results.permutation_test(n_perm=1000)
    perm_results.to_df()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>name</th>
          <th>estimate</th>
          <th>se</th>
          <th>z-score</th>
          <th>p-value</th>
          <th>p-value (perm.)</th>
          <th>ci_0.025</th>
          <th>ci_0.975</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>intercept</td>
          <td>0.052993</td>
          <td>0.026738</td>
          <td>1.981957</td>
          <td>0.047484</td>
          <td>0.068</td>
          <td>0.000588</td>
          <td>0.105399</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 81-84

References
-----------------------------------------------------------------------------
.. footbibliography::


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.018 seconds)


.. _sphx_glr_download_auto_examples_02_meta-analysis_plot_run_meta-analysis.py:

.. only:: html

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

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

      :download:`Download Jupyter notebook: plot_run_meta-analysis.ipynb <plot_run_meta-analysis.ipynb>`

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

      :download:`Download Python source code: plot_run_meta-analysis.py <plot_run_meta-analysis.py>`

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

      :download:`Download zipped: plot_run_meta-analysis.zip <plot_run_meta-analysis.zip>`


.. only:: html

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

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