pyretailscience 0.1.0__py3-none-any.whl

pyretailscience/data/cli.py

@@ -0,0 +1,46 @@
+import sys
+
+import click
+from loguru import logger
+
+from pyretailscience.data import simulation
+
+
+@click.command()
+@click.option("--config_file", type=click.Path(dir_okay=False))
+@click.option("--verbose", type=bool, default=False)
+@click.option("--seed", default=1234, type=int)
+@click.argument("output_file", type=click.Path(dir_okay=False))
+def generate(
+    config_file: str,
+    verbose: bool,
+    seed: int,
+    output_file: str,
+):
+    """Generate a CSV file with random transaction data.
+
+    args:
+        config_file (str): Configuration file for the simulation
+        verbose (bool): Whether to print debug messages
+        seed (int): random seed
+        output_file (str): File to write the transactions to in parquet format
+    """
+
+    # Set logging level to info
+    logger.remove()
+    if verbose:
+        logger.add(sys.stderr, level="DEBUG")
+    else:
+        logger.add(sys.stderr, level="INFO")
+
+    logger.info("Generating data...")
+
+    sim = simulation.Simulation(seed=seed, config_file=config_file)
+    sim.run()
+    sim.save_transactions(output_file)
+
+    logger.info("Done!")
+
+
+if __name__ == "__main__":
+    generate()

pyretailscience/data/simulation.py

