.. currentmodule:: socceraction.data

*************
Loading data
*************

Socceraction provides API clients for various popular event stream data
sources. These clients enable fetching event streams and their corresponding
metadata as Pandas DataFrames using a unified data model.
Alternatively, you can also use `kloppy <https://kloppy.pysport.org/>`__ to
load data.

Loading data with socceraction
==============================

All API clients implemented in socceraction inherit from the
:class:`~base.EventDataLoader` interface. This interface provides the
following methods to retrieve data as a Pandas DataFrames with a unified data
model (i.e., :class:`~pandera.Schema`). The schema defines the minimal set of
columns and their types that are returned by each method. Implementations of
the :class:`~base.EventDataLoader` interface may add additional columns.

.. list-table::
   :widths: 40 20 40
   :header-rows: 1

   * - Method
     - Output schema
     - Description
   * - :meth:`competitions() <base.EventDataLoader.competitions>`
     - :class:`~schema.CompetitionSchema`
     - All available competitions and seasons
   * - :meth:`games(competition_id, season_id) <base.EventDataLoader.games>`
     - :class:`~schema.GameSchema`
     - All available games in a season
   * - :meth:`teams(game_id) <base.EventDataLoader.teams>`
     - :class:`~schema.TeamSchema`
     - Both teams that participated in a game
   * - :meth:`players(game_id) <base.EventDataLoader.players>`
     - :class:`~schema.PlayerSchema`
     - All players that participated in a game
   * - :meth:`events(game_id) <base.EventDataLoader.events>`
     - :class:`~schema.EventSchema`
     - The event stream of a game

Currently, the following data providers are supported:

.. toctree::
  :maxdepth: 1

  statsbomb
  wyscout
  opta


Loading data with kloppy
=========================

Similarly to socceraction, `kloppy <https://kloppy.pysport.org/>`__ implements
a unified data model for soccer data. The main differences between kloppy and
socceraction are: (1) kloppy supports more data sources (including tracking
data), (2) kloppy uses a more flexible object-based data model in contrast to
socceraction's dataframe-based model, and (3) kloppy covers a more complete
set of events while socceraction focuses on-the-ball events. Thus, we recommend
using kloppy if you want to load data from a source that is not supported by
socceraction or when your analysis is not limited to on-the-ball events.

The following code snippet shows how to load data from StatsBomb using
kloppy::

  from kloppy import statsbomb

  dataset = statsbomb.load_open_data(match_id=8657)

Instructions for loading data from other sources can be found in the
`kloppy documentation <https://kloppy.pysport.org/>`__.

You can then convert the data to the SPADL format using the
:func:`~socceraction.spadl.kloppy.convert_to_actions` function::

  from socceraction.spadl.kloppy import convert_to_actions

  spadl_actions = convert_to_actions(dataset, game_id=8657)


.. note::

   Currently, the data model of kloppy is only complete for StatsBomb data.
   If you use kloppy to load data from other sources and convert it to the
   SPADL format, you may lose some information.