.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/01_basic_io/plot_create_dataset.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_basic_io_plot_create_dataset.py>`
        to download the full example code.

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

.. _sphx_glr_auto_examples_01_basic_io_plot_create_dataset.py:


.. _io1:

==================
Creating a dataset
==================

In PyMARE, operations are performed on :class:`~pymare.core.Dataset` objects.
Datasets are very lightweight objects that store the data used for
meta-analyses, including study-level estimates (y), variances (v),
predictors (X), and sample sizes (n).

.. GENERATED FROM PYTHON SOURCE LINES 14-16

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

.. GENERATED FROM PYTHON SOURCE LINES 16-22

.. code-block:: Python

    from pprint import pprint

    import pandas as pd

    from pymare import core








.. GENERATED FROM PYTHON SOURCE LINES 23-32

Datasets can be created from arrays
-----------------------------------
The simplest way to create a dataset is to pass in arguments as numpy arrays.

``y`` refers to the study-level estimates, ``v`` to the variances,
``X`` to any study-level regressors, and ``n`` to the sample sizes.

Not all Estimators require all of these arguments, so not all need to be
used in a given Dataset.

.. GENERATED FROM PYTHON SOURCE LINES 32-40

.. code-block:: Python

    y = [2, 4, 6]
    v = [100, 100, 100]
    X = [[5, 9], [2, 8], [1, 7]]

    dataset = core.Dataset(y=y, v=v, X=X, X_names=["X1", "X7"])

    pprint(vars(dataset))





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

 .. code-block:: none

    {'X': array([[1., 5., 9.],
           [1., 2., 8.],
           [1., 1., 7.]]),
     'X_names': ['intercept', 'X1', 'X7'],
     'n': None,
     'v': array([[100],
           [100],
           [100]]),
     'y': array([[2],
           [4],
           [6]])}




.. GENERATED FROM PYTHON SOURCE LINES 41-42

Datasets have the :meth:`~pymare.core.Dataset.to_df` method.

.. GENERATED FROM PYTHON SOURCE LINES 42-44

.. code-block:: Python

    dataset.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>
          <th>X1</th>
          <th>X7</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>2</td>
          <td>100</td>
          <td>1.0</td>
          <td>5.0</td>
          <td>9.0</td>
        </tr>
        <tr>
          <th>1</th>
          <td>4</td>
          <td>100</td>
          <td>1.0</td>
          <td>2.0</td>
          <td>8.0</td>
        </tr>
        <tr>
          <th>2</th>
          <td>6</td>
          <td>100</td>
          <td>1.0</td>
          <td>1.0</td>
          <td>7.0</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 45-47

Datasets can also be created from pandas DataFrames
---------------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 47-60

.. code-block:: Python

    df = pd.DataFrame(
        {
            "y": [2, 4, 6],
            "v_alt": [100, 100, 100],
            "X1": [5, 2, 1],
            "X7": [9, 8, 7],
        }
    )

    dataset = core.Dataset(v="v_alt", X=["X1", "X7"], data=df, add_intercept=False)

    pprint(vars(dataset))





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

 .. code-block:: none

    {'X': array([[5, 9],
           [2, 8],
           [1, 7]]),
     'X_names': ['X1', 'X7'],
     'n': None,
     'v': array([[100],
           [100],
           [100]]),
     'y': array([[2],
           [4],
           [6]])}




.. GENERATED FROM PYTHON SOURCE LINES 61-68

Datasets can also contain multiple dependent variables
------------------------------------------------------
These variables are analyzed in parallel, but as unrelated variables,
rather than as potentially correlated ones.

This is particularly useful for image-based neuroimaging meta-analyses.
For more information about this, see `NiMARE <https://nimare.readthedocs.io>`_.

.. GENERATED FROM PYTHON SOURCE LINES 68-84

.. code-block:: Python

    y = [
        [2, 4, 6],  # Estimates for first study's three outcome variables.
        [3, 2, 1],  # Estimates for second study's three outcome variables.
    ]
    v = [
        [100, 100, 100],  # Estimate variances for first study's three outcome variables.
        [8, 4, 2],  # Estimate variances for second study's three outcome variables.
    ]
    X = [
        [5, 9],  # Predictors for first study. Same across all three outcome variables.
        [2, 8],  # Predictors for second study. Same across all three outcome variables.
    ]

    dataset = core.Dataset(y=y, v=v, X=X, X_names=["X1", "X7"])

    pprint(vars(dataset))




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

 .. code-block:: none

    {'X': array([[1., 5., 9.],
           [1., 2., 8.]]),
     'X_names': ['intercept', 'X1', 'X7'],
     'n': None,
     'v': array([[100, 100, 100],
           [  8,   4,   2]]),
     'y': array([[2, 4, 6],
           [3, 2, 1]])}





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

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


.. _sphx_glr_download_auto_examples_01_basic_io_plot_create_dataset.py:

.. only:: html

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

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

      :download:`Download Jupyter notebook: plot_create_dataset.ipynb <plot_create_dataset.ipynb>`

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

      :download:`Download Python source code: plot_create_dataset.py <plot_create_dataset.py>`

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

      :download:`Download zipped: plot_create_dataset.zip <plot_create_dataset.zip>`


.. only:: html

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

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