| Name | fantacalciosimulator JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A python tool to simulate an entire Fantacalcio season |
| upload_time | 2025-09-08 09:27:59 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Riccardo Samaritan
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
fantacalcio
simulation
football
fantasy football
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
pandas
send2trash
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# About
A comprehensive Python library for simulating Italian fantasy football (Fantacalcio) seasons with probabilistic algorithms, multi-season support, and flexible team management.
> **Purpose**: This library is designed to support data science and machine learning projects in the fantasy football domain. It provides realistic season simulations and statistical analysis tools for research, not to replace the original game experience.
# Features
- **Multi-Season Support**: Simulate different seasons (2024-25, 2023-24, 2022-23, 2021-22) with automatic data directory management
- **Multiple Input Formats**: Load teams from JSON, CSV files, or pandas DataFrames
- **Probabilistic Simulation**: Probabilistic algorithms eliminate luck factor for realistic season outcomes
- **Flexible Configuration**: Support for various team compositions and formation rules.
The app takes as input a given number of teams (usually a multiple of 2 in a range between 8 and 12) with 25 players (3 goalkeepers, 8 defenders, 8 midfielders and 6 forwards), which is the most common format used in the game.
# Game Rules
## Formation
To simplify the implementation, the following rules have been applied to fantasy football by default:
- The only allowed formation is 4-3-3, which means 1 goalkeeper, 4 defenders, 3 midfielders and 3 forwards. If there are not enough players in a role with a valid vote, a player with a null vote will be fielded anyway.
- The user doesn't field players; instead, they are automatically selected based on the highest "fantavoto", while respecting positional requirements.
## Bonus and Malus
The following bonus and malus are applied to a player's vote in order to calculate his "fantavoto":
- +3 for each goal or penalty scored;
- +1 for each assist;
- -1 for each goal taken (applied only to goalkeepers);
- -3 for each missed penalty;
- +3 for each saved penalty (applied only to goalkeepers);
- -0,5 if he gets a yellow card;
- -1 if he gets a red card;
- -2 for each autogoal;
- +1 if he keeps a clean sheet (applied only to goalkeepers).
## Defense Modifier
The defense modifier is used, which awards bonus points to the team based on the average rating of the 4 defenders:
- If the average rating is < 6, bonus +1
- If the average rating is ≥ 6 and < 6.25, bonus +2
- If the average rating is ≥ 6.25 and < 6.5, bonus +3
- If the average rating is ≥ 6.5 and < 6.75, bonus +4
- If the average rating is ≥ 6.75 and < 7, bonus +5
- If the average rating is ≥ 7 and < 7.25, bonus +6
- If the average rating is ≥ 7.25, bonus +7
The modifier is applied only if 4 defenders are fielded.
# Installation
Before installing the package, make sure you have **`Python 3.8` or higher** installed on your system.
In case you want to avoid any conflicts with your system's Python packages, you might want to create (and activate) a dedicated virtual environment:
```bash
python -m venv /path/to/fantacalciosimulator_env
source /path/to/fantacalciosimulator_env/bin/activate
```
## Install via PIP
You can install the package from the `Python Package Index (PyPI)` using pip:
```bash
pip install fantacalciosimulator
```
## Installing from source
1. Clone the repository:
```bash
git clone https://github.com/RiccardoSamaritan/FantacalcioSimulator
```
2. Move into the repository directory and install the package with:
```bash
cd FantacalcioSimulator/
pip install .
```
# Quick Start
## Basic Usage
```python
from fantacalciosimulator import FantacalcioSimulator
# Initialize simulator with season and teams file
simulator = FantacalcioSimulator(
season_year="2024-25",
teams_file="teams_input_example.csv"
)
# Simulate complete season
results = simulator.simulate_season("My Fantasy League 2024-25")
# Display final table
print(simulator.get_final_table())
```
## Using Different Input Formats
### CSV Format
```python
# CSV with format: team_name,player_name,role
simulator = FantacalcioSimulator("2024-25", "teams.csv")
```
### JSON Format
```python
# JSON with nested team structure
simulator = FantacalcioSimulator("2024-25", "teams.json")
```
### Pandas DataFrame
```python
import pandas as pd
from fantacalciosimulator import FantacalcioSimulator
df = pd.read_csv("teams.csv")
simulator = FantacalcioSimulator.from_dataframe("2024-25", df)
```
## Configuration Options
```python
# Disable defense modifier
simulator = FantacalcioSimulator(
season_year="2024-25",
teams_file="teams.csv",
defense_modifier=False
)
# Custom data directory
simulator = FantacalcioSimulator(
season_year="2024-25",
teams_file="teams.csv",
data_dir="custom_data_path"
)
```
## Advanced Usage Examples
### Complete Analysis Workflow
```python
from fantacalciosimulator import FantacalcioSimulator
# Initialize and simulate
simulator = FantacalcioSimulator("2024-25", "teams.csv")
results = simulator.simulate_season("My League")
# Get detailed team information
teams_info = simulator.get_teams_info()
for team in teams_info:
print(f"{team['name']}: {team['total_players']} players, Valid: {team['valid_composition']}")
# Analyze specific team progression
team_progression = simulator.get_team_progression("Team Alpha")
print(f"Final points: {team_progression['final_total']}")
# Display championship results
print(f"Champion: {results['champion']} with {results['champion_points']} points")
print(f"Highest fantasy score: {results['highest_fantasy_score']} by {results['highest_fantasy_team']}")
```
### Quick Simulation Function
```python
from fantacalciosimulator import quick_simulation
# One-line season simulation
results = quick_simulation(
season_year="2024-25",
teams_file="teams.csv",
season_name="Championship 2025"
)
```
### Team Validation
```python
from fantacalciosimulator import load_and_validate_teams
# Validate teams before simulation
teams_info = load_and_validate_teams("2024-25", "teams.csv")
valid_teams = [t for t in teams_info if t['valid_composition']]
print(f"{len(valid_teams)} valid teams out of {len(teams_info)}")
```
# Data Sources
**`FantacalcioSimulator`** matchday statistics are taken from [Fantacalcio.it](https://www.fantacalcio.it/voti-fantacalcio-serie-a), one of the most popular Italian fantasy football platforms.
Other useful resources from the same site are:
- [Player fantasy market value](https://www.fantacalcio.it/quotazioni-fantacalcio)
- [Player statistics](https://www.fantacalcio.it/statistiche-serie-a)
- [Goalkeeper grid](https://www.fantacalcio.it/griglia-portieri)
- [Penalty takers](https://www.fantacalcio.it/rigoristi-serie-a)
Raw data
{
"_id": null,
"home_page": null,
"name": "fantacalciosimulator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "fantacalcio, simulation, football, fantasy football",
"author": null,
"author_email": "Riccardo Samaritan <riccardo.samaritan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7a/5a/48bafe32d8be520fc225c29355561f4d9a733e652ad85b571a7dbe280123/fantacalciosimulator-0.1.1.tar.gz",
"platform": null,
"description": "# About\n\nA comprehensive Python library for simulating Italian fantasy football (Fantacalcio) seasons with probabilistic algorithms, multi-season support, and flexible team management.\n\n> **Purpose**: This library is designed to support data science and machine learning projects in the fantasy football domain. It provides realistic season simulations and statistical analysis tools for research, not to replace the original game experience.\n\n# Features\n\n- **Multi-Season Support**: Simulate different seasons (2024-25, 2023-24, 2022-23, 2021-22) with automatic data directory management\n- **Multiple Input Formats**: Load teams from JSON, CSV files, or pandas DataFrames\n- **Probabilistic Simulation**: Probabilistic algorithms eliminate luck factor for realistic season outcomes\n- **Flexible Configuration**: Support for various team compositions and formation rules.\n\nThe app takes as input a given number of teams (usually a multiple of 2 in a range between 8 and 12) with 25 players (3 goalkeepers, 8 defenders, 8 midfielders and 6 forwards), which is the most common format used in the game. \n\n# Game Rules\n\n## Formation\n\nTo simplify the implementation, the following rules have been applied to fantasy football by default:\n - The only allowed formation is 4-3-3, which means 1 goalkeeper, 4 defenders, 3 midfielders and 3 forwards. If there are not enough players in a role with a valid vote, a player with a null vote will be fielded anyway.\n \n - The user doesn't field players; instead, they are automatically selected based on the highest \"fantavoto\", while respecting positional requirements.\n\n## Bonus and Malus\n The following bonus and malus are applied to a player's vote in order to calculate his \"fantavoto\":\n - +3 for each goal or penalty scored;\n - +1 for each assist;\n - -1 for each goal taken (applied only to goalkeepers);\n - -3 for each missed penalty;\n - +3 for each saved penalty (applied only to goalkeepers);\n - -0,5 if he gets a yellow card;\n - -1 if he gets a red card;\n - -2 for each autogoal;\n - +1 if he keeps a clean sheet (applied only to goalkeepers).\n\n## Defense Modifier\n The defense modifier is used, which awards bonus points to the team based on the average rating of the 4 defenders:\n - If the average rating is < 6, bonus +1\n - If the average rating is \u2265 6 and < 6.25, bonus +2\n - If the average rating is \u2265 6.25 and < 6.5, bonus +3\n - If the average rating is \u2265 6.5 and < 6.75, bonus +4\n - If the average rating is \u2265 6.75 and < 7, bonus +5\n - If the average rating is \u2265 7 and < 7.25, bonus +6\n - If the average rating is \u2265 7.25, bonus +7\n The modifier is applied only if 4 defenders are fielded.\n\n# Installation\n\nBefore installing the package, make sure you have **`Python 3.8` or higher** installed on your system.\nIn case you want to avoid any conflicts with your system's Python packages, you might want to create (and activate) a dedicated virtual environment:\n\n```bash\npython -m venv /path/to/fantacalciosimulator_env\nsource /path/to/fantacalciosimulator_env/bin/activate\n```\n\n## Install via PIP\n\nYou can install the package from the `Python Package Index (PyPI)` using pip:\n\n```bash\npip install fantacalciosimulator\n```\n## Installing from source\n\n1. Clone the repository:\n \n ```bash\n git clone https://github.com/RiccardoSamaritan/FantacalcioSimulator\n ```\n\n2. Move into the repository directory and install the package with:\n \n ```bash\n cd FantacalcioSimulator/\n pip install .\n ```\n\n# Quick Start\n\n## Basic Usage\n\n```python\nfrom fantacalciosimulator import FantacalcioSimulator\n\n# Initialize simulator with season and teams file\nsimulator = FantacalcioSimulator(\n season_year=\"2024-25\",\n teams_file=\"teams_input_example.csv\"\n)\n\n# Simulate complete season\nresults = simulator.simulate_season(\"My Fantasy League 2024-25\")\n\n# Display final table\nprint(simulator.get_final_table())\n```\n\n## Using Different Input Formats\n\n### CSV Format\n```python\n# CSV with format: team_name,player_name,role\nsimulator = FantacalcioSimulator(\"2024-25\", \"teams.csv\")\n```\n\n### JSON Format\n```python\n# JSON with nested team structure\nsimulator = FantacalcioSimulator(\"2024-25\", \"teams.json\")\n```\n\n### Pandas DataFrame\n```python\nimport pandas as pd\nfrom fantacalciosimulator import FantacalcioSimulator\n\ndf = pd.read_csv(\"teams.csv\")\nsimulator = FantacalcioSimulator.from_dataframe(\"2024-25\", df)\n```\n\n## Configuration Options\n\n```python\n# Disable defense modifier\nsimulator = FantacalcioSimulator(\n season_year=\"2024-25\",\n teams_file=\"teams.csv\",\n defense_modifier=False\n)\n\n# Custom data directory\nsimulator = FantacalcioSimulator(\n season_year=\"2024-25\", \n teams_file=\"teams.csv\",\n data_dir=\"custom_data_path\"\n)\n```\n\n## Advanced Usage Examples\n\n### Complete Analysis Workflow\n```python\nfrom fantacalciosimulator import FantacalcioSimulator\n\n# Initialize and simulate\nsimulator = FantacalcioSimulator(\"2024-25\", \"teams.csv\")\nresults = simulator.simulate_season(\"My League\")\n\n# Get detailed team information\nteams_info = simulator.get_teams_info()\nfor team in teams_info:\n print(f\"{team['name']}: {team['total_players']} players, Valid: {team['valid_composition']}\")\n\n# Analyze specific team progression\nteam_progression = simulator.get_team_progression(\"Team Alpha\")\nprint(f\"Final points: {team_progression['final_total']}\")\n\n# Display championship results\nprint(f\"Champion: {results['champion']} with {results['champion_points']} points\")\nprint(f\"Highest fantasy score: {results['highest_fantasy_score']} by {results['highest_fantasy_team']}\")\n```\n\n### Quick Simulation Function\n```python\nfrom fantacalciosimulator import quick_simulation\n\n# One-line season simulation\nresults = quick_simulation(\n season_year=\"2024-25\",\n teams_file=\"teams.csv\",\n season_name=\"Championship 2025\"\n)\n```\n\n### Team Validation\n```python\nfrom fantacalciosimulator import load_and_validate_teams\n\n# Validate teams before simulation\nteams_info = load_and_validate_teams(\"2024-25\", \"teams.csv\")\nvalid_teams = [t for t in teams_info if t['valid_composition']]\nprint(f\"{len(valid_teams)} valid teams out of {len(teams_info)}\")\n```\n\n# Data Sources\n \n**`FantacalcioSimulator`** matchday statistics are taken from [Fantacalcio.it](https://www.fantacalcio.it/voti-fantacalcio-serie-a), one of the most popular Italian fantasy football platforms.\n\nOther useful resources from the same site are:\n- [Player fantasy market value](https://www.fantacalcio.it/quotazioni-fantacalcio)\n- [Player statistics](https://www.fantacalcio.it/statistiche-serie-a)\n- [Goalkeeper grid](https://www.fantacalcio.it/griglia-portieri)\n- [Penalty takers](https://www.fantacalcio.it/rigoristi-serie-a)\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Riccardo Samaritan\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A python tool to simulate an entire Fantacalcio season",
"version": "0.1.1",
"project_urls": {
"Repository": "https://github.com/RiccardoSamaritan/FantacalcioSimulator"
},
"split_keywords": [
"fantacalcio",
" simulation",
" football",
" fantasy football"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "65f985b918b63754fc76a8a7a4af175271dfbbcecd70dabc57987a90904b9293",
"md5": "8ba735e5d495c7148f2e30798d0ef066",
"sha256": "23de0b9e550f3eaf0c1b8fb9c3af8705613e53601405f4a6db9b54c687c7c77a"
},
"downloads": -1,
"filename": "fantacalciosimulator-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ba735e5d495c7148f2e30798d0ef066",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19166,
"upload_time": "2025-09-08T09:27:57",
"upload_time_iso_8601": "2025-09-08T09:27:57.819463Z",
"url": "https://files.pythonhosted.org/packages/65/f9/85b918b63754fc76a8a7a4af175271dfbbcecd70dabc57987a90904b9293/fantacalciosimulator-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7a5a48bafe32d8be520fc225c29355561f4d9a733e652ad85b571a7dbe280123",
"md5": "f8797a27bcb8c4aba14f52401ada39ab",
"sha256": "ad31ea643bd84fc201f47a07e49ecacfcf37fd29a7267729ce78acfe7954c861"
},
"downloads": -1,
"filename": "fantacalciosimulator-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f8797a27bcb8c4aba14f52401ada39ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18803,
"upload_time": "2025-09-08T09:27:59",
"upload_time_iso_8601": "2025-09-08T09:27:59.138190Z",
"url": "https://files.pythonhosted.org/packages/7a/5a/48bafe32d8be520fc225c29355561f4d9a733e652ad85b571a7dbe280123/fantacalciosimulator-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 09:27:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RiccardoSamaritan",
"github_project": "FantacalcioSimulator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pandas",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "send2trash",
"specs": [
[
">=",
"1.8.0"
]
]
}
],
"lcname": "fantacalciosimulator"
}
