<commit_before>.. include:: references.txt
.. |join| replace:: :func:`~astropy.table.operations.join`

.. _table_operations:

Table operations
-----------------

In this section we describe higher-level operations that can be used to generate a new
table from two or more input tables.  This includes:

=======================

.. list-table::
   :header-rows: 1
   :widths: 28 52 20

   * - Documentation
     - Description
     - Function
   * - `Stack vertically`_
     - Concatenate input tables along rows
     - `~astropy.table.operations.vstack`
   * - `Stack horizontally`_
     - Concatenate input tables along columns
     - `~astropy.table.operations.hstack`
   * - `Join`_
     - Database-style join of two tables
     - `~astropy.table.operations.join`


Stack vertically
^^^^^^^^^^^^^^^^^^^^

The |Table| class supports stacking tables vertically with the
`~astropy.table.operations.vstack` function.  This process is also commonly known as
concatenating or appending tables in the row direction.  It corresponds roughly
to the `numpy.vstack` function.

For example, suppose one has two tables of observations with several
column names in common::

  >>> from astropy.table import Table, vstack
  >>> obs1 = Table.read("""name    obs_date    mag_b  logLx
                           M31     2012-01-02  17.0   42.5
                           M82     2012-10-29  16.2   43.5
                           M101    2012-10-31  15.1   44.5""", format='ascii')

  >>> obs2 = Table.read("""name    obs_date    logLx
                           NGC3516 2011-11-11  42.1
                           M31     1999-01-05  43.1
                           M82     2012-10-30  45.0""", format='ascii')

Now we can stack these two tables::

  >>> print vstack([obs1, obs2])
    name   obs_date  mag_b logLx
  ------- ---------- ----- -----
      M31 2012-01-02  17.0  42.5
      M82 2012-10-29  16.2  43.5
     M101 2012-10-31  15.1  44.5
  NGC3516 2011-11-11    --  42.1
      M31 1999-01-05    --  43.1
      M82 2012-10-30    --  45.0

Notice that the ``obs2`` table is missing the ``mag_b`` column, so in the stacked output
table those values are marked as missing.  This is the default behavior and corresponds to
``join_type='outer'``.  There are two other allowed values for the ``join_type`` argument,
``'inner'`` and ``'exact'``::

  >>> print vstack([obs1, obs2], join_type='inner')
    name   obs_date  logLx
  ------- ---------- -----
      M31 2012-01-02  42.5
      M82 2012-10-29  43.5
     M101 2012-10-31  44.5
  NGC3516 2011-11-11  42.1
      M31 1999-01-05  43.1
      M82 2012-10-30  45.0

  >>> print vstack([obs1, obs2], join_type='exact')
  ...
  TableMergeError: Inconsistent columns in input arrays (use 'inner' or
  'outer' join_type to allow non-matching columns)

