Skip to content

Common

Classes

kloppy.domain.models.common.Metadata dataclass

Metadata

Attributes:

Name Type Description
teams List[kloppy.domain.models.common.Team]

[home_team, away_team]. See Team

periods List[kloppy.domain.models.common.Period]

See Period

pitch_dimensions PitchDimensions

See PitchDimensions

score Score

See Score

frame_rate float
orientation Orientation

See Orientation

flags DatasetFlag
provider Provider

See Provider

Source code in kloppy/domain/models/common.py
class Metadata:
    """
    Metadata

    Attributes:
        teams: `[home_team, away_team]`. See [`Team`][kloppy.domain.models.common.Team]
        periods: See [`Period`][kloppy.domain.models.common.Period]
        pitch_dimensions: See [`PitchDimensions`][kloppy.domain.models.pitch.PitchDimensions]
        score: See [`Score`][kloppy.domain.models.common.Score]
        frame_rate:
        orientation: See [`Orientation`][kloppy.domain.models.common.Orientation]
        flags:
        provider: See [`Provider`][kloppy.domain.models.common.Provider]
    """

    teams: List[Team]
    periods: List[Period]
    pitch_dimensions: PitchDimensions
    score: Score
    frame_rate: float
    orientation: Orientation
    flags: DatasetFlag
    provider: Provider
    coordinate_system: CoordinateSystem

kloppy.domain.models.common.Player dataclass

Attributes:

Name Type Description
player_id str

identifier given by the provider

team Team

See Team

jersey_no int

Jersey number

name str

Full name of the player

first_name str

First name

last_name str

Last name

starting bool

True when player is part of the starting 11

position Position

