How pysport/kloppy works
Project Type & Purpose
• This is an open‐source library (toolkit) for processing soccer data.
• Its key functions include loading data from multiple providers (e.g., OPTA, StatsBomb, Wyscout, etc.), converting them into a standardized internal format, and providing data transformation and pattern matching functionality.
• The README emphasizes standard models, (de)serialization, data processing (pitch transformation, orientation shifting), and pattern matching in event data.
Analyzing the File Structure
• The main code lives under the “kloppy” directory.
• There is a clear modular separation:
– The “_providers” subdirectory holds provider-specific loading logic.
– The “domain” directory contains the standardized data models and domain services (aggregators, event factories, state builders, etc.).
– The “infra” layer represents input/output (IO) adapters and serializers. Under “infra/io/adapters,” there are adapters for file, HTTP, S3, and ZIP, indicating support for different data sources.
– The “infra/serializers” directories are divided into submodules such as “code” and “event” (with further segregation by vendor) along with “tracking” serializers.
• There are testing and examples directories that exemplify usage, as well as documentation files that provide additional context.
High-Level System Components
a. Data Input Sources:
– External data sources (files, HTTP endpoints, S3 buckets) that supply raw soccer tracking/event data.
b. IO/Adapter Layer:
– IO adapters under “kloppy/infra/io/adapters” handle data ingestion. Represent these as modules dedicated to file, HTTP, S3, and ZIP access.
c. Deserialization and Serialization Layer:
– Under “kloppy/infra/serializers” are vendor-specific deserializers for event data (for example in folders like “metrica,” “opta,” “statsbomb,” “wyscout,” etc.) and equivalent logic for tracking data.
d. Provider Abstraction:
– In “kloppy/_providers,” each provider (datafactory, hawkeye, metrica, etc.) encapsulates logic to interface with specific vendor formats.
e. Domain Model & Service Layer:
– Domain models (within “kloppy/domain/models”) standardize entities like Event, Formation, Position, etc.
– Domain services (found in “kloppy/domain/services”) include factories, aggregators, pattern matching services (for instance, the “pattern matching” and “state builder” components).
f. Processing and Transformation Components:
– Services that transform datasets (changing pitch dimensions, orientation, etc.) and execute pattern matching to extract meaningful fragments.
g. CLI Tooling & Utilities:
– The “kloppy/cmdline.py”, “helpers.py”, and similar utilities support running commands directly from the command line.
Relationships & Data Flow
• Data flows from external sources into the IO adapter layer.
• The adapters pass raw data to the appropriate serializer/deserializer based on the vendor/data format.
• The deserialized data is then converted into the standardized domain models.
• Domain services further process this data (aggregators, state builders, event factories, etc.) and make it available for downstream applications or integrations.
• Optionally, utilities and CLI commands provide interfaces to invoke this pipeline.
Architectural Patterns & Design Principles
• Modularity: Each vendor or functionality is isolated in its submodule (e.g., different serializers and domain services).
• Abstraction: The provider layer abstracts vendor specifics, while the domain layer offers a standardized representation of soccer data.
• Separation of Concerns: IO handling, data transformation, and domain logic are distinct.
• Extensibility: It is straightforward to add new providers or processing logics given the clear separation between the adapters, serializers, and domain services.
Relevant Technologies and Libraries
• Python is the core language.
• Although not explicitly a web application, it relies on standard Python packaging and build tools (setup.py, pyproject.toml) along with CI/CD (GitHub workflows under .github/workflows).
• The project also includes notebooks and examples (Jupyter notebooks in docs/examples and docs/getting-started) to illustrate usage.