In the case of ``join_type='inner'`, only the common columns (the intersection) are
present in the output table.  When ``join_type='exact'`` is specified then
`~astropy.table.operations.vstack` requires that all the input tables
have exactly the same column names.

More than two tables can be stacked by supplying a list of table objects::

  >>> obs3 = Table.read("""name    obs_date    mag_b  logLx
                           M45     2012-02-03  15.0   40.5""", format='ascii')
  >>> print vstack([obs1, obs2, obs3])
    name   obs_date  mag_b logLx
  ------- ---------- ----- -----
      M31 2012-01-02  17.0  42.5
      M82 2012-10-29  16.2  43.5
     M101 2012-10-31  15.1  44.5
  NGC3516 2011-11-11    --  42.1
      M31 1999-01-05    --  43.1
      M82 2012-10-30    --  45.0
      M45 2012-02-03  15.0  40.5

See also the sections on `Merging metadata`_ and `Merging column
attributes`_ for details on how these characteristics of the input tables are merged in
the single output table.

Stack horizontally
^^^^^^^^^^^^^^^^^^^^^

The |Table| class supports stacking tables horizontally (in the column-wise direction) with the
`~astropy.table.operations.hstack` function.    It corresponds roughly
to the `numpy.hstack` function.<commit_msg>Fix trivial typo in table documentation.<commit_after>.. include:: references.txt
.. |join| replace:: :func:`~astropy.table.operations.join`

.. _table_operations:

Table operations
-----------------

In this section we describe higher-level operations that can be used to generate a new
table from two or more input tables.  This includes:

=======================

.. list-table::
   :header-rows: 1
   :widths: 28 52 20

   * - Documentation
     - Description
     - Function
   * - `Stack vertically`_
     - Concatenate input tables along rows
     - `~astropy.table.operations.vstack`
   * - `Stack horizontally`_
     - Concatenate input tables along columns
     - `~astropy.table.operations.hstack`
   * - `Join`_
     - Database-style join of two tables
     - `~astropy.table.operations.join`


Stack vertically
^^^^^^^^^^^^^^^^^^^^

The |Table| class supports stacking tables vertically with the
`~astropy.table.operations.vstack` function.  This process is also commonly known as
concatenating or appending tables in the row direction.  It corresponds roughly
to the `numpy.vstack` function.

For example, suppose one has two tables of observations with several
column names in common::

  >>> from astropy.table import Table, vstack
  >>> obs1 = Table.read("""name    obs_date    mag_b  logLx
                           M31     2012-01-02  17.0   42.5
                           M82     2012-10-29  16.2   43.5
                           M101    2012-10-31  15.1   44.5""", format='ascii')

  >>> obs2 = Table.read("""name    obs_date    logLx
                           NGC3516 2011-11-11  42.1
                           M31     1999-01-05  43.1
                           M82     2012-10-30  45.0""", format='ascii')

Now we can stack these two tables::

  >>> print vstack([obs1, obs2])
    name   obs_date  mag_b logLx
  ------- ---------- ----- -----
      M31 2012-01-02  17.0  42.5
      M82 2012-10-29  16.2  43.5
     M101 2012-10-31  15.1  44.5
  NGC3516 2011-11-11    --  42.1
      M31 1999-01-05    --  43.1
      M82 2012-10-30    --  45.0

Notice that the ``obs2`` table is missing the ``mag_b`` column, so in the stacked output
table those values are marked as missing.  This is the default behavior and corresponds to
``join_type='outer'``.  There are two other allowed values for the ``join_type`` argument,
``'inner'`` and ``'exact'``::

  >>> print vstack([obs1, obs2], join_type='inner')
    name   obs_date  logLx
  ------- ---------- -----
      M31 2012-01-02  42.5
      M82 2012-10-29  43.5
     M101 2012-10-31  44.5
  NGC3516 2011-11-11  42.1
      M31 1999-01-05  43.1
      M82 2012-10-30  45.0

  >>> print vstack([obs1, obs2], join_type='exact')
  ...
  TableMergeError: Inconsistent columns in input arrays (use 'inner' or
  'outer' join_type to allow non-matching columns)

In the case of ``join_type='inner'``, only the common columns (the intersection) are
present in the output table.  When ``join_type='exact'`` is specified then
`~astropy.table.operations.vstack` requires that all the input tables
have exactly the same column names.

More than two tables can be stacked by supplying a list of table objects::

  >>> obs3 = Table.read("""name    obs_date    mag_b  logLx
                           M45     2012-02-03  15.0   40.5""", format='ascii')
  >>> print vstack([obs1, obs2, obs3])
    name   obs_date  mag_b logLx
  ------- ---------- ----- -----
      M31 2012-01-02  17.0  42.5
      M82 2012-10-29  16.2  43.5
     M101 2012-10-31  15.1  44.5
  NGC3516 2011-11-11    --  42.1
      M31 1999-01-05    --  43.1
      M82 2012-10-30    --  45.0
      M45 2012-02-03  15.0  40.5

See also the sections on `Merging metadata`_ and `Merging column
attributes`_ for details on how these characteristics of the input tables are merged in
the single output table.

Stack horizontally
^^^^^^^^^^^^^^^^^^^^^

The |Table| class supports stacking tables horizontally (in the column-wise direction) with the
`~astropy.table.operations.hstack` function.    It corresponds roughly
to the `numpy.hstack` function.
{'fraction_non_alphanumeric': 0.13562252964426877, 'fraction_numerical': 0.09955533596837944, 'mean_word_length': 2.199130778348479, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 51, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 10, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6927225', 'n_tokens_mistral': 3069, 'n_tokens_neox': 2550, 'n_words': 844}