API Docs

Class: ScheduleEditor

PD.SVG. ScheduleEditor

Defines an editable heatmap of days of the year arranged in weekly columns.

This type of chart displays the 365 days of the year (366 in a leap year), laid out in a 54x7 grid (54x12 when in EnergyPlus mode) with optional month separators. The horizontal axis is effectively weeks of the year and the vertical axis is days of the week. Depending on the size of the chart and its configuration, each month can wrap over multiple horizontal lines or be shown vertically.

Whilst it typically displays the annual daily profiles

          JAN   FEB  MAR  APR   MAY  JUN  JUL   AUG  SEP   OCT  NOV  DEC
        +------------------------------------------------------------------+
    MON | ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ |
    TUE | ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ |
    WED | ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐  |
    THU | ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐  |
    FRI | ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐  |
    SAT | ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐  |
    SUN | ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐ ☐☐☐☐ ☐☐☐☐ ☐☐☐☐☐  |
        +------------------------------------------------------------------+
          1    5     10    15    20    25    30    35     40    45    50
                              WEEKS OF THE YEAR

Each day of the year can be individually colored and selected based on its value, day type or month of the year. This type of chart is typically used to display and edit PD.Schedule and BIM.Schedule data.

EnergyPlus Mode

In EnergyPlus mode, each week has 12 slots for day schedules instead of 7. The extra 5 day schedules in each week (indexes 7 through 11) are designated as 7:Holiday, 8:SummerDesignDay, 9:WinterDesignDay, 10:CustomDay1 and 11:CustomDay2. This allows EnergyPlus to use the same schedule across different regions that may have different holiday periods, as well as being able to control seasonal variation in other conditions such as lighting, heating, cooling or ventilation.

new ScheduleEditor(config)

Creates a new annual daily schedule editor.

Parameters:
Name Type Description
config object

A configuration object.
Properties of config:
Name Type Argument Description
svgId SVGElement | string

The SVG element to use, or the DOM identifier of an SVG element.
scaleToFit boolean <optional>

Whether or not to automatically size chart to canvas.
isVertical boolean <optional>

Whether or not to run months in vertical axis.
monthWrap number <optional>

The number of months in each row.
monthAutoWrap boolean <optional>

Whether or not to automatically calculate row lengths.
monthBoundaries boolean <optional>

Whether or not to show lines between months.
monthSeparation number <optional>

The number of cells to separate months by.
isLeapYear boolean <optional>

Whether or not to include 366 days rather than 365.
textOverlay number <optional>

The information text to show in each cell.
cellSizeMin number <optional>

The minimum allowable pixel size of each cell.
cellSizeAbs number <optional>

The absolute pixel size of each cell when not scaled.
startDay number <optional>

The day of the week to start at (0 to 6).
selectAction number <optional>

What action to take when interactively selecting.
showWeekNumbers boolean <optional>

Whether or not to display week numbers.
eplusMode boolean <optional>

Whether or not to display weekly slots with 12 cells.
colorBy number <optional>

The color scale to use for each cell.
cellGap number <optional>

The number of pixels between cells.
tooltipWidth number <optional>

The width of the selection tooltip.
tooltipHeight number <optional>

The height of the selection tooltip.
throttledRescale number <optional>

The number of milliseconds to throttle calls to rescale() by.
padding Array <optional>

An array of padding pixels in top, right, bottom, left order.
paddingTop number <optional>

The number of padding pixels at the top of the chart.
paddingRight number <optional>

The number of padding pixels to the right of the chart.
paddingBottom number <optional>

The number of padding pixels at the bottom of the chart.
paddingLeft number <optional>

The number of padding pixels to the left of the chart.
title string <optional>

The primary title to display in the chart.
subTitle string <optional>

The secondary title to display in the chart.
units string <optional>

The units to display in the scale legend.
yMin number <optional>

The minimum scale value when coloring each cell.
yMax number <optional>

The maximum scale value when coloring each cell.
yAutoScale boolean <optional>

Whether or not to automatically scale new values.
legendAlign number <optional>

The alignment of the legend, as per PD.ALIGN.
decimals number <optional>

The number of decimal places to displayed values if yFormat not given.
yFormat function <optional>