@@ -0,0 +1,300 @@
+import uuid
+from dataclasses import dataclass
+from datetime import date, datetime, time, timedelta
+
+import numpy as np
+import pandas as pd
+import strictyaml as yaml
+from loguru import logger
+from tqdm import tqdm
+
+# Configuration schema for the config file yaml
+schema = yaml.Map(
+    {
+        "stores": yaml.Map(
+            {
+                "number_of_stores": yaml.Int(),
+            }
+        ),
+        "transactions": yaml.Map(
+            {
+                "start_date": yaml.Datetime(),
+                "end_date": yaml.Datetime(),
+                "start_hour": yaml.Int(),
+                "end_hour": yaml.Int(),
+                "max_products_per_transaction": yaml.Int(),
+            }
+        ),
+        "customers": yaml.Map(
+            {
+                "starting_number_of_customers": yaml.Int(),
+                "churn_probability": yaml.Float(),
+                "average_time_between_purchases": yaml.Int(),
+                "average_new_customers_per_day": yaml.Int(),
+            }
+        ),
+        "products": yaml.Seq(
+            yaml.Map(
+                {
+                    "category_0": yaml.Str(),
+                    "category_0_id": yaml.Int(),
+                    "subcategories": yaml.Seq(
+                        yaml.Map(
+                            {
+                                "category_1": yaml.Str(),
+                                "category_1_id": yaml.Int(),
+                                "brands": yaml.Seq(
+                                    yaml.Map(
+                                        {
+                                            "brand": yaml.Str(),
+                                            "brand_id": yaml.Int(),
+                                            "products": yaml.Seq(
+                                                yaml.Map(
+                                                    {
+                                                        "product_name": yaml.Str(),
+                                                        "product_id": yaml.Int(),
+                                                        "unit_price": yaml.Float(),
+                                                    }
+                                                )
+                                            ),
+                                        }
+                                    )
+                                ),
+                            }
+                        )
+                    ),
+                }
+            )
+        ),
+    }
+)
+
+
+def _random_time(rnd_generator: np.random.Generator, start_hour, end_hour):
+    hour = rnd_generator.integers(start_hour, end_hour)
+    minute = rnd_generator.integers(0, 60)
+    second = rnd_generator.integers(0, 60)
+
+    return time(hour, minute, second)
+
+
+@dataclass
+class Product:
+    category_0: str
+    category_0_id: int
+    category_1: str
+    category_1_id: int
+    brand: str
+    brand_id: int
+    product_name: str
+    product_id: int
+    unit_price: float
+    quantity_mean: int
+
+
+class TransactionGenerator:
+    """Generates a random transaction for a customer."""
+
+    def __init__(
+        self,
+        rnd_generator: np.random.Generator,
+        num_stores: int,
+        max_products_per_transaction: int,
+        products: list[Product],
+        start_hour: int,
+        end_hour: int,
+    ):
+        self.num_stores = num_stores
+        self.rnd_generator = rnd_generator
+        self.products = products
+        self.max_products_per_transaction = max_products_per_transaction
+        self.start_hour = start_hour
+        self.end_hour = end_hour
+
+    def generate_transaction(self, customer_id: int, simulation_date: date) -> dict:
+        # Combine transaction_date with a random time
+        simulation_datetime = datetime.combine(
+            simulation_date,
+            _random_time(
+                rnd_generator=self.rnd_generator,
+                start_hour=self.start_hour,
+                end_hour=self.end_hour,
+            ),
+        )
+
+        store_id = self.rnd_generator.integers(1, self.num_stores)
+        products = self.rnd_generator.choice(
+            self.products, size=self.rnd_generator.integers(1, self.max_products_per_transaction)
+        )
+        quantity = self.rnd_generator.integers(1, self.max_products_per_transaction)
+
+        # Generate a UUID for now, but we'll change it to a sequential integer later
+        transaction_id = str(uuid.uuid4())
+
+        transaction_lines = []
+        for product in products:
+            quantity = self.rnd_generator.poisson(product.quantity_mean)
+            total_price = float(product.unit_price) * quantity
+
+            transaction = {
+                "transaction_id": transaction_id,
+                "date": simulation_datetime,
+                "customer_id": customer_id,
+                "product_id": product.product_id,
+                "product_name": product.product_name,
+                "category_0": product.category_0,
+                "category_0_id": product.category_0_id,
+                "category_1": product.category_1,
+                "category_1_id": product.category_1_id,
+                "brand": product.brand,
+                "brand_id": product.brand_id,
+                "unit_price": float(product.unit_price),
+                "quantity": quantity,
+                "total_price": total_price,
+                "store_id": store_id,
+            }
+
+            transaction_lines.append(transaction)
+
+        return transaction_lines
+
+
+class Customer:
+    has_churned = False
+
+    def __init__(
+        self,
+        rnd_generator: np.random.Generator,
+        churn_prob: float,
+        customer_id: int,
+        transaction_gen: TransactionGenerator,
+        period_between_purchases: int,
+    ):
+        self.rnd_generator = rnd_generator
+        self.churn_prob = churn_prob
+        self.id = customer_id
+        self.transaction_gen = transaction_gen
+        self.periods_between_purchases = period_between_purchases
+        self.transactions = []
+
+        self.time_to_next_purchase = self.rnd_generator.poisson(period_between_purchases)
+
+    def step(self, date: date = None) -> None:
+        if self.has_churned:
+            return
+
+        if self.time_to_next_purchase == 0:  # time to buy!
+            logger.debug("Customer made a purchase")
+            purchase = self.transaction_gen.generate_transaction(self.id, date)
+            self.transactions.extend(purchase)
+
+            # Bernoulli trial to see if customer churns
+            if self.rnd_generator.binomial(1, self.churn_prob):
+                self.has_churned = True
+                logger.debug(f"Customer {self.id} churned")
+            else:
+                self.time_to_next_purchase = self.rnd_generator.poisson(self.periods_between_purchases)
+        else:
+            self.time_to_next_purchase -= 1
+
+
+class Simulation:
+    def __init__(
+        self,
+        seed: int,
+        config_file: str,
+    ):
+        self.seed = seed
+        with open(config_file, "r") as f:
+            try:
+                self.config = yaml.load(f.read(), schema).data
+            except yaml.YAMLError as error:
+                logger.error(error)
+                raise error
+
+        self.rnd_generator = np.random.default_rng(self.seed)
+
+        self.products = self._load_products()
+
+        self.customers = [
+            self._create_customer(customer_id=customer_id)
+            for customer_id in range(1, self.config["customers"]["starting_number_of_customers"] + 1)
+        ]
+        self.transactions = []
+
+    def step(self, date: date) -> None:
+        num_new_customers = self.rnd_generator.poisson(self.config["customers"]["average_new_customers_per_day"])
+        logger.debug(f"Adding {num_new_customers} new customers")
+        self.customers.extend(
+            [
+                self._create_customer(customer_id=new_customer_id)
+                for new_customer_id in range(len(self.customers) + 1, num_new_customers + 1)
+            ]
+        )
+        # Simulate each customer
+        for customer in self.customers:
+            customer.step(date)
+
+    def run(self) -> None:
+        start_date = self.config["transactions"]["start_date"].date()
+        end_date = self.config["transactions"]["end_date"].date()
+        days_in_simulation = [start_date + timedelta(n) for n in range((end_date - start_date).days)]
+        for sim_day in tqdm(days_in_simulation, desc="Simulating days"):
+            self.step(sim_day)
+
+        transactions = []
+        for customer in self.customers:
+            transactions.extend(customer.transactions)
+
+        # Change transactions UUIDs to sequential integers
+        unique_transaction_ids = set([t["transaction_id"] for t in transactions])
+        transaction_id_map = {transaction_id: i for i, transaction_id in enumerate(unique_transaction_ids)}
+        for transaction in transactions:
+            transaction["transaction_id"] = transaction_id_map[transaction["transaction_id"]]
+
+        self.transactions = transactions
+
+    def _create_customer(self, customer_id: int) -> Customer:
+        return Customer(
+            rnd_generator=self.rnd_generator,
+            churn_prob=self.config["customers"]["churn_probability"],
+            customer_id=customer_id,
+            period_between_purchases=self.config["customers"]["average_time_between_purchases"],
+            transaction_gen=TransactionGenerator(
+                rnd_generator=self.rnd_generator,
+                num_stores=self.config["stores"]["number_of_stores"],
+                max_products_per_transaction=self.config["transactions"]["max_products_per_transaction"],
+                products=self.products,
+                start_hour=self.config["transactions"]["start_hour"],
+                end_hour=self.config["transactions"]["end_hour"],
+            ),
+        )
+
+    def _load_products(self) -> list[Product]:
+        products = []
+
+        for category_0 in self.config["products"]:
+            for category_1 in category_0["subcategories"]:
+                for brand in category_1["brands"]:
+                    for product in brand["products"]:
+                        products.append(
+                            Product(
+                                category_0=category_0["category_0"],
+                                category_0_id=int(category_0["category_0_id"]),
+                                category_1=category_1["category_1"],
+                                category_1_id=int(category_1["category_1_id"]),
+                                brand=brand["brand"],
+                                brand_id=int(brand["brand_id"]),
+                                product_name=product["product_name"],
+                                product_id=int(product["product_id"]),
+                                unit_price=product["unit_price"],
+                                # TODO: Move this to the config file
+                                quantity_mean=self.rnd_generator.poisson(self.rnd_generator.integers(1, 3)),
+                            )
+                        )
+        return products
+
+    def save_transactions(self, output_file: str) -> None:
+        df = pd.DataFrame(self.transactions)
+        logger.info(f"Saving {len(df)} transactions to {output_file}")
+        df.to_parquet(output_file, index=False)

