[SPORTEC] Load DFL Open Data

[UnravelSports]

The Floodlight Package has a way to load 7 games of DFL event and tracking data.

{
        'J03WMX': 1. FC Köln vs. FC Bayern München,
        'J03WN1': VfL Bochum 1848 vs. Bayer 04 Leverkusen,
        'J03WPY': Fortuna Düsseldorf vs. 1. FC Nürnberg,
        'J03WOH': Fortuna Düsseldorf vs. SSV Jahn Regensburg,
        'J03WQQ': Fortuna Düsseldorf vs. FC St. Pauli,
        'J03WOY': Fortuna Düsseldorf vs. F.C. Hansa Rostock,
        'J03WR9': Fortuna Düsseldorf vs. 1. FC Kaiserslautern
        }

I have created an implementation to load this same data directly into Kloppy. We simply add:

def load_open_event_data(
    match_id: str = "J03WPY",
    event_types: Optional[List[str]] = None,
    coordinates: Optional[str] = None,
    event_factory: Optional[EventFactory] = None,
) -> EventDataset:

    if not META_DATA_MAP.get(match_id):
        raise ValueError(
            f"This match_id is not available, please select from {list(META_DATA_MAP.keys())}"
        )

    return load_event(
        event_data=DATA_URL.format(file_id=EVENT_DATA_MAP[match_id]),
        meta_data=DATA_URL.format(file_id=META_DATA_MAP[match_id]),
        event_types=event_types,
        coordinates=coordinates,
        event_factory=event_factory,
    )


def load_open_tracking_data(
    match_id: str = "J03WPY",
    sample_rate: Optional[float] = None,
    limit: Optional[int] = None,
    coordinates: Optional[str] = None,
    only_alive: Optional[bool] = True,
) -> EventDataset:

    if not META_DATA_MAP.get(match_id):
        raise ValueError(
            f"This match_id is not available, please select from {list(META_DATA_MAP.keys())}"
        )

    return load_tracking(
        raw_data=DATA_URL.format(file_id=TRACKING_DATA_MAP[match_id]),
        meta_data=DATA_URL.format(file_id=META_DATA_MAP[match_id]),
        sample_rate=sample_rate,
        limit=limit,
        coordinates=coordinates,
        only_alive=only_alive,
    )

I've added the following in the same file, but I'm not sure how desirable this is and if it needs to be put in another file.

META_DATA_MAP = {
    "J03WPY": "48392497",
    "J03WN1": "48392491",
    "J03WMX": "48392485",
    "J03WOH": "48392515",
    "J03WQQ": "48392488",
    "J03WOY": "48392503",
    "J03WR9": "48392494",
}
EVENT_DATA_MAP = {
    "J03WPY": "48392542",
    "J03WN1": "48392527",
    "J03WMX": "48392524",
    "J03WOH": "48392500",
    "J03WQQ": "48392521",
    "J03WOY": "48392518",
    "J03WR9": "48392530",
}
TRACKING_DATA_MAP = {
    "J03WPY": "48392572",
    "J03WN1": "48392512",
    "J03WMX": "48392539",
    "J03WOH": "48392578",
    "J03WQQ": "48392545",
    "J03WOY": "48392551",
    "J03WR9": "48392563",
}

DATA_URL = "https://figshare.com/ndownloader/files/{file_id}?private_link=1f806cb3e755c6b54e05"

Finally, when loading match_id="J03WN1" or match_id="J03WN1" tracking data I get an error, but match_id="J03WPY" works fine. So, this would be an issue that we'd have to resolve, although it seems unrelated to this specific implementation.

[probberechts]

Cool! I didn't know about this great dataset. However, I wonder if it is supposed to be made public. The URL is a private Figshare link. Typically, its purpose is to share private data with reviewers. Moreover, the paper that is now published includes the following statement:

Due to licensing issues, the position and event data of the examined soccer matches cannot be made available.

I assume there is also no license for the data?

[ussf-jbekkers]

Good point, thanks for checking that. I assumed it would be freely available simply because:

• It's in an open-source package.
• I was told by people who should know that this data was made available. But maybe they ran into issues afterwards?

