Pie title

src/traces/pie/attributes.js

@@ -180,6 +180,33 @@ module.exports = {
         description: 'Sets the font used for `textinfo` lying outside the pie.'
     }),
 
+    title: {
+        valType: 'string',
+        dflt: '',
+        role: 'info',
+        editType: 'calc',
+        description: [
+            'Sets the title of the pie chart.',
+            'If it is empty, no title is displayed.'
+        ].join(' ')
+    },
+    titleposition: {
+        valType: 'enumerated',
+        values: ['inhole', 'outside'],
+        dflt: 'outside',
+        role: 'info',
+        editType: 'calc',
+        description: [
+            'Specifies the location of the `title`.',
+            'If `inhole` and the chart is a donut, the text is scaled',
+            'and displayed inside the hole.',
+            'If `outside`, the text is shown above the pie chart.'
+        ].join(' ')
+    },
+    titlefont: extendFlat({}, textFontAttrs, {
+        description: 'Sets the font used for `title`.'
+    }),
+
     // position and shape
     domain: domainAttrs({name: 'pie', trace: true, editType: 'calc'}),
 

src/traces/pie/defaults.js

@@ -65,6 +65,15 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         }
     }
 
+    var title = coerce('title');
+    if(title) {
+        var titlePosition = coerce('titleposition');
+
+        if(titlePosition === 'inhole' || titlePosition === 'outside') {
+            coerceFont(coerce, 'titlefont', layout.font);
+        }
+    }
+
     handleDomainDefaults(traceOut, layout, coerce);
 
     coerce('hole');

src/traces/pie/plot.js

@@ -308,6 +308,53 @@ module.exports = function plot(gd, cdpie) {
                 });
             });
 