pyretailscience-0.1.0.dist-info/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

pyretailscience-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.1
+Name: pyretailscience
+Version: 0.1.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.12
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: click (>=8.1.7,<9.0.0)
+Requires-Dist: loguru (>=0.7.2,<0.8.0)
+Requires-Dist: matplotlib (>=3.8.2,<4.0.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: seaborn (>=0.13.1,<0.14.0)
+Requires-Dist: strictyaml (>=1.7.3,<2.0.0)
+Description-Content-Type: text/markdown
+
+![pyretailscience logo](logo.png)
+
+# pyretailscience
+
+⚡ Democratizing retail data analytics for all retailers ⚡
+
+pyretailscience is a Python package designed for performing analytics on retail data. Additionally, the package includes functionality for generating test data to facilitate testing and development.

pyretailscience-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyretailscience/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyretailscience/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyretailscience/data/cli.py,sha256=GxLUcRPbRbdDfYnH4JwQjqv2oHDlo9ub3Tzty61BsZA,1148
+pyretailscience/data/simulation.py,sha256=F6hUvQN8Eg3nq_EPUsu1j9pzOmMLGlV6JwmfmL2FC1Q,11265
+pyretailscience-0.1.0.dist-info/LICENSE,sha256=ZPwVR73Biwm3sK6vR54djCrhaRiM4cAD2zvOQZV8Xis,3859
+pyretailscience-0.1.0.dist-info/METADATA,sha256=VbYi6PnF_FsFtn00NQBqESyEFEgZTKBsgAePPARgRRI,1103
+pyretailscience-0.1.0.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+pyretailscience-0.1.0.dist-info/entry_points.txt,sha256=VJFsbNuCLiNNiOxZ_JYZ_4ZerEQ5rRTpc5jfvkh8Fys,69
+pyretailscience-0.1.0.dist-info/RECORD,,

pyretailscience-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.8.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pyretailscience-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pyretailscience=pyretailscience.data.cli:generate
+