GanttChart

A schedule: one bar per task from its start to its end over a date axis. The Gantt Chart guide shows every feature on real data; this page is the contract: the function, the shape of its data, the keys style takes, and the constant each parameter accepts.

Function

datachart.charts.GanttChart

GanttChart(
    data: list[GanttTaskAttrs] | list[list[GanttTaskAttrs]],
    *,
    title: str | None = None,
    xlabel: str | None = None,
    ylabel: str | None = None,
    subtitle: str | list[str | None] | None = None,
    figsize: FIG_SIZE | tuple[float, float] | None = None,
    xmin: date | datetime | None = None,
    xmax: date | datetime | None = None,
    max_cols: int | None = None,
    period: GANTT_DATE_PERIOD | str | None = None,
    show_group_headers: bool | None = None,
    show_legend: bool | None = None,
    legend: LegendSettingAttrs | None = None,
    show_grid: SHOW_GRID | str | bool | None = None,
    show_values: GANTT_VALUE | str | None = None,
    value_format: VALUE_FORMAT | str | None = None,
    show_dependencies: bool | None = None,
    show_today: bool | None = None,
    today: date | datetime | None = None,
    today_label: str | None = None,
    sort: SORT | str | None = None,
    sort_by: GANTT_SORT_KEY | str | None = None,
    emphasis: (
        EMPHASIS | str | list[str | None] | None
    ) = None,
    emphasis_rule: EmphasisRuleAttrs | None = None,
    style: (
        GanttStyleAttrs
        | list[GanttStyleAttrs | None]
        | None
    ) = None,
    xtickrotate: int | None = None,
    ytickrotate: int | None = None,
    xticks_format: DATE_FORMAT | str | None = None,
    vlines: (
        VLineSettingAttrs | list[VLineSettingAttrs] | None
    ) = None,
    vspans: (
        VSpanSettingAttrs | list[VSpanSettingAttrs] | None
    ) = None,
    texts: (
        TextSettingAttrs | list[TextSettingAttrs] | None
    ) = None
) -> plt.Figure

Creates the gantt chart.

A gantt chart shows a schedule: one horizontal bar per task from its start to its end over a date axis, one row per task, the first task at the top. Use it for project plans, release roadmaps, or any set of activities where when and how long matter more than a single value. Task groups share a colour or get header rows with summary bars, an optional progress fraction fills part of each bar, a task ending when it starts is a milestone marker, dependency arrows link tasks, the date axis can be divided into calendar periods, and a today line marks the present.

The chart is always horizontal, so the axis parameters are spatial: xlabel, xmin, xmax, and xticks_format address the horizontal date axis, and ylabel the vertical task axis. It composes in Grid, but not in Panel.

Examples:

>>> from datetime import date
>>> from datachart.charts import GanttChart
>>> figure = GanttChart(
...     data=[
...         {"task": "Design", "start": date(2024, 1, 1), "end": date(2024, 1, 12),
...          "group": "Plan", "progress": 1.0},
...         {"task": "Build", "start": date(2024, 1, 10), "end": date(2024, 2, 9),
...          "group": "Make", "progress": 0.4, "depends_on": ["Design"]},
...         {"task": "Test", "start": date(2024, 2, 5), "end": date(2024, 2, 23),
...          "group": "Make", "depends_on": ["Build"]},
...     ],
...     title="Release Plan",
...     show_dependencies=True,
... )