+            // add the title
+            var hasTitle = trace.title &&
+                ((trace.titleposition === 'inhole' && trace.hole > 0) ||
+                 (trace.titleposition === 'outside'));
+            var titleTextGroup = d3.select(this).selectAll('g.titletext')
+                .data(hasTitle ? [0] : []);
+
+            titleTextGroup.enter().append('g')
+                .classed('titletext', true);
+            titleTextGroup.exit().remove();
+
+            titleTextGroup.each(function() {
+                var titleText = Lib.ensureSingle(d3.select(this), 'text', '', function(s) {
+                    // prohibit tex interpretation as above
+                    s.attr('data-notex', 1);
+                });
+
+                titleText.text(trace.title)
+                    .attr({
+                        'class': 'titletext',
+                        transform: '',
+                        'text-anchor': 'middle'
+                    })
+                .call(Drawing.font, trace.titlefont)
+                .call(svgTextUtils.convertToTspans, gd);
+
+
+                var titleBB = Drawing.bBox(titleText.node());
+                // translation and scaling for the title text box.
+                // The translation is for the center point.
+                var transform;
+
+                if(trace.titleposition === 'outside') {
+                    transform = positionTitleOutside(titleBB, cd0, fullLayout._size);
+                } else {
+                    transform = positionTitleInside(titleBB, cd0);
+                }
+
+                titleText.attr('transform',
+                    'translate(' + transform.x + ',' + transform.y + ')' +
+                    (transform.scale < 1 ? ('scale(' + transform.scale + ')') : '') +
+                    'translate(' +
+                            (-(titleBB.left + titleBB.right) / 2) + ',' +
+                            (-(titleBB.top + titleBB.bottom) / 2) +
+                        ')');
+            });
+
             // now make sure no labels overlap (at least within one pie)
             if(hasOutsideText) scootLabels(quadrants, trace);
             slices.each(function(pt) {
@@ -454,6 +501,72 @@ function transformOutsideText(textBB, pt) {
     };
 }
 
+function positionTitleInside(titleBB, cd0) {
+    var textDiameter = Math.sqrt(titleBB.width * titleBB.width + titleBB.height * titleBB.height);
+    return {
+        x: cd0.cx,
+        y: cd0.cy,
+        scale: cd0.trace.hole * cd0.r * 2 / textDiameter
+    };
+}
+
+function positionTitleOutside(titleBB, cd0, plotSize) {
+    var scaleX, scaleY, chartWidth, titleSpace, titleShift, maxPull;
+    var trace = cd0.trace;
+
+    maxPull = getMaxPull(trace);
+    chartWidth = plotSize.w * (trace.domain.x[1] - trace.domain.x[0]);
+    scaleX = chartWidth / titleBB.width;
+    if(isSinglePie(trace)) {
+        titleShift = trace.titlefont.size / 2;
+        // we need to leave enough free space for an outside label
+        if(trace.outsidetextfont) titleShift += 3 * trace.outsidetextfont.size / 2;
+        else titleShift += trace.titlefont.size / 4;
+        return {
+            x: cd0.cx,
+            y: cd0.cy - (1 + maxPull) * cd0.r - titleShift,
+            scale: scaleX
+        };
+    }
+    titleSpace = getTitleSpace(trace, plotSize);
+    // we previously left a free space of height titleSpace.
+    // The text must fit in this space.
+    scaleY = titleSpace / titleBB.height;
+    return {
+        x: cd0.cx,
+        y: cd0.cy - (1 + maxPull) * cd0.r - (titleSpace / 2),
+        scale: Math.min(scaleX, scaleY)
+    };
+}
+
+function isSinglePie(trace) {
+    // check if there is a single pie per y-column
+    if(trace.domain.y[0] === 0 && trace.domain.y[1] === 1) return true;
+    return false;
+}
+
+function getTitleSpace(trace, plotSize) {
+    var chartHeight = plotSize.h * (trace.domain.y[1] - trace.domain.y[0]);
+    // leave 3/2 * titlefont.size free space. We need at least titlefont.size
+    // space, and the 1/2 * titlefont.size is a small buffer to avoid the text
+    // touching the pie.
+    var titleSpace = (trace.title && trace.titleposition === 'outside') ?
+        (3 * trace.titlefont.size / 2) : 0;
+    if(chartHeight > titleSpace) return titleSpace;
+    else return chartHeight / 2;
+}
+
+function getMaxPull(trace) {
+    var maxPull = trace.pull, j;
+    if(Array.isArray(maxPull)) {
+        maxPull = 0;
+        for(j = 0; j < trace.pull.length; j++) {
+            if(trace.pull[j] > maxPull) maxPull = trace.pull[j];
+        }
+    }
+    return maxPull;
+}
+
 function scootLabels(quadrants, trace) {
     var xHalf, yHalf, equatorFirst, farthestX, farthestY,
         xDiffSign, yDiffSign, thisQuad, oppositeQuad,
@@ -570,21 +683,18 @@ function scalePies(cdpie, plotSize) {
     for(i = 0; i < cdpie.length; i++) {
         cd0 = cdpie[i][0];
         trace = cd0.trace;
+
         pieBoxWidth = plotSize.w * (trace.domain.x[1] - trace.domain.x[0]);
         pieBoxHeight = plotSize.h * (trace.domain.y[1] - trace.domain.y[0]);
+        // leave some space for the title, if it will be displayed outside
+        if(!isSinglePie(trace)) pieBoxHeight -= getTitleSpace(trace, plotSize);
 
-        maxPull = trace.pull;
-        if(Array.isArray(maxPull)) {
-            maxPull = 0;
-            for(j = 0; j < trace.pull.length; j++) {
-                if(trace.pull[j] > maxPull) maxPull = trace.pull[j];
-            }
-        }
+        maxPull = getMaxPull(trace);
 
         cd0.r = Math.min(pieBoxWidth, pieBoxHeight) / (2 + 2 * maxPull);
 
         cd0.cx = plotSize.l + plotSize.w * (trace.domain.x[1] + trace.domain.x[0]) / 2;
-        cd0.cy = plotSize.t + plotSize.h * (2 - trace.domain.y[1] - trace.domain.y[0]) / 2;
+        cd0.cy = plotSize.t + plotSize.h * (1 - trace.domain.y[0]) - pieBoxHeight / 2;
 
         if(trace.scalegroup && scaleGroups.indexOf(trace.scalegroup) === -1) {
             scaleGroups.push(trace.scalegroup);

test/image/mocks/pie_title_inhole.json

@@ -0,0 +1,18 @@
+{
+  "data": [
+    {
+      "values": [955, 405, 360, 310, 295],
+      "labels": ["Mandarin", "Spanish", "English", "Hindi", "Arabic"],
+      "textinfo": "label+percent",
+      "hole": 0.3,
+      "title": "Num. speakers",
+      "titleposition": "inhole",
+      "type": "pie"
+    }
+  ],
+  "layout": {
+    "title": "Top 5 languages by number of native speakers (2010, est.)",
+    "height": 600,
+    "width": 600
+  }
+}

test/image/mocks/pie_title_multiple.json

@@ -0,0 +1,58 @@
+{
+  "data": [
+    {
+      "values": [38600, 83100, 11100, 15400, 1740, 77],
+      "labels": ["Platinum", "Palladium", "Rhodium", "Ruthenium", "Iridium", "Osmium"],
+      "type": "pie",
+      "name": "Year 2013",
+      "title": "Year 2013",
+      "domain": {
+        "x": [0, 0.5],
+        "y": [0.51, 1]
+      },
+      "hoverinfo": "label+percent+name",
+      "textinfo": "none"
+    },{
+      "values": [45800, 92900, 11100, 11000, 1960, 322],
+      "labels": ["Platinum", "Palladium", "Rhodium", "Ruthenium", "Iridium", "Osmium"],
+      "type": "pie",
+      "name": "Year 2014",
+      "title": "Year 2014",
+      "domain": {
+        "x": [0.51, 1],
+        "y": [0.51, 1]
+      },
+      "hoverinfo": "label+percent+name",
+      "textinfo": "none"
+    },{
+      "values": [42700, 85300,  10600, 8230, 1010, 8],
+      "labels": ["Platinum", "Palladium", "Rhodium", "Ruthenium", "Iridium", "Osmium"],
+      "type": "pie",
+      "name": "Year 2015",
+      "title": "Year 2015",
+      "domain": {
+        "x": [0, 0.5],
+        "y": [0, 0.5]
+      },
+      "hoverinfo": "label+percent+name",
+      "textinfo": "none"
+    },{
+      "values": [42300, 80400, 10700, 8410, 1300, 27],
+      "labels": ["Platinum", "Palladium", "Rhodium", "Ruthenium", "Iridium", "Osmium"],
+      "type": "pie",
+      "name": "Year 2016",
+      "title": "Year 2016",
+      "domain": {
+        "x": [0.51, 1],
+        "y": [0, 0.5]
+      },
+      "hoverinfo": "label+percent+name",
+      "textinfo": "none"
+    }
+ ],
+ "layout": {
+    "title": "U.S. Imports for Platinum-group Metals",
+    "height": 400,
+    "width": 500
+  }
+}

test/image/mocks/pie_title_pull.json

@@ -0,0 +1,21 @@
+{
+  "data": [
+    {
+      "values": [
+        50, 49, 48, 47, 46, 45, 44, 43, 42, 41
+      ],
+      "pull": [
+        0, 0.5, 0, 0.5, 0, 0.5, 0, 0.5, 0, 0.5
+      ],
+      "sort": false,
+      "type": "pie",
+      "textposition": "inside",
+      "title": "Withering Flower"
+    }
+  ],
+  "layout": {
+    "height": 600,
+    "width": 400,
+    "showlegend": false
+  }
+}

test/jasmine/tests/pie_test.js

@@ -182,6 +182,53 @@ describe('Pie traces:', function() {
         .catch(failTest)
         .then(done);
     });
+
+    it('shows title in hole', function(done) {
+        Plotly.newPlot(gd, [{
+            values: [2, 2, 2, 2],
+            title: 'Pie',
+            titleposition: 'inhole',
+            hole: 0.5,
+            type: 'pie',
+        }], {height: 300, width: 300})
+        .then(function() {
+            var title = d3.selectAll('.titletext text');
+            expect(title.size()).toBe(1);
+        })
+        .catch(failTest)
+        .then(done);
+    });
+
+    it('does not show title inside if there is no hole', function(done) {
+        Plotly.newPlot(gd, [{
+            values: [2, 2, 2, 2],
+            title: 'Pie',
+            titleposition: 'inhole',
+            hole: 0,
+            type: 'pie',
+        }], {height: 300, width: 300})
+        .then(function() {
+            var title = d3.selectAll('.titletext text');
+            expect(title.size()).toBe(0);
+        })
+        .catch(failTest)
+        .then(done);
+    });
+
+    it('shows title outside', function(done) {
+        Plotly.newPlot(gd, [{
+            values: [1, 1, 1, 1, 2],
+            title: 'Pie',
+            titleposition: 'outside',
+            type: 'pie',
+        }], {height: 300, width: 300})
+        .then(function() {
+            var title = d3.selectAll('.titletext text');
+            expect(title.size()).toBe(1);
+        })
+        .catch(failTest)
+        .then(done);
+    });
 });
 
 describe('pie hovering', function() {