pyretailscience 0.3.2__tar.gz → 0.4.0__tar.gz

pyretailscience-0.4.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.3
+Name: pyretailscience
+Version: 0.4.0
+Summary: Retail Data Science Tools
+License: Elastic-2.0
+Author: Murray Vanwyk
+Author-email: 2493311+mvanwyk@users.noreply.github.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: duckdb (>=1.0.0,<2.0.0)
+Requires-Dist: graphviz (>=0.20.3,<0.21.0)
+Requires-Dist: ibis-framework[duckdb] (>=9.5.0,<10.0.0)
+Requires-Dist: loguru (>=0.7.2,<0.8.0)
+Requires-Dist: matplotlib (>=3.9.1,<4.0.0)
+Requires-Dist: matplotlib-set-diagrams (>=0.0.2,<0.1.0)
+Requires-Dist: numpy (>=1.26.3,<2.0.0)
+Requires-Dist: pandas (>=2.1.4,<3.0.0)
+Requires-Dist: pyarrow (>=14.0.2,<15.0.0)
+Requires-Dist: scikit-learn (>=1.4.2,<2.0.0)
+Requires-Dist: scipy (>=1.13.0,<2.0.0)
+Requires-Dist: toml (>=0.10.2,<0.11.0)
+Requires-Dist: tqdm (>=4.66.1,<5.0.0)
+Description-Content-Type: text/markdown
+
+![PyRetailScience Logo](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/logo.png)
+
+# PyRetailScience
+
+⚡ Rapid bespoke and deep dive retail analytics ⚡
+
+PyRetailScience equips you with a wide array of retail analytical capabilities, from segmentations to gain-loss analysis. Leave the mundane to us and elevate your role from data janitor to insights virtuoso.
+
+## Installation
+
+To get the latest release:
+
+```bash
+pip install pyretailscience
+```
+
+Alternatively, if you want the very latest version of the package you can install it from GitHub:
+
+```bash
+pip install git+https://github.com/Data-Simply/pyretailscience.git
+```
+
+## Features
+
+- **Tailored for Retail**: Leverage pre-built functions designed specifically for retail analytics. From customer segmentations to gains loss analysis, PyRetailScience provides over a dozen building blocks you need to tackle retail-specific challenges efficiently and effectively.
+
+![New Store Cannibalization Analysis](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/new_store_cannibalization.png)
+
+- **Reliable Results**: Built with extensive unit testing and best practices, PyRetailScience ensures the accuracy and reliability of your analyses. Confidently present your findings, knowing they're backed by a robust, well-tested framework.
+
+- **Professional Charts**: Say goodbye to hours of tweaking chart styles. PyRetailScience delivers beautifully standardized visualizations that are presentation-ready with just a few lines of code. Impress stakeholders and save time with our pre-built, customizable chart templates.
+
+![Cross Shop Analysis Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/cross_shop_chart.png)
+
+- **Workflow Automation**: PyRetailScience streamlines your workflow by automating common retail analytics tasks. Easily loop analyses over different dimensions like product categories or countries, and seamlessly use the output of one analysis as input for another. Spend less time on data manipulation and more on generating valuable insights.
+
+## Examples
+
+### Gains Loss Analysis
+
+Here is an excerpt from the gain loss analysis example [notebook](https://pyretailscience.datasimply.co/examples/gain_loss/)
+
+```python
+from pyretailscience.gain_loss import GainLoss
+
+gl = GainLoss(
+    df,
+    # Flag the rows of period 1
+    p1_index=time_period_1,
+    # Flag the rows of period 2
+    p2_index=time_period_2,
+    # Flag which rows are part of the focus group.
+    # Namely, which rows are Calvin Klein sales
+    focus_group_index=df["brand_name"] == "Calvin Klein",
+    focus_group_name="Calvin Klein",
+    # Flag which rows are part of the comparison group.
+    # Namely, which rows are Diesel sales
+    comparison_group_index=df["brand_name"] == "Diesel",
+    comparison_group_name="Diesel",
+    # Finally we specifiy that we want to calculate
+    # the gain/loss in total revenue
+    value_col="total_price",
+)
+# Ok now let's plot the result
+gl.plot(
+    x_label="Revenue Change",
+    source_text="Transactions 2023-01-01 to 2023-12-31",
+    move_legend_outside=True,
+)
+plt.show()
+```
+
+![Cross Shop Analysis Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/gain_loss_chart.png)
+
+### Cross Shop Analysis
+
+Here is an excerpt from the cross shop analysis example [notebook](https://pyretailscience.datasimply.co/examples/cross_shop/)
+
+```python
+from pyretailscience import cross_shop
+
+cs = cross_shop.CrossShop(
+    df,
+    group_1_idx=df["category_1_name"] == "Jeans",
+    group_2_idx=df["category_1_name"] == "Shoes",
+    group_3_idx=df["category_1_name"] == "Dresses",
+    labels=["Jeans", "Shoes", "Dresses"],
+)
+cs.plot(
+    title="Jeans are a popular cross-shopping category with dresses",
+    source_text="Source: Transactions 2023-01-01 to 2023-12-31",
+    figsize=(6, 6),
+)
+plt.show()
+# Let's see which customers were in which groups
+display(cs.cross_shop_df.head())
+# And the totals for all groups
+display(cs.cross_shop_table_df)
+```
+
+![Cross Shop Analysis Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/cross_shop_chart.png)
+
+### Customer Retention Analysis
+
+Here is an excerpt from the customer retention analysis example [notebook](https://pyretailscience.datasimply.co/examples/retention/)
+
+```python
+ax = dbp.plot(
+    figsize=(10, 5),
+    bins=20,
+    cumlative=True,
+    draw_percentile_line=True,
+    percentile_line=0.8,
+    source_text="Source: Transactions in 2023",
+    title="When Do Customers Make Their Next Purchase?",
+)
+
+# Let's dress up the chart a bit of text and get rid of the legend
+churn_period = dbp.purchases_percentile(0.8)
+ax.annotate(
+    f"80% of customers made\nanother purchase within\n{round(churn_period)} days",
+    xy=(churn_period, 0.81),
+    xytext=(dbp.purchase_dist_s.min(), 0.8),
+    fontsize=15,
+    ha="left",
+    va="center",
+    arrowprops=dict(facecolor="black", arrowstyle="-|>", connectionstyle="arc3,rad=-0.25", mutation_scale=25),
+)
+ax.legend().set_visible(False)
+plt.show()
+```
+
+![Cumulative Next Purchase Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/days_until_next_purchase.png)
+
+## Documentation
+
+Please see [here](https://pyretailscience.datasimply.co/) for full documentation, which includes:
+
+- [Analysis Modules](https://pyretailscience.datasimply.co/analysis_modules/): Overview of the framework and the structure of the docs.
+- [Examples](https://pyretailscience.datasimply.co/examples/retention/): If you're looking to build something specific or are more of a hands-on learner, check out our examples. This is the best place to get started.
+- [API Reference](https://pyretailscience.datasimply.co/api/gain_loss/): Thorough documentation of every class and method.
+
+## Contributing
+
+We welcome contributions from the community to enhance and improve PyRetailScience. To contribute, please follow these steps:
+
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix.
+3. Make your changes and commit them with clear messages.
+4. Push your changes to your fork.
+5. Open a pull request to the main repository's `main` branch.
+
+Please make sure to follow the existing coding style and provide unit tests for new features.
+
+## Contact / Support
+
+This repository is supported by Data simply.
+
+If you are interested in seeing what Data Simply can do for you, then please email [email us](mailto:murray@datasimply.co).
+We work with companies at a variety of scales and with varying levels of data and retail analytics sophistication, to
+help them build, scale or streamline their analysis capabilities.
+
+## Contributors
+
+<a href="https://github.com/Data-Simply/pyretailscience/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Data-Simply/pyretailscience" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
+## Acknowledgements
+
+Built with expertise doing analytics and data science for scale-ups to multi-nationals, including:
+
+- Loblaws
+- Dominos
+- Sainbury's
+- IKI
+- Migros
+- Sephora
+- Nectar
+- Metro
+- Coles
+- GANNI
+- Mindful Chef
+- Auchan
+- Attraction Tickets Direct
+- Roman Originals
+
+## License
+
+This project is licensed under the Elastic License 2.0 - see the [LICENSE](LICENSE) file for details.
+

pyretailscience-0.4.0/README.md

@@ -0,0 +1,192 @@
+![PyRetailScience Logo](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/logo.png)
+
+# PyRetailScience
+
+⚡ Rapid bespoke and deep dive retail analytics ⚡
+
+PyRetailScience equips you with a wide array of retail analytical capabilities, from segmentations to gain-loss analysis. Leave the mundane to us and elevate your role from data janitor to insights virtuoso.
+
+## Installation
+
+To get the latest release:
+
+```bash
+pip install pyretailscience
+```
+
+Alternatively, if you want the very latest version of the package you can install it from GitHub:
+
+```bash
+pip install git+https://github.com/Data-Simply/pyretailscience.git
+```
+
+## Features
+
+- **Tailored for Retail**: Leverage pre-built functions designed specifically for retail analytics. From customer segmentations to gains loss analysis, PyRetailScience provides over a dozen building blocks you need to tackle retail-specific challenges efficiently and effectively.
+
+![New Store Cannibalization Analysis](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/new_store_cannibalization.png)
+
+- **Reliable Results**: Built with extensive unit testing and best practices, PyRetailScience ensures the accuracy and reliability of your analyses. Confidently present your findings, knowing they're backed by a robust, well-tested framework.
+
+- **Professional Charts**: Say goodbye to hours of tweaking chart styles. PyRetailScience delivers beautifully standardized visualizations that are presentation-ready with just a few lines of code. Impress stakeholders and save time with our pre-built, customizable chart templates.
+
+![Cross Shop Analysis Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/cross_shop_chart.png)
+
+- **Workflow Automation**: PyRetailScience streamlines your workflow by automating common retail analytics tasks. Easily loop analyses over different dimensions like product categories or countries, and seamlessly use the output of one analysis as input for another. Spend less time on data manipulation and more on generating valuable insights.
+
+## Examples
+
+### Gains Loss Analysis
+
+Here is an excerpt from the gain loss analysis example [notebook](https://pyretailscience.datasimply.co/examples/gain_loss/)
+
+```python
+from pyretailscience.gain_loss import GainLoss
+
+gl = GainLoss(
+    df,
+    # Flag the rows of period 1
+    p1_index=time_period_1,
+    # Flag the rows of period 2
+    p2_index=time_period_2,
+    # Flag which rows are part of the focus group.
+    # Namely, which rows are Calvin Klein sales
+    focus_group_index=df["brand_name"] == "Calvin Klein",
+    focus_group_name="Calvin Klein",
+    # Flag which rows are part of the comparison group.
+    # Namely, which rows are Diesel sales
+    comparison_group_index=df["brand_name"] == "Diesel",
+    comparison_group_name="Diesel",
+    # Finally we specifiy that we want to calculate
+    # the gain/loss in total revenue
+    value_col="total_price",
+)
+# Ok now let's plot the result
+gl.plot(
+    x_label="Revenue Change",
+    source_text="Transactions 2023-01-01 to 2023-12-31",
+    move_legend_outside=True,
+)
+plt.show()
+```
+
+![Cross Shop Analysis Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/gain_loss_chart.png)
+
+### Cross Shop Analysis
+
+Here is an excerpt from the cross shop analysis example [notebook](https://pyretailscience.datasimply.co/examples/cross_shop/)
+
+```python
+from pyretailscience import cross_shop
+
+cs = cross_shop.CrossShop(
+    df,
+    group_1_idx=df["category_1_name"] == "Jeans",
+    group_2_idx=df["category_1_name"] == "Shoes",
+    group_3_idx=df["category_1_name"] == "Dresses",
+    labels=["Jeans", "Shoes", "Dresses"],
+)
+cs.plot(
+    title="Jeans are a popular cross-shopping category with dresses",
+    source_text="Source: Transactions 2023-01-01 to 2023-12-31",
+    figsize=(6, 6),
+)
+plt.show()
+# Let's see which customers were in which groups
+display(cs.cross_shop_df.head())
+# And the totals for all groups
+display(cs.cross_shop_table_df)
+```
+
+![Cross Shop Analysis Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/cross_shop_chart.png)
+
+### Customer Retention Analysis
+
+Here is an excerpt from the customer retention analysis example [notebook](https://pyretailscience.datasimply.co/examples/retention/)
+
+```python
+ax = dbp.plot(
+    figsize=(10, 5),
+    bins=20,
+    cumlative=True,
+    draw_percentile_line=True,
+    percentile_line=0.8,
+    source_text="Source: Transactions in 2023",
+    title="When Do Customers Make Their Next Purchase?",
+)
+
+# Let's dress up the chart a bit of text and get rid of the legend
+churn_period = dbp.purchases_percentile(0.8)
+ax.annotate(
+    f"80% of customers made\nanother purchase within\n{round(churn_period)} days",
+    xy=(churn_period, 0.81),
+    xytext=(dbp.purchase_dist_s.min(), 0.8),
+    fontsize=15,
+    ha="left",
+    va="center",
+    arrowprops=dict(facecolor="black", arrowstyle="-|>", connectionstyle="arc3,rad=-0.25", mutation_scale=25),
+)
+ax.legend().set_visible(False)
+plt.show()
+```
+
+![Cumulative Next Purchase Chart](https://raw.githubusercontent.com/Data-Simply/pyretailscience/main/readme_assets/days_until_next_purchase.png)
+
+## Documentation
+
+Please see [here](https://pyretailscience.datasimply.co/) for full documentation, which includes:
+
+- [Analysis Modules](https://pyretailscience.datasimply.co/analysis_modules/): Overview of the framework and the structure of the docs.
+- [Examples](https://pyretailscience.datasimply.co/examples/retention/): If you're looking to build something specific or are more of a hands-on learner, check out our examples. This is the best place to get started.
+- [API Reference](https://pyretailscience.datasimply.co/api/gain_loss/): Thorough documentation of every class and method.
+
+## Contributing
+
+We welcome contributions from the community to enhance and improve PyRetailScience. To contribute, please follow these steps:
+
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix.
+3. Make your changes and commit them with clear messages.
+4. Push your changes to your fork.
+5. Open a pull request to the main repository's `main` branch.
+
+Please make sure to follow the existing coding style and provide unit tests for new features.
+
+## Contact / Support
+
+This repository is supported by Data simply.
+
+If you are interested in seeing what Data Simply can do for you, then please email [email us](mailto:murray@datasimply.co).
+We work with companies at a variety of scales and with varying levels of data and retail analytics sophistication, to
+help them build, scale or streamline their analysis capabilities.
+
+## Contributors
+
+<a href="https://github.com/Data-Simply/pyretailscience/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Data-Simply/pyretailscience" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).
+
+## Acknowledgements
+
+Built with expertise doing analytics and data science for scale-ups to multi-nationals, including:
+
+- Loblaws
+- Dominos
+- Sainbury's
+- IKI
+- Migros
+- Sephora
+- Nectar
+- Metro
+- Coles
+- GANNI
+- Mindful Chef
+- Auchan
+- Attraction Tickets Direct
+- Roman Originals
+
+## License
+
+This project is licensed under the Elastic License 2.0 - see the [LICENSE](LICENSE) file for details.

pyretailscience-0.4.0/pyproject.toml

@@ -0,0 +1,151 @@
+[tool.poetry]
+name = "pyretailscience"
+version = "0.4.0"
+description = "Retail Data Science Tools"
+authors = ["Murray Vanwyk <2493311+mvanwyk@users.noreply.github.com>"]
+readme = "README.md"
+license = "Elastic-2.0"
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.13"
+pandas = "^2.1.4"
+pyarrow = "^14.0.2"
+matplotlib = "^3.9.1"
+numpy = "^1.26.3"
+loguru = "^0.7.2"
+tqdm = "^4.66.1"
+scipy = "^1.13.0"
+scikit-learn = "^1.4.2"
+matplotlib-set-diagrams = "~0.0.2"
+toml = "^0.10.2"
+duckdb = "^1.0.0"
+graphviz = "^0.20.3"
+ibis-framework = {extras = ["duckdb"], version = "^9.5.0"}
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-cov = "^4.1.0"
+nbstripout = "^0.7.1"
+ruff = "^0.4.8"
+pre-commit ="^3.6.2"
+pytest-mock = "^3.14.0"
+
+[tool.poetry.group.examples.dependencies]
+jupyterlab = "^4.2.5"
+tqdm = "^4.66.1"
+
+[tool.poetry.group.docs.dependencies]
+mkdocs-material = "^9.5.4"
+mkdocstrings = {extras = ["python"], version = "^0.24.0"}
+mkdocs = "^1.5.3"
+mkdocs-jupyter = "^0.24.6"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+addopts = "--cov=pyretailscience --cov-report=term-missing  --cov-branch"
+
+[tool.coverage.run]
+branch = true
+source = ["pyretailscience"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+[tool.ruff]
+target-version = "py310"
+line-length=120
+show-fixes = true
+
+[tool.ruff.lint]
+ignore = [
+    "ANN101",
+    "ANN102",
+    "EM101",
+    "TRY003", # Disable until we start creating proper exception classes
+    "PT011",  # Disable until we start creating proper exception classes
+    "PTH123", # Not using open() to open files
+    "SLF001", # Ibis makes a lot of use of the ibis._[column] which triggers this
+]
+select = [
+    "A",    # Builtins
+    "ANN",  # Annotations
+    "ARG",  # Unused arguments
+    "B",    # Bugbear
+    "BLE",  # Blind except
+    "C4",   # Comprehensions
+    "C90",  # mccabe
+    "COM",  # Commas
+    "D",    # Pydocstyle
+    "D1",   # Undocumented public elements
+    "D2",   # Docstring conventions
+    "D3",   # Triple double quotes
+    "D4",   # Docstring text format
+    "DTZ",  # Datetimes
+    "EM",   # Error messages
+    "ERA",  # Commented-out code
+    "EXE",  # Executable
+    "F",    # Pyflakes
+    "FA",   # __future__ annotations
+    "FLY",  # F-strings
+    "G",    # Logging format
+    "I",    # Isort
+    "ICN",  # Import conventions
+    "INP",  # Disallow PEP-420 (Implicit namespace packages)
+    "INT",  # gettext
+    "ISC",  # Implicit str concat
+    "N",    # PEP-8 Naming
+    "NPY",  # Numpy
+    "PERF", # Unnecessary performance costs
+    "PGH",  # Pygrep hooks
+    "PIE",  # Unnecessary code
+    "PL",   # Pylint
+    "PT",   # Pytest
+    "PTH",  # Use Pathlib
+    "PYI",  # Stub files
+    "Q",    # Quotes
+    "RET",  # Return
+    "RUF",  # Ruff
+    "RSE",  # Raise
+    "S",    # Bandit
+    "SIM",  # Code simplification
+    "SLF",  # Private member access
+    "SLOT", # __slots__
+    "T10",  # Debugger
+    "T20",  # Print
+    "TCH",  # Type checking
+    "TID",  # Tidy imports
+    "TRY",  # Exception handling
+    "UP",   # Pyupgrade
+    "W",    # Warnings
+    "YTT",  # sys.version
+]
+
+
+[tool.ruff.lint.per-file-ignores]
+# https://beta.ruff.rs/docs/rules/
+"__init__.py" = ["F401", "F403", "F405", "D104"]
+"tests/*" = ["ANN", "ARG", "INP001", "S101", "SLF001"]
+"*.ipynb" = ["T201"]
+
+[tool.ruff.lint.pylint]
+max-args = 15
+max-branches = 20
+max-returns = 10
+max-statements = 80
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+multiline-quotes = "double"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"