Introduce a new event type for ball receipts

[lodevt]

We want to introduce a new event type for ball receipts.

Some providers (such as StatsBomb) already have ball_receipt events in their raw event data. For other providers that don't directly have ball_receipt events, we would have to deduce these events from the event stream.

This information is already present in the current data output, but for analytics purposes it would be cleaner to have this as a separate event. Generating these receival events could be optional during the deserialization, as it probably shouldn't be done by default.

[probberechts]

I would be happy to support this if there is a compelling use case but currently I also see a few reasons why we might not want to add it:

1. The ball receipt is the result of a pass. In general, the kloppy event model does not define event types for results (there is one exception, the BallOutEvent). For example, there are also no events for goals, a ball hitting the post, etc.
2. We've already included most information that is available in StatsBomb's Ball receipt* event in the pass event and the event after the pass. I think the only thing that is missing is the location of the intended receiver for failed passes. Hence, we would only duplicate information that is already parsed.
3. Ball receipts are not a common event type that is implemented by most data providers. Hence, it doesn't really align with the idea that "the event types in kloppy's data model are a common denominator of the event types and attributes that are supported by most data providers".

So, I have a few questions:

1. What is the use case? Do we really need an additional event type to solve it?
2. Which data providers (apart from StatsBomb) have a ball receipt event type and how did they implement it?
3. Can you propose a definition for a BallReceiptEvent and it's attributes?
4. Will you implement this for all event data providers that are currently supported by kloppy?

[lodevt]

Hi,

1. Club analysts/coaches are interested in the number of ball receipts of a player (for example in a specific zone). It is more intuitive to think about this as an event performed by the receiving player, rather than as a pass with the player of interest as the receiving player. It is not strictly necessary to have an additional event type for this, but it would allow these events to be handled in the same way as other events. Otherwise conditions such as the coordinates of the receival and the executor must be transformed when working with receivals (coordinates would become end_coordinates of the pass and executor would become receiving player).

2. It appears that only StatsBomb has a ball receipt event.

Their implementation:
The executor of the ball_receipt event is always the (intended) recipient of the related pass event. If a pass event lacks a recipient, there is no related ball_receipt event.
For passes with incomplete, out or offside as result, the result of the ball_receipt event is "incomplete".

class BallReceiptEvent(Event):
    """
    BallReceiptEvent

    Attributes:
        event_type (EventType): `EventType.BALL_RECEIPT` (See [`EventType`][kloppy.domain.models.event.EventType])
        event_name (str): `"ball_receipt"`
    """

    event_type: EventType = EventType.BALL_RECEIPT
    event_name: str = "ball_receipt"
    result: BallReceiptResult

class BallReceiptResult(ResultType):
    """
    BallReceiptResult

    Attributes:
        COMPLETE (BallReceiptResult): Complete ball receipt
        INCOMPLETE (BallReceiptResult): Incomplete ball receipt (pass was incomplete, out or offside)
    """

    COMPLETE = "COMPLETE"
    INCOMPLETE = "INCOMPLETE"


    @property
    def is_success(self):
        """
        Returns if the ball receipt was complete
        """
        return self == self.COMPLETE

4. As a possible implementation, I was thinking as follows. For StatsBomb, we can parse their ball_receipt events. For other providers we could have logica that analyses the stream of events (after it has been converted to a kloppy EventDataset) and generates the correct ball_receipt events. I think this is quite similar to PR 396 / Issue 379. Since this would happen after the raw event data has been parsed into a standardized dataset, it should work for all event providers (as long as the needed fields are present in the Pass events)

What do you think?

[probberechts]

Ok. I agree with adding support for "deducing" ball receipt events.

I'm still unsure whether we need a "result" for these events. If a pass was out, there was actually no ball receipt. Hence, maybe we should not create a ball receipt event for incomplete receipts? I don't think we should blindly follow StatsBomb. I also don't think we will be able to deduce these incomplete pass receipts for the other providers so this will create inconsistencies.

At least we should define it better what "complete" and "incomplete" means in this context. For example, if a player receives a pass but poorly controls it, is that a completed ball receipt?

[lodevt]

I agree with your reasoning. Maybe it makes more sense to define a completed ball receipt as a ball receipt after which the receiving player performed another on-the-ball action (that is not a miscontrol)?

So when a player gives a failed pass after a receival, it would still be classified as a completed ball receipt.
If a player from the opponent performs an on-the-ball event before the executor of the ball receipt does so, it should be classified as an incomplete receival.

Do you think it is possible to deduce this in a consistent way for all providers? If not, it might be better to not have a "result" property for these events.