PARAMETER	DESCRIPTION
data	The task records of the schedule: a list of {task, start, end} dicts with optional group, progress, depends_on, and emphasis keys. start and end are date, datetime, numpy.datetime64, or pandas Timestamp objects; date strings are never parsed. A list of such lists draws one schedule per subplot. See GanttTaskAttrs. TYPE: list[GanttTaskAttrs] | list[list[GanttTaskAttrs]]
title	The title of the chart. TYPE: str | None DEFAULT: None
xlabel	The label of the horizontal date axis. TYPE: str | None DEFAULT: None
ylabel	The label of the vertical task axis. TYPE: str | None DEFAULT: None
subtitle	The subtitle of each schedule. TYPE: str | list[str | None] | None DEFAULT: None
figsize	The size of the figure as (width, height) in inches. See FIG_SIZE. TYPE: FIG_SIZE | tuple[float, float] | None DEFAULT: None
xmin	The start of the date window, as a temporal object. TYPE: date | datetime | None DEFAULT: None
xmax	The end of the date window, as a temporal object. TYPE: date | datetime | None DEFAULT: None
max_cols	The maximum number of subplot columns for several schedules. TYPE: int | None DEFAULT: None
period	The calendar period the date axis is divided into: None (concise date ticks), "day", "week", "month", "quarter", "year", or "project_month" (M1, M2, … from xmin or the earliest start). Lines mark the period edges, each period is labelled at its centre, and a row beneath names the enclosing month or year. xticks_format sets the period labels. See GANTT_DATE_PERIOD. TYPE: GANTT_DATE_PERIOD | str | None DEFAULT: None
show_group_headers	Whether to give each task group a header row with a summary bar from its first start to its last end, the group's rows clustered beneath it and a gap before the next group. Raises when no task carries a group. TYPE: bool | None DEFAULT: None
show_legend	Whether to show the legend of the task groups. Defaults to on when any task carries a group and the group headers are off. TYPE: bool | None DEFAULT: None
legend	The per-figure legend setting: title, location, column count and alignment; each field falls back to the theme. See LegendSettingAttrs. TYPE: LegendSettingAttrs | None DEFAULT: None
show_grid	Which grid lines to show ("both", "x", "y"); False draws none. See SHOW_GRID. TYPE: SHOW_GRID | str | bool | None DEFAULT: None
show_values	The label printed past each bar end: None (none), "duration" (the duration in days), or "progress" (the progress as a percentage). A milestone prints its date instead, in the xticks_format or as day and month. See GANTT_VALUE. TYPE: GANTT_VALUE | str | None DEFAULT: None
value_format	Format string for the value labels: a VALUE_FORMAT constant or any "{x:.1f}", "{:.1f}%", or "%g" style string. It formats the duration in days, or the progress fraction. TYPE: VALUE_FORMAT | str | None DEFAULT: None
show_dependencies	Whether to draw an arrow from the end of each task named in depends_on to the start of the task depending on it. TYPE: bool | None DEFAULT: None
show_today	Whether to draw the today line. TYPE: bool | None DEFAULT: None
today	The date of the today line; the current date when not given. TYPE: date | datetime | None DEFAULT: None
today_label	The text printed at the foot of the today line; none when not given. TYPE: str | None DEFAULT: None
sort	The order of the task rows: None (input order), "ascending", or "descending" by the key sort_by names. Ties keep input order. See SORT. TYPE: SORT | str | None DEFAULT: None
sort_by	The key sort orders by: "start" (default) orders every row by its start; "group" clusters the rows by group, the groups ordered by their earliest start and the tasks within a group by start. Requires sort. See GANTT_SORT_KEY. TYPE: GANTT_SORT_KEY | str | None DEFAULT: None
emphasis	The emphasis role of the whole schedule ("background" or "highlight"), or one role per schedule. See EMPHASIS. TYPE: EMPHASIS | str | list[str | None] | None DEFAULT: None
emphasis_rule	A one-key dict that highlights the tasks matching it and mutes the rest: {"above": v} or {"below": v} (strict), {"between": (lo, hi)} (inclusive), {"top": n} or {"bottom": n}. Reads each task's duration in days; a task's own emphasis key wins over the rule. See EmphasisRuleAttrs. TYPE: EmphasisRuleAttrs | None DEFAULT: None
style	Style configuration(s) for the schedule. See GanttStyleAttrs. TYPE: GanttStyleAttrs | list[GanttStyleAttrs | None] | None DEFAULT: None
xtickrotate	Rotation angle for the date-axis tick labels. TYPE: int | None DEFAULT: None
ytickrotate	Rotation angle for the task-axis tick labels. TYPE: int | None DEFAULT: None
xticks_format	The date-axis tick label format: a DATE_FORMAT member or strftime pattern. TYPE: DATE_FORMAT | str | None DEFAULT: None
vlines	Vertical line(s) to plot, at temporal x positions. TYPE: VLineSettingAttrs | list[VLineSettingAttrs] | None DEFAULT: None
vspans	Vertical reference band(s) to shade, between two temporal positions. TYPE: VSpanSettingAttrs | list[VSpanSettingAttrs] | None DEFAULT: None
texts	Text annotation(s) to draw. TYPE: TextSettingAttrs | list[TextSettingAttrs] | None DEFAULT: None