[manuba95]

Hey guys, I'm responsible for including the dataset into floodlight and may answer some of your questions.

Our department got permission by the DFL to publish these seven matches under CC-BY-4.0 as an educational resource and benchmark dataset. We currently have an accompanying paper in review in Nature Scientific Data, as described in floodlights documentation of the dataset. During the revision process in SData the datasets are hosted on a private figshare repository as @probberechts pointed out. However, the paper by Henrik Biermann and colleagues is not related. It uses different data that we are not allowed do share.

Since we made the private link to the repository open source, you can feel free (and I appreciate it!!) to add it to kloppy. DataBallPy already included it in their latest release. However, please be aware of the following: First, once the dataset is published, the figshare repository will change to public and the hard-coded links will most likely change. Second, please cite the accompanying paper in the documentation.

So if you want to include the dataset in its current stage, you can do this but you will have to fix the links and references upon final publication.

Cheers!

[UnravelSports]

Hi @manuba95 thanks very much for the thorough reply!

Is there any objection to rehosting the data on github to avoid broken links in the future? Or @probberechts should we either wait for the public url, or perhaps shall I simply put a deprecation warning in place? That if the url appears broken users should update their kloppy version?

CIting the paper should not be an issue, we're still working on extending the docs but we'll include it!

[probberechts]

@manuba95 Great! Thanks for the clarification and good luck with the review process.

Is there also a license in the Figshare repo (or somewhere else) for which you could provide the link?

Is there any objection to rehosting the data on github to avoid broken links in the future?

The main reason for using a scientific data repository is exactly to avoid broken links in the future. 😃 For example for Zenode, once you upload something, there's almost no possibility to remove it and it will associate a DOI with your deposited artifacts, which will permanently link to the corresponding version. I am not very familiar with Figshare, but I assume it is similar. On the other hand, you can remove/rename/edit a GitHub repo.

That being said, I don't think it is a bad idea to mirror the dataset on GitHub. It makes it easier to discover and explore the data.

Or @probberechts should we either wait for the public url, or perhaps shall I simply put a deprecation warning in place?

If @manuba95 is ok with it, I would make it available now. I would not use a deprecation warning, but a regular warning seems a good idea.

CIting the paper should not be an issue, we're still working on extending the docs but we'll include it!

I think adding the citation to the docstring would be sufficient for now. Once we update the docs, we can include something like "if you use this dataset, please cite ..."

[UnravelSports]

Thanks @probberechts I'll include a regular warning.

@manuba95 is there anything to cite yet, or is this only relevant after publication of your Nature paper?

[manuba95]

Since it is published under CC-BY-4.0 you can share and distribute anywhere you like, from a lincensing perspective. But imo (and as @probberechts pointed out) GitHub is not a data repository, figshare is. Once published (hopefully within the next weeks fingers crossed) the links will be permanent and accessible. You can decide whether your users need another way to access the raw data.

The repository does not have a license for the data. We have a letter of permission by the DFL that we also shared with the editorial office of SData.

@UnravelSports we currently cite the paper as follows: Bassek, M., Weber, H., Rein, R., & Memmert,D. (2024). An integrated dataset of synchronized spatiotemporal and event data in elite soccer. In Submission.

Which is sufficient until publication. After that I can update you with the final reference!

[UnravelSports]

Thanks @manuba95, I will include it. I understand GitHub is not file storage, but it seemed like a decent solution since other files supported by Kloppy are also hosted there (StatsBomb for example). Just wanted to make sure the data persists, and I'm not familiar with figshare.

Either way, please update us with any information (new source, final reference) after publication when you find some time!

[probberechts]

Make sure to add a license to the repository once it gets published! Without a license, data is not truly open. This would be a great dataset for benchmarking but without an explicit license together with the data, we would not be allowed to use it in our research.

[UnravelSports]

@koenvo I have added a reference to (#369) in the error message as requested

[probberechts]

I did some refactoring and added documentation. Do you agree with my changes @UnravelSports?

[UnravelSports]

Awesome @probberechts thanks for that, it looks a lot cleaner!