Skip to content

CausalIQ Analysis Plot

This package draws charts using matplotlib and Seaborn from a summarise CSV output, migrated from the legacy experiments/plot.py module.

The public names are re-exported from causaliq_analysis.plot, so existing imports are unchanged. Internally the package is split into:

  • causaliq_analysis.plot.properties — chart property parsing;
  • causaliq_analysis.plot.axes — axis styling and box/violin annotations;
  • causaliq_analysis.plot.charts — the seaborn chart builders;
  • causaliq_analysis.plot.run — the run_plot entry point and CSV helpers.

SUPPORTED_KINDS lists the plot kinds accepted by the plot action (line, regression, histogram, box, violin, bar and scatter).

Entry Point

run_plot

run_plot(
    input_path: str,
    output: str,
    kind: str = "line",
    subplot: str = "",
    group: str = "",
    x: str = "",
    y: str = "",
    properties: Optional[Union[str, List[str]]] = None,
    log_fn: Optional[Callable[[str], None]] = None,
) -> Dict[str, Any]

Generate a chart from summarise output or a metrics cache.

The input is either a summarise CSV (one row per subplot, x value and group combination) or a metrics workflow cache (.db) whose entries carry a metrics object. The chart is generated using the migrated legacy plotting functions.

Parameters:

  • input_path

    (str) –

    path of the input CSV file or metrics cache.

  • output

    (str) –

    path of the output chart file (e.g. .png or .jpg).

  • kind

    (str, default: 'line' ) –

    type of plot required, e.g. line or bar.

  • subplot

    (str, default: '' ) –

    column name defining the subplot.

  • group

    (str, default: '' ) –

    column name defining the groups shown in the legend.

  • x

    (str, default: '' ) –

    column name providing the x-axis values.

  • y

    (str, default: '' ) –

    column name providing the y-axis values.

  • properties

    (Optional[Union[str, List[str]]], default: None ) –

    list of chart property strings in <name>=<value> format with Python literal values.

  • log_fn

    (Optional[Callable[[str], None]], default: None ) –

    optional callback used to log progress messages.

Returns:

  • Dict[str, Any] –

    Dictionary of metadata describing the chart generated.

Raises:

  • ValueError –

    If the kind, columns or input file are invalid.

Property Parsing

parse_properties

parse_properties(properties: Optional[Union[str, List[str]]]) -> Dict[str, Any]

Parse chart property strings into a typed dictionary.

Each property is a string of the form <name>=<value> (e.g. "int.property=22"). Values are parsed as Python literals so "0.05" becomes a float, "[1, 2]" a list, "{'a': 1}" a dict and "True" a boolean.

Parameters:

  • properties

    (Optional[Union[str, List[str]]]) –

    list of property strings, a single string, or None.

Returns:

  • Dict[str, Any] –

    Dictionary of parsed property names to typed values.

Raises:

  • ValueError –

    If a property string is malformed.

Chart Builders

relplot

relplot(
    data: DataFrame,
    props: Dict[str, Any],
    plot_file: str,
    info: Optional[Dict[str, SubplotInfo]] = None,
) -> None

Plot a set of relational charts.

Parameters:

  • data

    (DataFrame) –

    data in long form with the following columns: subplot (identifies the subplot), x_val (x values), y_var (y-variable on each subplot) and y_val (y values).

  • props

    (Dict[str, Any]) –

    customisable properties of the chart.

  • plot_file

    (str) –

    path of the output plot file.

  • info

    (Optional[Dict[str, SubplotInfo]], default: None ) –

    optional extra information to print on the chart.

Raises:

  • ValueError –

    If an unsupported subplot.kind is requested.

plot_scatter

plot_scatter(data: DataFrame, props: Dict[str, Any], plot_file: str) -> None

Plot one or more scatter plots.

Parameters:

  • data

    (DataFrame) –

    data in long form with the columns subplot, x_val, y_var and y_val.

  • props

    (Dict[str, Any]) –

    customisable properties of the chart.

  • plot_file

    (str) –

    path of the output plot file.

plot_degree_distribution

plot_degree_distribution(dist: DataFrame, plot_file: str) -> None

Plot node degree distributions for networks.

Parameters:

  • dist

    (DataFrame) –

    data with network, metric and value columns.

  • plot_file

    (str) –

    path of the output plot file.