RETURNS	DESCRIPTION
plt.Figure	The figure containing the gantt chart.

Data

Each record in data is a GanttTaskAttrs; the emphasis parameter renames its keys.

datachart.typings.GanttTaskAttrs

Bases: TypedDict

The task record attributes for the gantt chart.

ATTRIBUTE	DESCRIPTION
task	The task name, unique within the chart; the label of its row. TYPE: str
start	When the task starts: a date, datetime, numpy.datetime64, or pandas Timestamp. Date strings are never parsed. TYPE: date | datetime
end	When the task ends, of the same temporal types; never before start. A task ending when it starts is a milestone, drawn as a marker. TYPE: date | datetime
group	The task group; tasks of one group share a color and a legend entry. TYPE: str | None
progress	The fraction of the task done, in [0, 1]; drawn as an inner bar. TYPE: int | float | None
depends_on	The names of the tasks this task depends on. TYPE: list[str] | None
emphasis	The task's own emphasis role ("background" or "highlight"); wins over the chart's emphasis_rule. TYPE: EMPHASIS | str | None

Style

style takes the keys of GanttStyleAttrs. The chart also reads the shared groups it draws: value labels (ValueLabelStyleAttrs), reference lines (VLineStyleAttrs and HLineStyleAttrs), reference bands (VSpanStyleAttrs and HSpanStyleAttrs) and text annotations (TextStyleAttrs). Every key falls back to the theme, so the same keys set the default look through config.

datachart.typings.GanttStyleAttrs

Bases: TypedDict

The typing for the gantt chart style.

The range bars take the plot_bar_* keys (color, alpha, edge, hatch, zorder); these keys set what is specific to a gantt chart.

ATTRIBUTE	DESCRIPTION
plot_gantt_bar_height	The height of a task bar, as a fraction of its row. TYPE: int | float | None
plot_gantt_progress_color	The color of the progress bar; None darkens the task bar's color. TYPE: str | None
plot_gantt_progress_alpha	The alpha value of the progress bar. TYPE: float | None
plot_gantt_progress_height	The height of the progress bar, as a fraction of the task bar. TYPE: int | float | None
plot_gantt_dependency_color	The color of the dependency arrows. TYPE: str | None
plot_gantt_dependency_width	The line width of the dependency arrows. TYPE: int | float | None
plot_gantt_dependency_style	The arrow head of the dependency arrows, as a matplotlib arrow style. TYPE: str | None
plot_gantt_dependency_zorder	The zorder of the dependency arrows. TYPE: int | float | None
plot_gantt_dependency_entry	The side of the dependent task a dependency arrow enters ("top" or "left"). TYPE: GANTT_ARROW_ENTRY | str | None
plot_gantt_summary_height	The height of a group's summary bar under show_group_headers, as a fraction of its row. TYPE: int | float | None
plot_gantt_summary_color	The color of the summary bars; None takes each group's color. TYPE: str | None
plot_gantt_group_gap	The empty space before each group header, in rows. TYPE: int | float | None
plot_gantt_milestone_marker	The marker of a milestone, a task whose start equals its end. TYPE: LINE_MARKER | str | None
plot_gantt_milestone_size	The size of the milestone marker, in points. TYPE: int | float | None
plot_gantt_today_color	The color of the today line. TYPE: str | None
plot_gantt_today_style	The line style of the today line. TYPE: LINE_STYLE | str | None
plot_gantt_today_width	The line width of the today line. TYPE: int | float | None
plot_gantt_today_alpha	The alpha value of the today line. TYPE: float | None

Constants

The parameters that accept a constant, with the class in datachart.constants that lists its values.

Parameter	Constant
period	GANTT_DATE_PERIOD
show_values	GANTT_VALUE
sort_by	GANTT_SORT_KEY
style={"plot_gantt_dependency_entry": ...}	GANTT_ARROW_ENTRY
figsize	FIG_SIZE
legend={"location": ..., "alignment": ...}	LEGEND_LOCATION, LEGEND_ALIGN
show_grid	SHOW_GRID
value_format	VALUE_FORMAT
sort	SORT
emphasis	EMPHASIS
xticks_format	DATE_FORMAT