0
# Superset Legacy Rose Chart Plugin
1

2
A Nightingale Rose Diagram visualization plugin for Apache Superset that creates polar coordinate charts where data values are represented as sectors with varying radii. The chart displays data in a circular format with equal-angle wedges, making it ideal for showing categorical data with quantitative dimensions and temporal patterns.
3

4
## Package Information
5

6
- **Package Name**: @superset-ui/legacy-plugin-chart-rose
7
- **Package Type**: npm  
8
- **Language**: JavaScript (ES6+)
9
- **Installation**: This plugin is typically bundled with Apache Superset. For standalone use: `npm install @superset-ui/legacy-plugin-chart-rose`
10

11
## Core Imports
12

13
```javascript
14
import RoseChartPlugin from '@superset-ui/legacy-plugin-chart-rose';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const RoseChartPlugin = require('@superset-ui/legacy-plugin-chart-rose').default;
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { SuperChart } from '@superset-ui/core';
27
import RoseChartPlugin from '@superset-ui/legacy-plugin-chart-rose';
28

29
// Register the plugin with Superset
30
new RoseChartPlugin().configure({ key: 'rose' }).register();
31

32
// Use within Superset or with SuperChart
33
const roseChart = (
34
  <SuperChart
35
    chartType="rose"
36
    width={600}
37
    height={400}
38
    formData={{
39
      colorScheme: 'd3Category10',
40
      numberFormat: 'SMART_NUMBER',
41
      dateTimeFormat: 'smart_date',
42
      richTooltip: true,
43
      roseAreaProportion: false,
44
      sliceId: 1
45
    }}
46
    queriesData={[{
47
      data: {
48
        "1609459200000": [
49
          { key: ["Product A"], name: ["Product A"], time: 1609459200000, value: 100 },
50
          { key: ["Product B"], name: ["Product B"], time: 1609459200000, value: 75 }
51
        ],
52
        "1609545600000": [
53
          { key: ["Product A"], name: ["Product A"], time: 1609545600000, value: 120 },
54
          { key: ["Product B"], name: ["Product B"], time: 1609545600000, value: 90 }
55
        ]
56
      }
57
    }]}
58
  />
59
);
60
```
61

62
In Superset, the plugin is automatically registered and available as a "Nightingale Rose Chart" visualization type when creating new charts.
63

64
## Architecture
65

66
The rose chart plugin is built around several key components:
67

68
- **RoseChartPlugin**: Main plugin class that integrates with Superset's chart ecosystem
69
- **Rose Component**: Core D3.js-based visualization component that renders the actual chart
70
- **ReactRose Wrapper**: React component wrapper with styling and emotion integration
71
- **Control Panel**: Configuration interface for chart customization options
72
- **Transform Props**: Data transformation layer that converts Superset data format to chart props
73

74
## Capabilities
75

76
### Chart Plugin Registration
77

78
Main plugin class for registering the rose chart with Superset.
79

80
```javascript { .api }
81
export default class RoseChartPlugin extends ChartPlugin {
82
  constructor() {
83
    super({
84
      loadChart: () => import('./ReactRose'),
85
      metadata: ChartMetadata,
86
      transformProps: transformProps,
87
      controlPanel: controlPanel,
88
    });
89
  }
90
}
91

92
class ChartPlugin {
93
  configure(config) { /* inherited method */ }
94
  register() { /* inherited method */ }
95
}
96
```
97

98
The plugin automatically configures chart metadata:
99
- **Category**: "Ranking"
100
- **Name**: "Nightingale Rose Chart"  
101
- **Description**: "A polar coordinate chart where the circle is broken into wedges of equal angle"
102
- **Tags**: Legacy, Advanced-Analytics, Circular, Multi-Layers, Pattern, Time, Trend
103
- **Legacy API**: Uses legacy Superset API (useLegacyApi: true)
104
- **Example Gallery**: Includes thumbnail and example images
105

106
### Chart Rendering
107

108
Core visualization component that renders the rose diagram using D3.js.
109

