devices - DaveL17/matplotlib GitHub Wiki

Presently, the plugin contains functionality for several charting devices including:

Charts:

Area
Bar - Vertical Flow
Bar - Vertical Stock
Bar - Horizontal Stock
Bar - Radial
Battery Health
Calendar
Line
Multiline Text
Matplotlib Parameters
Polar
Scatter
Weather Forecast

Your First Plot

Once you have some data to chart, it's time to create your first plot. Plots are built using Matplotlib Plugin Charting Devices, and each plot is managed by its own device instance. Create a new device and enter the configuration dialog. Most of these settings are available on multiple chart types and generally behave in the same way. For illustration, here are the settings for the line chart type.

Sample Device Configuration

Output Filename

Here, we just enter the full name of the chart--something like: chart_illumination.png. You shouldn't include a path, that is set in the main plugin configuration dialog.

Refresh Interval

How frequently the plugin will generate a new chart. Note that the default choice is marked with a star (this applies to most of the drop-down list items throughout the plugin). You are obviously free to pick something else, but this makes it easier to revert to the default should you want to do that.

Chart Controls

Use Size 2?

Sometimes, you might want the size of your chart to be different from the standard size (larger or smaller than the standard chart width specified in the plugin preferences). To force the chart to be drawn with Size 2, check this box (this size is set in the plugin preferences.)

Custom Size?

Sometimes, you might want a special size for your chart that doesn't conform to either the standard size or the extra wide size. Use these fields to specify a one-off size for this chart. If values are entered here, they will override all other size settings. If you later change your mind, set the value to 'None'. Note that if you leave the setting blank, the plugin will attempt to fix the setting for you. Also note that it is not necessary to set both values. You can choose to set only height or width and leave the other as None.

Custom Font Sizes?

It is sometimes necessary to make adjustments to your charts when they are going to be viewed on Retina and non-Retina displays. Fonts are especially sensitive to size depending on the target display. Setting a custom font size can help manage the difference. It is often best to create a chart device for your preferred display, duplicate it, and then adjust the font settings for the other display resolution.

Display Legend?

Check this box to include a legend in your chart. Note that if you also have X Axis labels (see below) the axis label will be suppressed when the legend is turned on (both would try to vie for the same real estate.)

Hide Anomalies?

This setting will cause certain values to be skipped when drawing the chart. This will not affect the underlying data in any way and only affects the chart drawing itself. Anomalies are considered to be values that are VAL standard deviations outside the "norm". Using this control can cause unexpected results. For example, some data sources may have very small variances across many observations (for example, the energy used by a motor that is always running). In these instances it is best to not use the hide anomalies setting.

Chart Title

Your chart title can be any valid string (including unicode characters). If you prefer not to have a title associated with your chart, leave the field blank. If you enter 'None', your chart will literally have None as its title.

Axis Controls

The axis controls area contains settings for the X and Y axes.

X Axis Controls

Controls that affect the horizontal X axis:

Display Grid?

The grid control specifies whether a vertical grid will be applied to the chart. If enabled, a vertical line will be charted at every major tick. Note that the style of grid line is established within the plugin preferences dialog.

Format

The format control specifies the format of the label that will be applied to the major tick marks along the X axis. Choose the label that makes the most sense for your particular case.

Label

The axis title control specifies the label that will be applied to the X axis. Note that if the chart's legend has been enabled (see above) the label entered here will be suppressed (both will fight for the same real estate).

Scale

The scale control specifies how often a major tick mark will be placed on your chart. For example, if you choose one tick per day (Every Day) a new tick mark will be placed at the start of a new day.

Axis Controls

Controls that affect the vertical Y axis:

Display Grid?

The grid control specifies whether a horizontal grid will be applied to the chart. If enabled, a horizontal line will be charted at every major tick. Note that the style of grid line is established within the plugin preferences dialog.

Label

The axis title control specifies the label that will be applied to the Y axis.

Min

The axis min control will limit the lower boundary of the Y axis. If None is specified, the plugin will manage the lower boundary automatically.

Max

The axis max control will limit the upper boundary of the Y axis. If None is specified, the plugin will manage the upper boundary automatically.

Mirror Axis?

If this setting is enabled, the left-side Y axis tick labels (the values) will be mirrored on the Y2 axis.

Precision

The precision control will affect the precision of the values placed along the Y axis.

Tick Labels

The tick labels setting will control the labels used for the tick marks on the Y axis. Whatever you enter here will be applied to the tick marks (in order, starting from the bottom). In order to use custom tick labels, you must also use custom tick locations. If you don't specify anything in the tick locations field, the custom tick labels field will be ignored.

Tick Locations