A function taking a numeric value and returning a string for display.
onSelectionChanging function <optional>

A callback function triggered when the selection is about to change.
onSelectionChanged function <optional>

A callback function triggered when the selection has just changed.
Author:
  • drajmarsh
Throws:

Throws an error if provided with an invalid svgId element or id.

Type
Error

Members

:number

id

A unique identifier for this sun-path.

Type
  • number
:SVGElement

svgElem

The SVG element to render the chart to.

Type
  • SVGElement
:number

ASSIGNED_COLOR <static>

Defines a special value indicating that cells should be colored by their assigned color.

Type
  • number

Methods

_selectDaySlotByPointer(slot_index [, event])

Sets the selection state of the given slot over each week of the year.

The 12 slots in each week are used by EnergyPlus to assign profile data to addition day types, as shown in the following table.

SLOT DAY TYPE
0 MONDAY (Mon)
1 TUESDAY (Tue)
2 WEDNESDAY (Wed)
3 THURSDAY (Thu)
4 FRIDAY (Fri)
5 SATURDAY (Sat)
6 SUNDAY (Sun)
7 HOLIDAY (Hol)
8 SUMMER DESIGN DAY (Sdd)
9 WINTER DESIGN DAY (Wdd)
10 CUSTOM DAY 1 (Cd1)
11 CUSTOM DAY 2 (Cd2)
Parameters:
Name Type Argument Description
slot_index number

The slot within each week (0 to 11).
event Event <optional>

The event that triggered this selection.
Returns:

Returns true if the selection state of any cells changed, otherwise false.

Type
boolean

_setCellState(cell, state)

Sets the selection state of the given cell.

Parameters:
Name Type Description
cell object

The cell to set the state for.
state boolean

The new state to set.
Returns:

Returns true if the cell's state was changed, Otherwise false.

Type
boolean

anyDaysNotAssigned()

Returns a count of any days not assigned a valid profile.

A value of zero indicates that all days are properly assigned.

Returns:

Returns the number of days not assigned.

Type
number

assignToAll(value [, color])

Assigns the value and color to all current nodes.

Parameters:
Name Type Argument Description
value number

The new numeric value to store for the cell.
color string <optional>

An optional CSS color string. This is only used when the colorBy setting is set to -99.
Returns:

Returns this chart object to support method chaining

Type
object

assignToSelection(value [, color])

Assigns the value and color to all currently selected nodes.

Parameters:
Name Type Argument Description
value number

The new numeric value to store for the cell.
color string <optional>

An optional CSS color string. This is only used when the colorBy setting is set to -99.
Returns:

Returns this chart object to support method chaining

Type
object

autoScale( [fit])

Get/set whether or not to auto-fit the color scale.

Parameters:
Name Type Argument Description
fit boolean <optional>

When provided, this sets the new auto-fit state for the chart.
Returns:

Returns the current auto-fit state.

Type
boolean

colorBy( [color_by])

Get/set how the chart data is colored.

TODO: Document allowable values.

Parameters:
Name Type Argument Description
color_by string <optional>

When provided, this sets the new method to color the chart data.
Returns:

Returns the current chart data color method.

Type
string

colorScaleCallback( [callback])

Get/set the callback function used for the color scale.

Parameters:
Name Type Argument Description
callback function <optional>

When provided, this sets the new callback function.
Returns:

Returns the current callback function.

Type
function

dayOfTheWeek(dayOfYear)

Retrieves the numeric index of the day in the week (0:Monday to 6:Sunday).

This method follows ISO 8601 and considers Monday as the first day of the week and Sunday as the last. Thus, the day of the week index refers to Monday(0), Tuesday(1), Wednesday(2), Thursday(3), Friday(4), Saturday(5) and Sunday(6). This differs from the standard JavaScript Date.getDay() method which assumes the week starts on a Sunday.

Parameters:
Name Type Description
dayOfYear number

The index of the day within the year (0 to 364/365).
Returns:

Returns the day of the week index (0 to 6).

Type
number

gatDataHeight()

Get the current height of the actual chart data area.

Returns:

Returns the current chart data area height in pixels.

Type
number

getDataWidth()

