Abacus Preprocessing: Directory (dir.py)ΒΆ

This module provides utility functions for creating uniquely named directories to store the outputs (plots, data files, configuration) generated during a Marketing Mix Model (MMM) run.

Functions

make_results_dir

def make_results_dir(
    data_dir: str, dirname_fixed: str = "", results_key: str = ""
) -> str:

Creates a new directory within a structured path, using a unique key to avoid overwriting previous results.

The directory structure created is typically: <data_dir>/results/<dirname_fixed>/<unique_key>/.

If results_key is not provided, a unique key is generated based on the current date and time using generate_unique_date_key(). The function ensures the directory does not already exist before creating it (os.makedirs with exist_ok=False).

Parameters:

  • data_dir (str): The base directory path where the results subdirectory structure will be created (e.g., the project root).

  • dirname_fixed (str, optional): An optional subdirectory name to insert between results and the unique key directory. Useful for organising results by project or customer. Defaults to "".

  • results_key (str, optional): A specific key to use as the final directory name. If empty (default), a unique timestamp-based key is generated.

Returns:

  • str: The full path to the newly created unique results directory.

Raises:

  • FileExistsError: If a directory with the generated path already exists.

generate_unique_date_key

def generate_unique_date_key() -> str:

Generates a unique string based on the current date and time.

The format is YYYY-MM-DD-SSSSSS, where SSSSSS represents the number of seconds elapsed since midnight on the current date. This provides a reasonably unique identifier for naming results directories created at different times.

Returns:

  • str: A unique key string based on the current timestamp.