110
```javascript { .api }
111
function Rose(element, props) {
112
  // D3.js-based chart rendering function
113
}
114

115
// PropTypes validation
116
Rose.propTypes = {
117
  data: PropTypes.objectOf(
118
    PropTypes.arrayOf(
119
      PropTypes.shape({
120
        key: PropTypes.arrayOf(PropTypes.string),
121
        name: PropTypes.arrayOf(PropTypes.string), 
122
        time: PropTypes.number,
123
        value: PropTypes.number,
124
      }),
125
    ),
126
  ),
127
  width: PropTypes.number,
128
  height: PropTypes.number,
129
  colorScheme: PropTypes.string,
130
  dateTimeFormat: PropTypes.string,
131
  numberFormat: PropTypes.string,
132
  useRichTooltip: PropTypes.bool,
133
  useAreaProportions: PropTypes.bool,
134
  sliceId: PropTypes.number,
135
};
136

137
// Data structure
138
const RoseData = {
139
  "1609459200000": [
140
    {
141
      key: ["Category A"],
142
      name: ["Category A"], 
143
      time: 1609459200000,
144
      value: 100
145
    }
146
  ]
147
};
148
```
149

150
The Rose component creates an interactive polar coordinate chart with the following features:
151
- Circular layout with equal-angle time segments
152
- Radial encoding of values (area or radius based)
153
- Interactive hover effects with tooltips
154
- Click interactions for drilling down into time segments
155
- Legend with toggle functionality for series visibility
156
- Animated transitions between states
157

158
### React Integration
159

160
React wrapper component with styling and theming support.
161

162
```javascript { .api }
163
const ReactRose = ({ className, ...otherProps }) => (
164
  <div className={className}>
165
    <Global styles={theme => css`/* tooltip styles */`} />
166
    <ReactComponent {...otherProps} />
167
  </div>
168
);
169

170
export default styled(ReactRose)`/* chart styles */`;
171

172
// Component props (passed to ReactComponent)
173
const reactRoseProps = {
174
  className: String, // optional
175
  width: Number,
176
  height: Number, 
177
  data: Object, // RoseData format
178
  colorScheme: String,
179
  dateTimeFormat: String,
180
  numberFormat: String,
181
  useRichTooltip: Boolean,
182
  useAreaProportions: Boolean,
183
  sliceId: Number,
184
};
185
```
186

187
The ReactRose component provides:
188
- Global CSS styling through emotion
189
- Theme integration for consistent appearance
190
- Responsive design support
191
- Tooltip styling and positioning
192

193
### Data Transformation
194

195
Transforms chart properties from Superset format to component props.
196

197
```javascript { .api }
198
export default function transformProps(chartProps) {
199
  const { width, height, formData, queriesData } = chartProps;
200
  const {
201
    colorScheme,
202
    dateTimeFormat,
203
    numberFormat,
204
    richTooltip,
205
    roseAreaProportion,
206
    sliceId,
207
  } = formData;
208

209
  return {
210
    width,
211
    height,
212
    data: queriesData[0].data,
213
    colorScheme,
214
    dateTimeFormat,
215
    numberFormat,
216
    useAreaProportions: roseAreaProportion,
217
    useRichTooltip: richTooltip,
218
    sliceId,
219
  };
220
}
221

222
// Input structure
223
const SupersetChartProps = {
224
  width: Number,
225
  height: Number,
226
  formData: {
227
    colorScheme: String,
228
    dateTimeFormat: String,
229
    numberFormat: String,
230
    richTooltip: Boolean,
231
    roseAreaProportion: Boolean,
232
    sliceId: Number,
233
  },
234
  queriesData: [{
235
    data: Object // RoseData format
236
  }]
237
};
238
```
239

240
### Control Panel Configuration
241

242
Configuration object defining available chart options and controls.
243

