Using conditional attributes in PowerGadgets

[JuanC]

Conditional attributes is a feature that allows you to create charts where the color of the markers depend on a certain condition. In the first PowerGadgets  release build (1.0.2588) there are 2 different ways to setup these conditional attributes

Static
You can use this approach when you know in advance the ranges that should define the color of the markers, also this approach only works if the condition applies to the column/field being charted.

For example if you wanted a bar chart showing the number of handles opened by each process, and you want to show processes with more than 600 Handles in red, processes with opened handles between 400 and 600 yellow and all others green you could write something like this

ps | out-chart -values Handles -ConditionalAttributes_0_Condition_From 600 -ConditionalAttributes_0_Color Red -ConditionalAttributes_1_Condition_From 200 -ConditionalAttributes_1_Condition_To 600 -ConditionalAttributes_1_Color Yellow -Series_0_Color Green

Note that ConditionalAttributes is a collection so we can create as many conditions as needed but to specify the condition you can only specify From and To values. Also note that besides color you can change other point attributes such as PointLabels, Borders, MarkerShape, MarkerSize, etc.

An advantage of this approach is that you can set it up in a PGF or PGT using the PowerGadgets creator. If you are using PowerShell make sure you have our Tab Completion hooked up so that you can type -cond<TAB><TAB>_0_<TAB> and see all the properties you can modify.

Dynamic (ScriptBlock using Powershell)
Using this approach you can use the -condition parameter to specify a boolean piece of code you want to use as condition when coloring the markers. Note that you are free to use any existing property whether that is being charted or not, but you can only have 1 condition so you will end up with 2 sets of markers: the ones where your scriptblock evaluates to true will be applied any properties specified using the -condition_ attributes. The ones where your scriptblock evaluates to false will be untouched.

For example, if you wanted a bar chart showing the available hard drive space in your machine but you want to see disks where the available space is less than 50% of the total size in a different color, you could type

get-wmiobject -class Win32_LogicalDisk | out-chart -values FreeSpace -label DeviceID -condition {([double]$_.FreeSpace/$_.Size) -lt 0.5} -condition_Color LightGreen

Because FreeSpace and Size are both UINT64 we have to cast one of them to double so that the division is defined. If your are trying to write the right condition I would recommend you start doing something like get-wmiobject -class Win32_LogicalDisk | select FreeSpace,DeviceId,{([double]$_.FreeSpace/$_.Size) -lt 0.5}, not using out-chart but just selecting the fields and condition will give you the chance to make sure the condition actually works.

Note that although -condition_ allows you to set the same properties as the -ConditionalAttributes counterpart (MarkerSize, MarkerShape, etc.) you can only specify one condition (we do not support -condition_1_)

Combined

Feedback from some of our users showed that we need an approach where you can have the flexibility of writing your own condition using a scriptblock but you also need to specify multiple conditions. In build 2683 we implemented a new feature that supports this pattern. You specify as many conditionalattributes as you want but you do not have to set their conditions, only visual attributes such as color, markersize, etc. Then you make sure your scriptblock returns a number which we will use as an index for the condition you want to apply.

E.g. if you want a chart where available hard drive space is plotted, but disks where available space is less than 50% of the total size should be yellow and disks where available space is less than 10% of the total size should be red. Obviously because we have far passed the human limit for a one-liner, you would create a script with the following

$condition = {   $perc = [double] $_.FreeSpace / $_.Size;   if ($perc -lt 0.10) {   0;   } else {   if ($perc -lt 0.50) {   1;   } else {   2;   }   } } get-wmiobject -class Win32_LogicalDisk | out-chart -label DeviceID -values FreeSpace -conditionalattributes_0_color red -conditionalattributes_1_color yellow -conditionalattributes_2_color green -condition $condition -legendbox_visible false

To finish this chart we will add a legend explaining the colors, note that although you can assign a label to each conditional attribute, the chart will also show a label for the series. To hide the series items from the legend box we had to support a really strange syntax but it was the only way we could squeeze this change without affecting existing scripts

get-wmiobject -class Win32_LogicalDisk | out-chart -label DeviceID -values FreeSpace -conditionalattributes_0_color red -conditionalattributes_1_color yellow -conditionalattributes_2_color green -condition $condition -conditionalattributes_0_text "Less than 10%" -conditionalattributes_1_text "Less than 50%" -conditionalattributes_2_text "More than 50%" -legendbox_itemattributes_-series_visible false

Remember that in order to use the combined approach you need to install PowerGadgets build 2683 or later.

JuanC

[cosmin.onea]

this is a cool feature! great job!

one typo in the last script "-legendbox_itemattributes_-series_visible false"

Cosmin.

[marco.shaw]

Are scriptblocks supported with out-map also?

[marco.shaw]

Yes, it does appear out-map will also support scriptblocks. I should have checked the documentation before posting... out-map also has the '-condition' parameter.

[cosmin.onea]

-refresh param for out-chart cmdlet doesn't seem to work with this feature. Is it by design?

[DJake]

Will out-guage support scriptblocks as well?