Skip to content

Commit 3305981

Browse files
Macman1234aestoltm
Macman1234
and
aestoltm
authored
Updated summary charts howto, added color palette howto. (#1818)
* Updated documentation for customizing Summary charts * Added documentation for customizing the color palette --------- Co-authored-by: Andrew Stoltman <[email protected]>
1 parent 088611c commit 3305981

File tree

3 files changed

+158
-50
lines changed

3 files changed

+158
-50
lines changed

‎docs/howto-colors.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: HOWTO Change Metric Explorer Colors
3+
---
4+
5+
The color palette available to style chart data in Metric Explorer can be edited
6+
in the JSON file `colors1.json` (`/etc/xdmod/colors1.json` if you installed the RPM or
7+
`PREFIX/etc/colors1.json` if you did a manual install).
8+
9+
The default version of `colors1.json` (and what is used as a fallback palette if `colors1.json`
10+
is missing or malformed) is shown below
11+
12+
```json
13+
[
14+
[
15+
["FFFFFF"], ["1199FF"], ["DB4230"], ["4E665D"], ["F4A221"], ["66FF00"], ["33ABAB"], ["A88D95"],
16+
["789ABC"], ["FF99CC"], ["00CCFF"], ["FFBC71"], ["A57E81"], ["8D4DFF"], ["FF6666"], ["CC99FF"],
17+
["2F7ED8"], ["0D233A"], ["8BBC21"], ["910000"], ["1AADCE"], ["492970"], ["F28F43"], ["77A1E5"],
18+
["3366FF"], ["FF6600"], ["808000"], ["CC99FF"], ["008080"], ["CC6600"], ["9999FF"], ["99FF99"],
19+
["969696"], ["FF00FF"], ["FFCC00"], ["666699"], ["00FFFF"], ["00CCFF"], ["993366"], ["3AAAAA"],
20+
["C0C0C0"], ["FF99CC"], ["FFCC99"], ["CCFFCC"], ["CCFFFF"], ["99CCFF"], ["339966"], ["FF9966"],
21+
["69BBED"], ["33FF33"], ["6666FF"], ["FF66FF"], ["99ABAB"], ["AB8722"], ["AB6565"], ["990099"],
22+
["999900"], ["CC3300"], ["669999"], ["993333"], ["339966"], ["C42525"], ["A6C96A"], ["111111"]
23+
]
24+
]
25+
```
26+
27+
To change the colors available, simply edit the hexadecimal codes for any of the swatches in the palette.
28+
To add a new color or set of colors, make sure to keep the JSON array rectangular with the same width.
29+
30+
As an example, to add the colors `123456` and `654321` you'd need to pad the table with other colors.
31+
In this case, they're padded with white, which Open XDMoD skips when showing charts.
32+
33+
```json
34+
[
35+
[
36+
["FFFFFF"], ["1199FF"], ["DB4230"], ["4E665D"], ["F4A221"], ["66FF00"], ["33ABAB"], ["A88D95"],
37+
["789ABC"], ["FF99CC"], ["00CCFF"], ["FFBC71"], ["A57E81"], ["8D4DFF"], ["FF6666"], ["CC99FF"],
38+
["2F7ED8"], ["0D233A"], ["8BBC21"], ["910000"], ["1AADCE"], ["492970"], ["F28F43"], ["77A1E5"],
39+
["3366FF"], ["FF6600"], ["808000"], ["CC99FF"], ["008080"], ["CC6600"], ["9999FF"], ["99FF99"],
40+
["969696"], ["FF00FF"], ["FFCC00"], ["666699"], ["00FFFF"], ["00CCFF"], ["993366"], ["3AAAAA"],
41+
["C0C0C0"], ["FF99CC"], ["FFCC99"], ["CCFFCC"], ["CCFFFF"], ["99CCFF"], ["339966"], ["FF9966"],
42+
["69BBED"], ["33FF33"], ["6666FF"], ["FF66FF"], ["99ABAB"], ["AB8722"], ["AB6565"], ["990099"],
43+
["999900"], ["CC3300"], ["669999"], ["993333"], ["339966"], ["C42525"], ["A6C96A"], ["111111"],
44+
["123456"], ["654321"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"]
45+
]
46+
]
47+
```
48+
49+
Charts in Open XDMoD will go sequentially through this list when deciding what colors to color grouped sets within
50+
one dataset on a chart. As such, you can create a gradient by defining it sequentially in this list. The
51+
following JSON list adds a 8-element "snapshot" of [the Viridis color gradient](https://bids.github.io/colormap/).
52+
53+
```json
54+
[
55+
[
56+
["FFFFFF"], ["1199FF"], ["DB4230"], ["4E665D"], ["F4A221"], ["66FF00"], ["33ABAB"], ["A88D95"],
57+
["789ABC"], ["FF99CC"], ["00CCFF"], ["FFBC71"], ["A57E81"], ["8D4DFF"], ["FF6666"], ["CC99FF"],
58+
["2F7ED8"], ["0D233A"], ["8BBC21"], ["910000"], ["1AADCE"], ["492970"], ["F28F43"], ["77A1E5"],
59+
["3366FF"], ["FF6600"], ["808000"], ["CC99FF"], ["008080"], ["CC6600"], ["9999FF"], ["99FF99"],
60+
["969696"], ["FF00FF"], ["FFCC00"], ["666699"], ["00FFFF"], ["00CCFF"], ["993366"], ["3AAAAA"],
61+
["C0C0C0"], ["FF99CC"], ["FFCC99"], ["CCFFCC"], ["CCFFFF"], ["99CCFF"], ["339966"], ["FF9966"],
62+
["69BBED"], ["33FF33"], ["6666FF"], ["FF66FF"], ["99ABAB"], ["AB8722"], ["AB6565"], ["990099"],
63+
["FDE725"], ["A0DA39"], ["4AC16D"], ["1FA187"], ["277F8E"], ["365C8D"], ["46327E"], ["440154"]
64+
]
65+
]
66+
```
67+
68+
Open XDMOD indexes the colors based on the first instance of the color found in that list,
69+
so any duplicate colors may wreck havoc on group-by coloring.
70+
As an example, selecting the first `123456` in the following
71+
palette would cause the next two groups in that dataset to be colored `AABBCC` and `CCBBAA`.
72+
Selecting the second `123456` in the palette would result in the next two groups *still* being colored `AABBCC` and `CCBBAA`.
73+
74+
```json
75+
[
76+
[
77+
["123456"], ["AABBCC"], ["CCBBAA"], ["123456"], ["111111"], ["222222"], ["333333"], ["444444"]
78+
]
79+
]
80+
```
81+
82+
The palette below shows a workaround for this problem in order to add both an 8-element and 10-element Viridis gradient.
83+
This is done by nudging the starting point over by a value of 1 in any of the 3 RGB channels. In this example, the starting point of the
84+
8-element gradient is `FDE725`, and the starting point of the 10-element gradient is `FDE726`.
85+
86+
```json
87+
[
88+
[
89+
["FFFFFF"], ["1199FF"], ["DB4230"], ["4E665D"], ["F4A221"], ["66FF00"], ["33ABAB"], ["A88D95"],
90+
["789ABC"], ["FF99CC"], ["00CCFF"], ["FFBC71"], ["A57E81"], ["8D4DFF"], ["FF6666"], ["CC99FF"],
91+
["2F7ED8"], ["0D233A"], ["8BBC21"], ["910000"], ["1AADCE"], ["492970"], ["F28F43"], ["77A1E5"],
92+
["3366FF"], ["FF6600"], ["808000"], ["CC99FF"], ["008080"], ["CC6600"], ["9999FF"], ["99FF99"],
93+
["969696"], ["FF00FF"], ["FFCC00"], ["666699"], ["00FFFF"], ["00CCFF"], ["993366"], ["3AAAAA"],
94+
["C0C0C0"], ["FF99CC"], ["FFCC99"], ["CCFFCC"], ["CCFFFF"], ["99CCFF"], ["339966"], ["FF9966"],
95+
["69BBED"], ["33FF33"], ["6666FF"], ["FF66FF"], ["99ABAB"], ["AB8722"], ["AB6565"], ["990099"],
96+
["FDE725"], ["A0DA39"], ["4AC16D"], ["1FA187"], ["277F8E"], ["365C8D"], ["46327E"], ["440154"],
97+
["FDE726"], ["B5DE2B"], ["6ECE58"], ["35B779"], ["1F9E89"], ["26828e"], ["31688E"], ["3E4989"],
98+
["482878"], ["440155"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"], ["FFFFFF"]
99+
]
100+
]
101+
```

‎docs/howto-summary-charts.md

Lines changed: 54 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,72 +2,78 @@
22
title: HOWTO Change Summary Page Charts
33
---
44

5-
To change the default charts for all users you need to update the
6-
`roles.json` file (`/etc/xdmod/roles.json` if you installed the RPM or
7-
`PREFIX/etc/roles.json` if you did a manual install) and change the JSON
8-
for the charts. Since it is not obvious how to do this, I suggest
9-
looking at the JSON created from the Metric Explorer for the changes you
10-
need to make in `roles.json`.
5+
If a user wants to add a chart to their personal Summary tab, they can use Metric Explorer to create a chart,
6+
then open the "Chart Options" context menu by left clicking in the chart, then check the "Show in Summary
7+
tab" checkbox.
118

12-
First, log into the portal and create the desired charts using the
13-
Metric Explorer. You can add this chart to the summary page, but only
14-
for that user, by checking "Show in Summary Tab".
9+
To change the charts that appear in users' Summary tabs by default, you'll need to create
10+
a chart and add its JSON definition to the XDMoD configuration files.
1511

16-
After saving the chart, select from the table `UserProfiles` in the
17-
database `moddb`.
12+
The easiest way to create a JSON definition for a chart is interactively,
13+
using Metric Explorer's JSON export function:
1814

19-
mysql> SELECT * FROM moddb.UserProfiles;
15+
* Login to Open XDMoD with a user account that has the "Developer" role.
16+
* Create a chart in the Metric Explorer.
17+
* Open the "Chart Options" context menu by left clicking in the chart.
18+
* Select the "View chart json" menu item.
2019

21-
This will show the user profile data for all users including the chart
22-
JSON serialized by PHP. If you are unsure of your `user_id`, check the
23-
`Users` table.
20+
Default summary charts are defined as lists of charts within the configuration files for user roles.
21+
These are located in two different sets of locations: in the top level `roles.json` file
22+
(`/etc/xdmod/roles.json` if you installed the RPM or `PREFIX/etc/roles.json` if you did a manual install),
23+
and in any `.json` files located in `roles.d` (`/etc/xdmod/roles.d/` or `PREFIX/xdmod/roles.d/` respectively).
2424

25-
mysql> SELECT id, username FROM moddb.Users;
25+
The base summary charts (the ones included with a install of Open XDMoD) are included implicity
26+
for any user role if the field `summary_charts` is absent for that role in both `roles.json` and
27+
in `roles.d`. If `summary_charts` contains any charts, those override displaying any of the summary charts.
2628

27-
Next you'll need to deserialize the data then examine the JSON. Copy
28-
this code into a file and run it with the data from your user profile:
29+
By default, in an out-of-the-box XDMoD configuration:
2930

30-
```php
31-
<?php
32-
$data = 'a:1:{....'; // Copy your data into this variable.
33-
$profile = unserialize($data);
34-
$queries = json_decode($profile['queries'], true);
35-
foreach ($queries as $name => $query) {
36-
echo $name, ":\n";
37-
echo $query['config'], "\n\n";
38-
}
39-
```
31+
* The role "pub" - which is applied to any users who are not logged in - has no `summary_charts` field and so implictly uses the base summary charts.
32+
* The role "default" - which all other user roles inherit - has an empty `summary_charts` field in `roles.json`, but
33+
has explicitly defined summary charts appended in `roles.d/jobs.json` that are equivalent to the base summary charts.
4034

41-
This will output the JSON for each chart saved for the user the data was
42-
copied from. Find the chart that you want to add to the default summary
43-
page and copy it into `summary_charts` section of `roles.json`. Add the
44-
JSON object list after the name of the chart.
35+
The recommended method to define new summary charts is to create a new `.json` file in `roles.d` that specifically handles
36+
any summary chart customization, rather than using the existing `.json` files. If you'd like to keep the default charts along with
37+
any newly created charts, it's recommended to move the ones included with `roles.d/jobs.json` and any other files that contain `+summary_charts`,
38+
to your newly created `.json` file, deleting them from their original files.
39+
40+
As an example, if you wanted to add a default chart for the "default" role,
41+
you would edit your summary chart customization `.json` file in `roles.d`.
42+
In the example below, you'd replace the `...`
43+
in the `+summary_charts` list with the JSON you copied.
4544

4645
```json
47-
"summary_charts": [
48-
{
49-
...
50-
},
51-
{
46+
{
47+
"+roles": {
48+
"+default": {
49+
...
50+
"+summary_charts": [
51+
...
52+
]
53+
}
5254
...
53-
},
54-
...
55-
]
55+
}
56+
}
57+
5658
```
5759

58-
You should also add a title to JSON for the chart that will be displayed
59-
on the summary page.
60+
This would only change the summary charts for logged-in users - if you wanted to make this same change for non-logged-in users,
61+
you would have to do the same do the same for the role "pub", rather than just for "default".
62+
63+
There's a known issue displaying charts with no `global_filters` field
64+
in the Summary page. If the chart you're adding has no global filters,
65+
add an empty `global_filters` field as shown below
66+
(see the premade ones in `roles.d/jobs.json` for more examples).
6067

6168
```json
62-
"summary_charts": [
69+
"+summary_charts": [
6370
{
64-
"title": "Chart Title",
71+
"global_filters": {
72+
"data": [],
73+
"total": 0
74+
},
6575
...
6676
},
6777
...
6878
]
6979
```
70-
71-
Note that it is possible to have a different set of charts for different
72-
roles, but the default configuration uses a single set of charts for all
73-
roles.

‎docs/howto.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ title: HOWTOs
44

55
The Open XDMoD HOWTOs are "how to" documents on specific subjects.
66

7-
- [Change Default Summary Page Charts](howto-summary-charts.html)
7+
- [Change Summary Page Charts](howto-summary-charts.html)
8+
- [Change Metric Explorer Colors](howto-colors.html)
89
- [Enable Node Utilization Statistics](howto-node-utilization.html)
9-
- [Reconstruct Slurm accounting logs](howto-reconstruct-slurm.html)
10+
- [Reconstruct Slurm Accounting Logs](howto-reconstruct-slurm.html)

0 commit comments

Comments
 (0)