244
```javascript { .api }
245
const config = {
246
  controlPanelSections: [
247
    sections.legacyTimeseriesTime,
248
    {
249
      label: 'Query',
250
      expanded: true,
251
      controlSetRows: [
252
        ['metrics'],
253
        ['adhoc_filters'],
254
        ['groupby'],
255
        ['limit', 'timeseries_limit_metric'],
256
        ['order_desc'],
257
        [{
258
          name: 'contribution',
259
          config: {
260
            type: 'CheckboxControl',
261
            label: 'Contribution',
262
            default: false,
263
            description: 'Compute the contribution to the total',
264
          },
265
        }],
266
        ['row_limit', null],
267
      ],
268
    },
269
    {
270
      label: 'Chart Options',
271
      expanded: true,
272
      controlSetRows: [
273
        ['color_scheme'],
274
        [
275
          {
276
            name: 'number_format',
277
            config: {
278
              type: 'SelectControl',
279
              freeForm: true,
280
              label: 'Number format',
281
              renderTrigger: true,
282
              default: 'SMART_NUMBER',
283
              choices: D3_FORMAT_OPTIONS,
284
              description: D3_FORMAT_DOCS,
285
            },
286
          },
287
          {
288
            name: 'date_time_format',
289
            config: {
290
              type: 'SelectControl',
291
              freeForm: true,
292
              label: 'Date Time Format',
293
              renderTrigger: true,
294
              default: 'smart_date',
295
              choices: D3_TIME_FORMAT_OPTIONS,
296
              description: D3_FORMAT_DOCS,
297
            },
298
          },
299
        ],
300
        [
301
          {
302
            name: 'rich_tooltip',
303
            config: {
304
              type: 'CheckboxControl',
305
              label: 'Rich Tooltip',
306
              renderTrigger: true,
307
              default: true,
308
              description: 'The rich tooltip shows a list of all series for that point in time',
309
            },
310
          },
311
          {
312
            name: 'rose_area_proportion',
313
            config: {
314
              type: 'CheckboxControl',
315
              label: 'Use Area Proportions',
316
              description: 'Check if the Rose Chart should use segment area instead of segment radius for proportioning',
317
              default: false,
318
              renderTrigger: true,
319
            },
320
          },
321
        ],
322
      ],
323
    },
324
    // Advanced Analytics section with rolling window, time comparison, resample options
325
  ],
326
  formDataOverrides: formData => ({
327
    ...formData,
328
    groupby: getStandardizedControls().popAllColumns(),
329
    metrics: getStandardizedControls().popAllMetrics(),
330
  }),
331
};
332
```
333

334
The control panel provides:
335
- Time series configuration (legacy format)
336
- Query options (metrics, filters, groupby, limits)
337
- Chart customization (color scheme, formatting)
338
- Tooltip configuration options
339
- Area vs radius proportion toggle
340
- Advanced analytics (rolling windows, time comparison, resampling)
341

342
## Chart Features
343

344
### Visual Encoding Options
345

346
- **Area Proportions**: When enabled, uses segment area for value encoding instead of radius
347
- **Rich Tooltips**: Shows all series data for a time point vs single series
348
- **Color Schemes**: Supports Superset's categorical color schemes
349
- **Number/Date Formatting**: Configurable display formats using D3 format specifications
350

351
### Interactions
352

353
- **Hover Effects**: Segments expand on hover with smooth transitions
354
- **Click Navigation**: Click segments to drill down into time-specific pie chart view
355
- **Legend Toggle**: Click legend items to show/hide data series
356
- **Animated Transitions**: Smooth animations between chart states
357

358
### Data Requirements
359

360
- **Time Series Data**: Data must be grouped by timestamp keys
361
- **Value Structure**: Each data point requires key, name, time, and value fields
362
- **Multiple Series**: Supports multiple data series per time period
363
- **Sorting**: Data is automatically sorted by value within each time period
364

365
## Dependencies
366

367
### Peer Dependencies
368

369
```javascript { .api }
370
// Required peer dependencies that must be installed separately
371
"@emotion/react": "^11.4.1"
372
"@superset-ui/chart-controls": "*"
373
"@superset-ui/core": "*"  
374
"react": "^16.13.1"
375
```
376

377
### Direct Dependencies
378

379
```javascript { .api }
380
// Automatically installed dependencies
381
"d3": "^3.5.17"           // D3.js visualization library (legacy version)
382
"nvd3-fork": "^2.0.5"     // NVD3 charting components fork
383
"prop-types": "^15.6.2"   // React prop validation
384
```
385

386
## Error Handling
387

388
The component handles various error conditions:
389
- Missing or malformed data gracefully degrades
390
- Invalid date/number formats fall back to defaults
391
- Rendering errors are contained within the chart component
392
- Tooltip positioning adjusts to viewport boundaries
393

394
## Performance Considerations
395

396
- Lazy loading of chart component through dynamic imports
397
- Efficient D3 data binding and updates
398
- Optimized transition animations
399
- Memory cleanup on component unmount
400
- Responsive design with configurable dimensions