Get the current width of the actual chart data area.

Returns:

Returns the current chart data area width in pixels.

Type
number

getDay(dayOfYear)

Retrieves the data for given day of the year.

Parameters:
Name Type Description
dayOfYear number

The required day of the year (0 to 364|365).
Returns:

Returns the stored data at the given cell, or null if an invalid day index is given.

Type
object | null

getDaysInYear()

Retrieves the total number of days in the current year (365 or 366).

Returns:

Returns the number of days in the year.

Type
object

getExportableText(inkscape_layers)

Converts the current SVG chart to text for exporting to a file.

This method adds an xml header and document type to the text as well as embedding styles.

Parameters:
Name Type Description
inkscape_layers boolean

Whether or not to convert id attributes to Inkscape layer data.
Returns:

Returns the SVG chart as a text string.

Type
string

getPreferredHeight( [width])

Calculate the preferred height of the chart data area to keep cells close to square.

Parameters:
Name Type Argument Description
width number <optional>

When provided, this is the width to use as a reference.
Returns:

Returns the current chart data area height in pixels.

Type
number

getWeek(weekIndex)

Retrieves an array of 12 indices for given week of the year.

The 12 slots in each week are used by EnergyPlus to assign profile data to addition day types, as shown in the following table.

SLOT DAY TYPE
0 MONDAY (Mon)
1 TUESDAY (Tue)
2 WEDNESDAY (Wed)
3 THURSDAY (Thu)
4 FRIDAY (Fri)
5 SATURDAY (Sat)
6 SUNDAY (Sun)
7 HOLIDAY (Hol)
8 SUMMER DESIGN DAY (Sdd)
9 WINTER DESIGN DAY (Wdd)
10 CUSTOM DAY 1 (Cd1)
11 CUSTOM DAY 2 (Cd2)
Parameters:
Name Type Description
weekIndex number

The required week of the year (0 to 53).
Returns:

Returns an array of 12 indices for that week, or null if an invalid .

Type
object | null

getWeekSlot(weekIndex, slotIndex)

Retrieves an array of 12 indices for given week of the year.

The slot index parameter refers to the 12 slots in each week are used by EnergyPlus to assign profile data to addition day types, as shown in the following table.

SLOT DAY TYPE
0 MONDAY (Mon)
1 TUESDAY (Tue)
2 WEDNESDAY (Wed)
3 THURSDAY (Thu)
4 FRIDAY (Fri)
5 SATURDAY (Sat)
6 SUNDAY (Sun)
7 HOLIDAY (Hol)
8 SUMMER DESIGN DAY (Sdd)
9 WINTER DESIGN DAY (Wdd)
10 CUSTOM DAY 1 (Cd1)
11 CUSTOM DAY 2 (Cd2)
Parameters:
Name Type Description
weekIndex number

The required week of the year (0 to 53).
slotIndex number

The slot within the given week (0 to 11).
Returns:

Returns the stored data at the given slot, or null if an invalid week or slot index is given.

Type
object | null

getWeeksArray(An)

Retrieves an annual array of 54 weeks by 12 profile indices.

The 12 slots in each week are used by EnergyPlus to assign profile data to addition day types, as shown in the following table.

SLOT DAY TYPE
0 MONDAY (Mon)
1 TUESDAY (Tue)
2 WEDNESDAY (Wed)
3 THURSDAY (Thu)
4 FRIDAY (Fri)
5 SATURDAY (Sat)
6 SUNDAY (Sun)
7 HOLIDAY (Hol)
8 SUMMER DESIGN DAY (Sdd)
9 WINTER DESIGN DAY (Wdd)
10 CUSTOM DAY 1 (Cd1)
11 CUSTOM DAY 2 (Cd2)
Parameters:
Name Type Description
An Array

optional array of 54 weeks by 12 slots;
Returns:

Returns an array of 54 weeks, where each week contains an array of 12 profile values.

Type
Array

height( [height])

Get/set the overall height of the chart, in pixels.

Parameters:
Name Type Argument Description
height number <optional>

When provided, this sets the new chart height in pixels.
Returns:

Returns the current chart height in pixels.

Type
number

hideTooltip()

Hides the tooltip above the selected node if it is visible.

