# 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.

::: abacus.prepro.dir

## Functions

### `make_results_dir`

```python
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`

```python
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.