The tick locations setting will control the placement of the tick marks on the Y axis. For example, if you were charting wind direction, matplotlib might automatically place tick marks every 50 degrees. While accurate, it's not particularly helpful or visually appealing. Therefore, with this setting you could choose to only place tick marks at 0, 90, 180, 270, 360 degrees. The plugin will then only plot tick marks at these values. If you do not specify custom tick locations, matplotlib will do its best to place them for you.

Line Controls

The line controls area contains settings for the lines of your chart. Up to six lines can be added to a single chart. Each line control area contains the same settings.

Data Source

The data source control specifies the data to be charted. All valid CSV data elements contained within the data folder will be available in this list.

Adjustment Factor

The adjustment factor allows you to perform transformations on your data as they are plotted. For example, you might want to plot four binary sources on one chart. Adding an adjustment factor would allow you to shift line up or down by that factor. For example, one binary plot would be plotted on Y=0 and y=1 and the second could be plotted on Y=2 and Y=3 (by increasing all the observations by 2.) See the tutorials page for a step-by-step example and the sample charts page.

The following are examples of valid adjustment factors:

+ 1
* 2
* 2 + 1

Annotate?

Annotations will place the value of the data point as a label on the chart (for each observation).

[!CAUTION] Use this setting sparingly as too many annotations make for ugly charts.

Fill?

If enabled, the fill control will cause the area under the line to be filled with the same color as the line color (but with some transparency.)

Legend Label

Any text included here will be used as the legend label for this line. The field must be empty for the default label to be used. Entering a space here will cause no label to be displayed (technically, a space will be displayed).

Line Color

The line color dropdown list specifies the color that you would like for each line.

Line Style

The line style dropdown list specifies the type of line that you would like for each line.

Marker Color

If a marker is specified, this setting will control the color of the marker. Custom marker colors are supported.

Marker Style

If a marker is desired for each observation, select the style from the dropdown list.

Plot Min?

If enabled, the plot min control will put a horizontal line on the chart at the minimum value. Note that this will be the minimum value of the data reflected in the chart, and not necessarily the minimum value of the data contained within the CSV file.

Plot Max?

If enabled, the plot max control will put a horizontal line on the chart at the maximum value. Note that this will be the maximum value of the data reflected in the chart, and not necessarily the maximum value of the data contained within the CSV file.

Plot Best Fit?

If enabled, the plot best fit control will put a "horizontal" line on the chart that approximates the best fit for the data displayed. Use this control to identify a general trend in the data (i.e, generally increasing will show an upward-sloping line.)

Suppress Line?

When this box is ticked, the line will not be displayed in the plot. All settings will be retained, the line will merely be hidden from view.

Custom Line Segments

Custom line segments allow you to add extra lines to a chart. Custom line segments will not be available within the plugin until they have been enabled in the Advanced Settings dialog.

Constants

These line segments (if enabled) require value pairs: a value to chart (integer or float) and a color. The values must be entered as tuples and separated by commas when there is more than one. For example, an entry like this: (123.4, 'blue'), (234.5, 'green') will cause two horizontal lines to be added to your chart. Single segment entries must still be entered as a tuple (see image).

Substitutions

Later versions of the plugin added support for Indigo value substitutions within custom line segment settings. To use value substitutions, use the proper syntax in place of the context shown above. For example, the second line segment above could be re-written as (123.4, 'blue'), ('%%v:12345678%%', 'green') to use the value of an Indigo variable.

[!WARNING] There is not a lot of validation done by the plugin on these entries--you are generally responsible for entering them correctly. For more information on Indigo value substitutions, see the Indigo documentation.

Example:
On a weather forecast chart, you might want a line to denote a freeze threshold. Such a threshold could be done thusly: (32.0, 'blue') or (0.0, 'blue') (see 10-day Forecast sample image).

Style

Click on the line style dropdown list to specify the type of line that you would like for your custom line segment.

Area Charts

Area chart devices are like line charts, except the data points are charted with the values as cumulative.

Bar Chart (Vertical - Flow)

Bar chart devices of the flow variety are like line charts, except the data points are charted with typical bars. These chart types are typically better for plots with fewer observations. They are also good for plotting boolean values like on/off or open/closed. Use the flow chart with time-series data. For example, tracking the temperature of a single room over time.

Bar Chart (Vertical - Stock)

Stock bar charts are typically better for plots with fewer observations. They are also good for plotting boolean values like on/off or open/closed. Use the stock chart with distinct(single point in time) observations. For example, comparing the current temperatures of different rooms on one chart.

Bar Chart (Horizontal - Stock)

Horizontal stock bar charts are exactly the same as stock bar charts -- with the bars oriented horizontally. These charts are typically better for plots with fewer observations. They are also good for plotting boolean values like on/off or open/closed. Use the stock chart with distinct (single point in time) observations. For example, comparing the current temperatures of different rooms on one chart.