Returns:

Returns this chart instance to support method chaining.

Type
object

paddingBottom( [pixels])

Get/set the inset on the bottom side of the chart.

Parameters:
Name Type Argument Description
pixels number <optional>

When provided, this sets the number of pixels the chart axis is indented from the parent container edge on the bottom side.
Returns:

Returns the current bottom padding in pixels.

Type
number

paddingLeft( [pixels])

Get/set the inset on the left side of the chart.

Parameters:
Name Type Argument Description
pixels number <optional>

When provided, this sets the number of pixels the chart axis is indented from the parent container edge on the left side.
Returns:

Returns the current left padding in pixels.

Type
number

paddingRight( [pixels])

Get/set the inset on the right side of the chart.

Parameters:
Name Type Argument Description
pixels number <optional>

When provided, this sets the number of pixels the chart axis is indented from the parent container edge on the right side.
Returns:

Returns the current right padding in pixels.

Type
number

paddingTop( [pixels])

Get/set the inset on the top side of the chart.

Parameters:
Name Type Argument Description
pixels number <optional>

When provided, this sets the number of pixels the chart axis is indented from the parent container edge on the top side.
Returns:

Returns the current top padding in pixels.

Type
number

refresh()

Regenerates the chart from scratch.

Returns:

Returns this chart instance to support method chaining.

Type
object

rescale( [instant])

Initiates a rescaling of the chart when it has changed size or shape.

The maximum frequency at which this method will actually rescale the chart is governed by the 'throttledRescale' property.

Parameters:
Name Type Argument Default Description
instant boolean <optional>
<nullable>
 false

Amn optional flag to make the rescale immediate even if debounced, defaults to false.
Returns:

Returns this chart instance to support method chaining.

Type
object

selectAction( [action])

Get/set the action to take when interactively selecting.

Parameters:
Name Type Argument Description
action number <optional>

When provided, specifies the action to take when selecting.
Returns:

Returns the current select action.

Type
number

selectDay(dayOfYear [, state])

Sets the selection state of the given day of the year.

Parameters:
Name Type Argument Description
dayOfYear number

The required day of the year (0 to 364|365).
state boolean <optional>

The new selection state, defaults to true.
Returns:

Returns true if the selection state of the given cell changed, otherwise false.

Type
boolean

selectDaysOfWeek(selectedIndexes)

Selects all specified days of the week for a given year

Slot numbers 0-6 correspond to the days of the week (Mon-Sun).

Parameters:
Name Type Description
selectedIndexes array

An array of slot indexes to be selected.
Returns:

Returns true if the selection state of any cells changed, otherwise false.

Type
boolean

selectMonth(monthOfYear [, state])

Sets the selection state of the given ordinal week of the year.

Parameters:
Name Type Argument Description
monthOfYear number

The month to select (0 to 11).
state boolean <optional>

The new selection state, defaults to current selection action.
Returns:

Returns true if the selection state of any cells changed, otherwise false.

Type
boolean

selectWeek(weekIndex [, state])

Sets the selection state of the given ordinal week of the year.

Parameters:
Name Type Argument Description
weekIndex number

The required week of the year (0 to 53).
state boolean <optional>

The new selection state, defaults to true.
Returns:

Returns true if the selection state of any cells changed, otherwise false.

Type
boolean

selectWeekSlot(weekIndex [, state])

Sets the selection state of the given ordinal week of the year.

Parameters:
Name Type Argument Description
weekIndex number

The required week of the year (0 to 53).
state boolean <optional>

The new selection state, defaults to true.
Returns:

Returns true if the selection state of any cells changed, otherwise false.

Type
boolean

set(config)

Sets one or more configuration values for the chart.

Parameters:
Name Type Description
config object

An object containing one or more configuration settings.
Returns:

Returns this chart instance to support method chaining.

Type
object

setDay(dayOfYear, value [, color])

Retrieves the data for given day of the year.

Parameters:
Name Type Argument Description
dayOfYear number

The required day of the year (0 to 364|365).
value number

The new numeric value to store for the cell.
color string <optional>

An optional CSS color string. This is only used when the colorBy setting is set to -99.
Returns:

