一、QCPStatisticalBox 概述

QCPStatisticalBox 是 QCustomPlot 中用于绘制箱线图(盒须图)的类，可以显示数据的五个关键统计量：最小值、第一四分位数(Q1)、中位数、第三四分位数(Q3)和最大值，以及可能的异常值。

二、主要属性

属性	类型	描述
width	double	箱体的宽度（坐标轴单位）
whiskerWidth	double	须线的宽度（0-1表示比例）
pen	QPen	箱线和须线的画笔属性
brush	QBrush	箱体填充的画刷属性
whiskerPen	QPen	须线的画笔属性
medianPen	QPen	中位线的画笔属性
outlierStyle	QCPScatterStyle	异常值的散点样式
name	QString	箱线图名称（显示在图例中）
visible	bool	是否可见
selectable	bool	是否可选择
selected	bool	当前是否被选中

三、常用方法

1. 数据相关方法

方法	参数	返回值	描述
setData	double key, double minimum, double lowerQuartile, double median, double upperQuartile, double maximum	void	设置单个箱线图数据
setData	const QVector<double>& keys, const QVector<double>& minimums, const QVector<double>& lowerQuartiles, const QVector<double>& medians, const QVector<double>& upperQuartiles, const QVector<double>& maximums	void	设置多个箱线图数据
addData	double key, double minimum, double lowerQuartile, double median, double upperQuartile, double maximum	void	添加单个箱线图
addData	const QVector<double>& keys, const QVector<double>& minimums, const QVector<double>& lowerQuartiles, const QVector<double>& medians, const QVector<double>& upperQuartiles, const QVector<double>& maximums	void	添加多个箱线图
setOutliers	double key, const QVector<double>& outliers	void	设置指定key的异常值
addOutliers	double key, const QVector<double>& outliers	void	添加异常值

2. 样式设置方法

方法	参数	返回值	描述
setWidth	double width	void	设置箱体宽度
setWhiskerWidth	double width	void	设置须线宽度比例
setPen	const QPen &pen	void	设置箱线画笔
setBrush	const QBrush &brush	void	设置箱体填充画刷
setWhiskerPen	const QPen &pen	void	设置须线画笔
setMedianPen	const QPen &pen	void	设置中位线画笔
setOutlierStyle	const QCPScatterStyle &style	void	设置异常值样式

3. 交互相关方法

方法	参数	返回值	描述
setSelectable	QCP::SelectionType selectable	void	设置可选择类型
setSelection	QCPDataSelection selection	void	设置选中项
selected	-	QCPDataSelection	获取选中项
selectTest	const QPointF &pos, bool onlySelectable, QVariant *details	double	测试点是否选中

四、信号列表

信号	参数	描述
selectionChanged	bool selected	选中状态改变时触发
selectableChanged	QCP::SelectionType selectable	可选择状态改变时触发

五、基础使用示例

cpp

// 创建箱线图
QCPStatisticalBox *statBox = new QCPStatisticalBox(customPlot->xAxis, customPlot->yAxis);// 设置单个箱线图数据 (key, 最小值, Q1, 中位数, Q3, 最大值)
statBox->setData(1, 3.0, 4.5, 5.8, 7.2, 9.0);// 添加异常值
statBox->addOutliers(1, {2.1, 9.5, 10.2});// 设置样式
statBox->setName("数据分布");
statBox->setWidth(0.3);
statBox->setBrush(QColor(100, 150, 250, 100));
statBox->setMedianPen(QPen(Qt::red, 2));
statBox->setWhiskerWidth(0.2);// 设置坐标轴范围
customPlot->xAxis->setRange(0, 2);
customPlot->yAxis->setRange(0, 12);// 刷新显示
customPlot->replot();

六、高级功能示例

1. 多组箱线图比较

cpp

// 创建第一组箱线图
QCPStatisticalBox *statBox1 = new QCPStatisticalBox(customPlot->xAxis, customPlot->yAxis);
statBox1->setData(1, 3.0, 4.5, 5.8, 7.2, 9.0);
statBox1->addOutliers(1, {2.1, 9.5});
statBox1->setName("组A");
statBox1->setWidth(0.3);
statBox1->setBrush(QColor(100, 150, 250, 100));// 创建第二组箱线图
QCPStatisticalBox *statBox2 = new QCPStatisticalBox(customPlot->xAxis, customPlot->yAxis);
statBox2->setData(2, 2.5, 5.0, 6.5, 8.0, 10.0);
statBox2->addOutliers(2, {1.8, 10.5});
statBox2->setName("组B");
statBox2->setWidth(0.3);
statBox2->setBrush(QColor(250, 150, 100, 100));// 设置坐标轴
customPlot->xAxis->setRange(0, 3);
customPlot->yAxis->setRange(0, 12);

2. 自定义选择样式

cpp

statBox->setSelectable(QCP::stWhole); // 允许选择整个箱线图
statBox->setSelectedBrush(QBrush(QColor(255, 100, 100, 150)));
statBox->setSelectedPen(QPen(Qt::red, 2));// 连接选择信号
connect(customPlot, &QCustomPlot::selectionChangedByUser, [=](){if (statBox->selected()) {qDebug() << "箱线图被选中";}
});

3. 从实际数据计算统计量

cpp

// 计算统计量的辅助函数
void calculateStatistics(const QVector<double> &data, double &min, double &q1, double &median, double &q3, double &max, QVector<double> &outliers)
{QVector<double> sorted = data;std::sort(sorted.begin(), sorted.end());int n = sorted.size();min = sorted.first();max = sorted.last();// 计算四分位数q1 = sorted.at(n*1/4);median = sorted.at(n/2);q3 = sorted.at(n*3/4);// 计算异常值(使用1.5IQR规则)double iqr = q3 - q1;double lowerBound = q1 - 1.5*iqr;double upperBound = q3 + 1.5*iqr;for (double val : data) {if (val < lowerBound || val > upperBound) {outliers.append(val);}}
}// 使用示例
QVector<double> dataset = { /* 你的数据 */ };
double min, q1, median, q3, max;
QVector<double> outliers;
calculateStatistics(dataset, min, q1, median, q3, max, outliers);statBox->setData(1, min, q1, median, q3, max);
statBox->setOutliers(1, outliers);

七、箱线图各部分的含义

Q75：上四分位数
Q25：下四分位数
须线(whisker)
箱体(interquartile range)

八、性能优化技巧

1. 批量设置数据：

   cpp

   // 使用vector批量设置数据比多次调用addData更高效
   QVector<double> keys = {1, 2, 3};
   QVector<double> mins = {3.0, 2.5, 3.2};
   // ...其他统计量向量
   statBox->setData(keys, mins, q1s, medians, q3s, maxs);

2. 简化绘制：

   cpp

   statBox->setAntialiased(false); // 关闭抗锯齿提高性能

3. 使用OpenGL加速：

   cpp

   customPlot->setOpenGl(true);

QCPStatisticalBox 提供了完整的箱线图功能，可以有效地展示数据的分布特征和异常值，特别适用于统计分析和数据比较场景。