Bar Chart (Radial)

Radial Bar charts display one single data element in a radial bar. These charts are typically used to display a value as a function of another value. For example, setting the chart to a scale of 100 to display the dim level of a lamp, or a humidity value. Another example might be to show the current energy usage as a function of a determined maximum. There is no rule beyond the notion that the charted value is a flow value (observation) as a function of a stock value (scale). These are designed to be relatively small charts (say 100 pixels square), but there is no predetermined limit. See the tutorials page for more information.

View Full Size

Battery Health

Battery Health devices are linked directly to Indigo in that they will report the health of all battery-powered devices currently known. When you add a new battery-powered device to Indigo, the chart will be updated to include the new device automatically (you must have a configured Battery Health Device created in the plugin.) The color of the bars that represent each device can be controlled to display whether a device has reached a "caution" level, or a "warning" level based on the percentage of life remaining (there is a default setting of 10 and 5 percent respectively.)

View Full Size

Calendar Graphics

Calendar devices are used to create images that represent a typical calendar month for display on control pages. Later versions of the plugin include a feature that highlights the current day (see sample). To "disable" this feature, simply set the highlight color to the same color as the background color.

View Full Size

Line Charts

Line charts are one of the most basic of the chart types. They present data points with lines connecting each point. Line charts include a control that is not available with all charts--the ability to control for anomalous data points.

View Full Size
Sample - Anomalies Chart
Sample - Anomalies Hidden Chart

Matplotlib Parameters

The Matplotlib Parameters Device a special device type which is not used for generating charts. It is used as a repository that holds the initial matplotlibrc configuration settings so that you can see at a glance the initial parameters that the plugin uses before any customizations are applied. There are no settings or configurations for the Matplotlib Parameters device. You do not need to establish this device for the plugin to work. It is simply a way to inspect Matplotlib's initial settings.

Multiline Text

You can use the multiline text device to do precisely that--create a Matplotlib graphic that contains text spread across multiple lines.

View Full Size

Polar Charts

Polar charts are used to plot directional data like wind. The charts are capable of plotting both speed and direction on the same chart. An important thing to keep in mind is that the plugin is agnostic about the data you use with respect to its currency. That is, if you tell the plugin to use 10 values, it's going to use the 10 most recent values even if they don't necessarily match up. For example, if your last observation for wind speed is from an hour ago, and your last observation for wind direction is from last week, the plugin is not going to know. You're in charge of keeping your observations proximate.

View Full Size

Scatter Charts

Scatter charts are a lot like line charts, only there's no line connecting the various observations. This is a good chart type when there's not a direct relationship between two data points (or you don't care about the relationship between two data points). For example, scatter charts are good for plotting wind direction.

View Full Size

Weather Forecast Charts

• 10-Day Forecast Chart
  These charts are designed to work directly (and only) with Fantastic Weather Plugin and WUnderground Plugin 10-Day
• Forecast devices (see below).

• 24-Hour Forecast Chart
  These charts are designed to work directly (and only) with Fantastic Weather Plugin and WUnderground Plugin 24-Hour Forecast devices. There is an additional feature for the 24-Hour Forecast device to (optionally) display daylight hours. If enabled, the plot will include shaded areas for daylight hours.

View Full Size

Some fields require a valid value or the value 'None'. For example, a custom width value must either be a valid value in pixels or None. A blank will cause an error. If there's a problem, the plugin will try to fix the error for you. Other things can be blank -- like a title -- because entering 'None' will generate a title 'None'.

Weather Forecast Composite Charts

These charts are designed to work directly (and only) with Fantastic Weather Plugin and WUnderground Plugin daily and hourly forecast devices. The Weather Forecast Composite chart combines standard forecast elements into a single (composite) chart. Elements can be added or removed from the composite chart, and it will adjust its size to accommodate the changes. A special note about the wind vector arrows -- these reflect the direction the wind is blowing (not the direction the wind is coming from as is typical for wind data.)

Sample - Composite Forecast Chart

[!WARNING] Although the Matplotlib Plugin is currently designed to work with the Fantastic Weather Plugin and WUnderground Plugin Forecast devices, the WUnderground Plugin has been fully deprecated and support for the Fantastic Weather Plugin will be dropped in 2023 when Apple discontinues the weather API. Therefore, support for weather devices will be removed in a future version of the plugin.

[!WARNING] Note that any changes made to the settings for a particular charting device will not be reflected in your charts until the plugin refreshes them at the next refresh point. If you would like to see your changes reflected immediately, please select "Redraw Charts Now" from the plugin menu.