Returns this chart object to support method chaining

Type
object

setStartDay(dayOfWeek)

Sets the day of the week that the year starts at.

Parameters:
Name Type Description
dayOfWeek number

The new start day of the week (0 to 6).

setWeekSlot(weekIndex, slotIndex, value [, color] [, select])

Retrieves the data for given day of the year.

The slot index parameter refers to the 12 slots in each week are used by EnergyPlus to assign profile data to addition day types, as shown in the following table.

SLOT DAY TYPE
0 MONDAY (Mon)
1 TUESDAY (Tue)
2 WEDNESDAY (Wed)
3 THURSDAY (Thu)
4 FRIDAY (Fri)
5 SATURDAY (Sat)
6 SUNDAY (Sun)
7 HOLIDAY (Hol)
8 SUMMER DESIGN DAY (Sdd)
9 WINTER DESIGN DAY (Wdd)
10 CUSTOM DAY 1 (Cd1)
11 CUSTOM DAY 2 (Cd2)
Parameters:
Name Type Argument Description
weekIndex number

The required week of the year (0 to 53).
slotIndex number

The slot within the given week (0 to 11).
value number

The new numeric value to store for the cell.
color string <optional>

An optional CSS color string. This is only used
select boolean <optional>

An optional flag to show slot as selected.
Returns:

Returns true of the value of the slot changed.

Type
boolean

show(state)

Shows or hides the chart based on given state.

Parameters:
Name Type Description
state boolean

Use true to show, false to hide.
Returns:

Returns this chart instance to support method chaining.

Type
object

subTitle( [subtitle])

Get/set the chart sub-title displayed in the header above the chart.

Parameters:
Name Type Argument Description
subtitle string <optional>

When provided, this sets the new sub-title for the chart.
Returns:

Returns the current chart sub-title.

Type
string

throttledRescale( [ms])

Get/set the timer value for throttling calls to the rescale() method.

This basically means that multiple calls to the rescale() method that occur within the specified number of milliseconds will be amalgamated to a single call that occurs at the end of that period.

Parameters:
Name Type Argument Description
ms number <optional>

When provided, this sets the throttling time, in milliseconds. Any value less than 5ms effectively turns off throttling.
Returns:

Returns the current throttling time in milliseconds.

Type
number

title( [title])

Get/set the chart title displayed in the header above the chart.

Parameters:
Name Type Argument Description
title string <optional>

When provided, this sets the new title for the chart.
Returns:

Returns the current chart title.

Type
string

titleSeparation( [fraction])

Get/set the fractional separation between title and subtitle.

Parameters:
Name Type Argument Description
fraction number <optional>

When provided, this sets the fractional separation between title and subtitle, where 0 means centered and 1 means edge aligned.
Returns:

Returns the current fractional separation.

Type
number

units( [units])

Get/set the chart units displayed in the header above the chart.

Parameters:
Name Type Argument Description
units string <optional>

When provided, this sets the new units for the chart.
Returns:

Returns the current chart units.

Type
string

update()

Updates values and colors.

Returns:

Returns this chart instance to support method chaining.

Type
object

updateScale()

Update value scale range.

Returns:

Returns this chart instance to support method chaining.g.

Type
object

updateSelection()

Update cell selection states.

Returns:

Returns this chart instance to support method chaining.

Type
object

weekOfTheYear(dayOfYear)

Retrieves the numeric index of the week in the year (0 to 53).

This method follows International Standard ISO 8601, where Monday is defined as the first day of the week followed by Tuesday, Wednesday, Thursday, Friday, Saturday, and with Sunday as the seventh day. Thus, if the year starts on a Saturday, there will only be two days in the first week and the following Monday is considered to be the start of the second week.

This means that there may be some years that have 53 weeks instead of 52, where there are less than 7 days in the first and last weeks of the year.

Parameters:
Name Type Description
dayOfYear number

The index of the day within the year (0 to 364/365).
Returns:

Returns the week index (0 to 53).

Type
number

width( [width])

Get/set the overall width of the chart.

Parameters:
Name Type Argument Description
width number <optional>

When provided, this sets the new chart width in pixels.
Returns:

Returns the current chart width in pixels.

Type
number