API Reference

def main() -> None:
    """Entry point when running this file as a Python script.

    This is where the instructions begin.

    Arguments: None.
    Returns: None.
    """
    log_header(LOG, "P01")

    LOG.info("===================================")
    LOG.info("START main()")
    LOG.info("===================================")

    LOG.info("-------------------------------")
    LOG.info("01. LOAD the data.")
    LOG.info("-------------------------------")

    # Use the imported privacy-preserving log_path() function
    # To indicate where we will look for the data file.
    log_path(LOG, "data file", path=DATA_FILE_PATH)

    # Call the built-in pandas `read_csv` function.
    # Store the tabular pandas DataFrame returned
    # in a local variable named `df`.

    df: pd.DataFrame = pd.read_csv(DATA_FILE_PATH)

    LOG.info("Data loaded successfully.")

    LOG.info("-------------------------------")
    LOG.info("02. INSPECT the data.")
    LOG.info("-------------------------------")

    # Call the inspect() function to get a string
    # with basic information about the DataFrame.
    # Pass in the pandas DataFrame (df)
    # The grain (what one row represents)
    # And the log so it knows where to send messages.

    inspection_string: str = inspect(df=df, grain=GRAIN, log=LOG)

    LOG.info(inspection_string)

    LOG.info("-------------------------------")
    LOG.info("03. DESCRIBE the data.")
    LOG.info("-------------------------------")

    # Call the get_analyst_description function.
    # Pass in the variables defined above.
    # The function will return a string
    # with a summary of the data from the analyst's perspective.

    summary_string: str = get_analyst_description(
        grain=GRAIN,
        target=A_TARGET_WE_COULD_PREDICT,
        feature=A_FEATURE_THAT_MIGHT_HELP,
        why=WHY_THE_FEATURE_MIGHT_HELP,
        log=LOG,
    )
    # Log the summary string.
    LOG.info(summary_string)

    LOG.info("-------------------------------")
    LOG.info("04. VISUALIZE the selected target and feature.")
    LOG.info("-------------------------------")

    # We required both the target and the feature to be numeric columns.
    # A good way to visualize the relationship
    # between two numeric columns is a scatter plot.

    # Define a path to save the feature vs target scatter plot.
    # REQUIRED: Use the "docs/images" folder to store generated charts.
    CHART_PATH = Path("docs/images/feature-target-scatter.png")

    # Call an imported function that will show a scatter plot
    # Pass in the pandas DataFrame (df) along with the target and feature column names.
    # It will return a matplotlib Axes object representing the scatter plot.
    ax = show_numeric_relationship(
        df, x=A_FEATURE_THAT_MIGHT_HELP, y=A_TARGET_WE_COULD_PREDICT
    )

    # call the save_chart() function and pass in the Axes and the path
    save_chart(ax, CHART_PATH)
    LOG.info(f"Chart saved successfully at {CHART_PATH}.")

    LOG.info(
        "IMPORTANT: Close chart window to continue by clicking its X or close button."
    )
    plt.show()

    LOG.info("===================================")
    LOG.info("END main() - Executed successfully!")
    LOG.info("===================================")

def get_analyst_description(
    grain: str,
    target: str,
    feature: str,
    why: str,
    log: logging.Logger,
) -> str:
    """Get a formatted summary string of the analyst description.

    These are the analyst's declarations, written after looking at the data.
    This is critical analyst work: look, then say what one row means,
    which of the columns might be a target we could predict,
    which of the columns might be a feature we could use if we
    were to build a model to predict the target,
    and why we think that feature might be related to the target.

    Arguments:
        grain: what one row means.
        target: a thing we could try to predict.
        feature: a feature (clue / indicator / column) that might help.
        why: why this feature might help predict the target.
        log: the logger to write progress to.

    Returns:
        a formatted multi-line string.
    """
    log.info("START get_analyst_description")

    summary_string: str = f"""
--------------------------------------------------------
Analyst Data Description (and Possible Prediction Plan):
--------------------------------------------------------
    A row represents:           {grain}
    A target we might predict:  {target}
    A feature that might help:  {feature}
    Why the feature might help: {why}
"""

    log.info("END get_analyst_description. Returning summary_string.")
    return summary_string

def inspect(df: pd.DataFrame, grain: str, log: logging.Logger) -> str:
    """Get a formatted inspection string from the data.

    Ask the data about itself.
    No need to type column names by hand - the data knows.

    Arguments:
        df: the loaded pandas DataFrame (a 2-dimensional table like an Excel sheet).
        grain: what one row represents.
        log: the logger to send progress messages to.

    Returns:
        a formatted multi-line string.
    """
    log.info("START inspect")

    # Get the count of rows.
    row_count: int = len(df)

    # Get the count of columns.
    column_count: int = len(df.columns)

    # Get a list of column names.
    column_names: list[str] = list(df.columns)

    # Get the first few rows of data
    first_rows: pd.DataFrame = df.head()

    # Log the facts Python discovered about the data.
    log.info("   row_count:    %s", row_count)
    log.info("   column_count: %s", column_count)
    log.info("   column_names: %s", column_names)

    # Build a readable string to return to the calling code.
    # Use a multi-line string (triple quotes) to make it easy to read.
    # Use a formatted string (f before the opening) so we can pass in information
    inspection_string: str = f"""
----------------
Data Inspection:
----------------
    One row means: {grain}
    Row count: {row_count}
    Column count: {column_count}
    Column names: {column_names}

---------------
First Few Rows:
---------------
{first_rows}
"""

    log.info("END inspect. Returning inspection_string.")
    return inspection_string