See `Position

attributes Optional[Dict]

attributes given by the provider

Source code in kloppy/domain/models/common.py
class Player:
    """
    Attributes:
        player_id: identifier given by the provider
        team: See [`Team`][kloppy.domain.models.common.Team]
        jersey_no: Jersey number
        name: Full name of the player
        first_name: First name
        last_name: Last name
        starting: `True` when player is part of the starting 11
        position: See [`Position][kloppy.domain.models.common.Position]
        attributes: attributes given by the provider
    """

    player_id: str
    team: "Team"
    jersey_no: int
    name: str = None
    first_name: str = None
    last_name: str = None

    # match specific
    starting: bool = None
    position: Position = None

    attributes: Optional[Dict] = field(default_factory=dict, compare=False)

    @property
    def full_name(self):
        if self.name:
            return self.name
        if self.first_name or self.last_name:
            return f"{self.first_name} {self.last_name}"
        return f"{self.team.ground}_{self.jersey_no}"

    def __str__(self):
        return self.full_name

    def __hash__(self):
        return hash(self.player_id)

    def __eq__(self, other):
        if not isinstance(other, Player):
            return False
        return self.player_id == other.player_id

kloppy.domain.models.common.Position dataclass

Position(position_id: str, name: str, coordinates: kloppy.domain.models.pitch.Point)

Source code in kloppy/domain/models/common.py
class Position:
    position_id: str
    name: str
    coordinates: Point

    def __str__(self):
        return self.name

kloppy.domain.models.common.Team dataclass

Attributes:

Name Type Description
team_id str

id of the team, given by the provider

name str

readable name of the team

ground Ground

See Ground

players List[kloppy.domain.models.common.Player]

See Player

starting_formation Optional[kloppy.domain.models.formation.FormationType]

See ['FormationType']

Source code in kloppy/domain/models/common.py
class Team:
    """

    Attributes:
        team_id: id of the team, given by the provider
        name: readable name of the team
        ground: See [`Ground`][kloppy.domain.models.common.Ground]
        players: See [`Player`][kloppy.domain.models.common.Player]
        starting_formation: See ['FormationType']
    """

    team_id: str
    name: str
    ground: Ground
    starting_formation: Optional[FormationType] = None
    players: List[Player] = field(default_factory=list)

    def __str__(self):
        return self.name

    def __hash__(self):
        return hash(self.team_id)

    def __eq__(self, other):
        if not isinstance(other, Team):
            return False
        return self.team_id == other.team_id

    def get_player_by_jersey_number(self, jersey_no: int):
        jersey_no = int(jersey_no)
        for player in self.players:
            if player.jersey_no == jersey_no:
                return player

        return None

    def get_player_by_id(self, player_id: str):
        player_id = str(player_id)

        for player in self.players:
            if player.player_id == player_id:
                return player

        return None

kloppy.domain.models.common.Score dataclass

Score

Attributes:

Name Type Description
home int
away int
Source code in kloppy/domain/models/common.py
class Score:
    """
    Score

    Attributes:
        home:
        away:
    """

    home: int
    away: int

kloppy.domain.models.common.Period dataclass

Period

Attributes:

Name Type Description
id int

1 for first half, 2 for second half

start_timestamp float

timestamp given by provider (can be unix timestamp or relative)

end_timestamp float

timestamp given by provider (can be unix timestamp or relative)

attacking_direction Optional[kloppy.domain.models.common.AttackingDirection]

See AttackingDirection

Source code in kloppy/domain/models/common.py
class Period:
    """
    Period

    Attributes:
        id: `1` for first half, `2` for second half
        start_timestamp: timestamp given by provider (can be unix timestamp or relative)
        end_timestamp: timestamp given by provider (can be unix timestamp or relative)
        attacking_direction: See [`AttackingDirection`][kloppy.domain.models.common.AttackingDirection]
    """

    id: int
    start_timestamp: float
    end_timestamp: float
    attacking_direction: Optional[
        AttackingDirection
    ] = AttackingDirection.NOT_SET

    def contains(self, timestamp: float):
        return self.start_timestamp <= timestamp <= self.end_timestamp

    @property
    def attacking_direction_set(self):
        return self.attacking_direction != AttackingDirection.NOT_SET

    def set_attacking_direction(self, attacking_direction: AttackingDirection):
        self.attacking_direction = attacking_direction

    @property
    def duration(self):
        return self.end_timestamp - self.start_timestamp

    def __eq__(self, other):
        return isinstance(other, Period) and other.id == self.id

Enums

kloppy.domain.models.common.AttackingDirection (Enum)

AttackingDirection

Attributes:

Name Type Description
HOME_AWAY AttackingDirection

Home team is playing from left to right

AWAY_HOME AttackingDirection

Home team is playing from right to left

NOT_SET AttackingDirection

not set yet

Source code in kloppy/domain/models/common.py
class AttackingDirection(Enum):
    """
    AttackingDirection

    Attributes:
        HOME_AWAY (AttackingDirection): Home team is playing from left to right
        AWAY_HOME (AttackingDirection): Home team is playing from right to left
        NOT_SET (AttackingDirection): not set yet
    """

    HOME_AWAY = "home-away"
    AWAY_HOME = "away-home"
    NOT_SET = "not-set"

    def __repr__(self):
        return self.value

kloppy.domain.models.common.BallState (Enum)

BallState

Attributes:

Name Type Description
ALIVE BallState

Ball is in play

DEAD BallState

Ball is not in play

Source code in kloppy/domain/models/common.py
class BallState(Enum):
    """
    BallState

    Attributes:
        ALIVE (BallState): Ball is in play
        DEAD (BallState): Ball is not in play
    """

    ALIVE = "alive"
    DEAD = "dead"

    def __repr__(self):
        return self.value

kloppy.domain.models.common.DatasetType (Enum)

DatasetType

Attributes:

Name Type Description
TRACKING DatasetType
EVENT DatasetType
CODE DatasetType
Source code in kloppy/domain/models/common.py
class DatasetType(Enum):
    """
    DatasetType

    Attributes:
        TRACKING (DatasetType):
        EVENT (DatasetType):
        CODE (DatasetType):
    """

    TRACKING = "TRACKING"
    EVENT = "EVENT"
    CODE = "CODE"

    def __repr__(self):
        return self.value

kloppy.domain.models.common.Ground (Enum)

Attributes:

Name Type Description
HOME

home playing team

AWAY

away playing team

REFEREE

Referee (could be used in tracking data)

Source code in kloppy/domain/models/common.py
class Ground(Enum):
    """
    Attributes:
        HOME: home playing team
        AWAY: away playing team
        REFEREE: Referee (could be used in tracking data)
    """

    HOME = "home"
    AWAY = "away"
    REFEREE = "referee"

    def __str__(self):
        return self.value

    def __repr__(self):
        return self.value

kloppy.domain.models.common.Orientation (Enum)

An enumeration.

Source code in kloppy/domain/models/common.py
class Orientation(Enum):
    # change when possession changes
    BALL_OWNING_TEAM = "ball-owning-team"

    # depends on team which executed the action
    ACTION_EXECUTING_TEAM = "action-executing-team"

    # changes during half-time
    HOME_TEAM = "home-team"
    AWAY_TEAM = "away-team"

    # won't change during match
    FIXED_HOME_AWAY = "fixed-home-away"
    FIXED_AWAY_HOME = "fixed-away-home"

    # Not set in dataset
    NOT_SET = "not-set"

    def get_orientation_factor(
        self,
        attacking_direction: AttackingDirection,
        ball_owning_team: Team,
        action_executing_team: Team,
    ) -> int:
        if self == Orientation.FIXED_HOME_AWAY:
            return -1
        elif self == Orientation.FIXED_AWAY_HOME:
            return 1
        elif self == Orientation.HOME_TEAM:
            if attacking_direction == AttackingDirection.HOME_AWAY:
                return -1
            elif attacking_direction == AttackingDirection.AWAY_HOME:
                return 1
            else:
                raise OrientationError("AttackingDirection not set")
        elif self == Orientation.AWAY_TEAM:
            if attacking_direction == AttackingDirection.AWAY_HOME:
                return -1
            elif attacking_direction == AttackingDirection.HOME_AWAY:
                return 1
            else:
                raise OrientationError("AttackingDirection not set")
        elif self == Orientation.BALL_OWNING_TEAM:
            if ball_owning_team.ground == Ground.HOME:
                return -1
            elif ball_owning_team.ground == Ground.AWAY:
                return 1
            else:
                raise OrientationError(
                    f"Invalid ball_owning_team: {ball_owning_team}"
                )
        elif self == Orientation.ACTION_EXECUTING_TEAM:
            if action_executing_team.ground == Ground.HOME:
                return -1
            elif action_executing_team.ground == Ground.AWAY:
                return 1
            else:
                raise OrientationError(
                    f"Invalid action_executing_team: {action_executing_team}"
                )
        else:
            raise OrientationError(f"Unknown orientation: {self}")

    def __repr__(self):
        return self.value

kloppy.domain.models.common.Provider (Enum)

Attributes:

Name Type Description
METRICA
TRACAB
SECONDSPECTRUM
OPTA
SKILLCORNER
STATSBOMB
SPORTEC
WYSCOUT
KLOPPY
DATAFACTORY
Source code in kloppy/domain/models/common.py
class Provider(Enum):
    """
    Attributes:
        METRICA:
        TRACAB:
        SECONDSPECTRUM:
        OPTA:
        SKILLCORNER:
        STATSBOMB:
        SPORTEC:
        WYSCOUT:
        KLOPPY:
        DATAFACTORY:
    """

    METRICA = "metrica"
    TRACAB = "tracab"
    SECONDSPECTRUM = "second_spectrum"
    OPTA = "opta"
    SKILLCORNER = "skillcorner"
    STATSBOMB = "statsbomb"
    SPORTEC = "sportec"
    WYSCOUT = "wyscout"
    KLOPPY = "kloppy"
    DATAFACTORY = "datafactory"
    OTHER = "other"

    def __str__(self):
        return self.value