README

为PHP生成SPSS类似表格、交叉表格（也称为crosstabs或列联表）和分层交叉表格的高度可定制抽象。这些在展示两个或更多分类变量之间的关系时非常有用。

要求

• PHP 8.2或更高版本

建议要求

确保安装了 intl 和 bcmath 扩展，分别用于国际数字格式化和更好的数学精度。

安装

运行以下命令来安装此库

$ composer require cliffordvickrey/crosstabs

基本用法

在此，我们生成一个交叉表格，显示网站访问者的浏览器以及客户端操作系统。

<?php

// some data. If "n" is omitted, each row is treated as a single case
$rawData = [
    ['Device Type' => 'Desktop', 'Browser' => 'Chrome', 'Platform' => 'Linux', 'n' => '256'],
    ['Device Type' => 'Tablet', 'Browser' => 'Safari', 'Platform' => 'iOS', 'n' => '6'],
    ['Device Type' => 'Desktop', 'Browser' => 'Chrome', 'Platform' => 'MacOSX', 'n' => '227'],
    ['Device Type' => 'Desktop', 'Browser' => 'IE', 'Platform' => 'Windows', 'n' => '35'],
    ['Device Type' => 'Desktop', 'Browser' => 'Chrome', 'Platform' => 'Windows', 'n' => '221'], 
    ['Device Type' => 'Desktop', 'Browser' => 'Firefox', 'Platform' => 'MacOSX', 'n' => '38'], 
    ['Device Type' => 'Mobile Device', 'Browser' => 'Safari', 'Platform' => 'iOS', 'n' => '21'],
    ['Device Type' => 'Desktop', 'Browser' => 'Netscape', 'Platform' => 'Windows', 'n' => '21'],
    ['Device Type' => 'Desktop', 'Browser' => 'Safari', 'Platform' => 'MacOSX', 'n' => '38'],
    ['Device Type' => 'Mobile Device', 'Browser' => 'Edge', 'Platform' => 'iOS', 'n' => '72'],
    ['Device Type' => 'Desktop', 'Browser' => 'Safari', 'Platform' => 'Windows', 'n' => '15'],
    ['Device Type' => 'Desktop', 'Browser' => 'Firefox', 'Platform' => 'Linux', 'n' => '27'],
    ['Device Type' => 'Desktop', 'Browser' => 'Firefox', 'Platform' => 'Windows', 'n' => '12'],
    ['Device Type' => 'Desktop', 'Browser' => 'Edge', 'Platform' => 'Windows', 'n' => '11']
];

// the builder does exactly what it says. Set a bunch of options and call the "build" method
$builder = new \CliffordVickrey\Crosstabs\CrosstabBuilder();
$builder->setRawData($rawData);
$builder->setTitle('Browser Usage by Platform');
$builder->setColVariableName('Browser');
$builder->setRowVariableName('Platform');
$builder->setShowPercent(true);
$builder->setPercentType((\CliffordVickrey\Crosstabs\Options\CrosstabPercentType::Column);

$crosstab = $builder->build();

// display the crosstab as HTML (see example output below)
echo $crosstab->write();

// if you use a Bootstrap layout and want a table with all the fancy utility classes, etc., you can override the default
// writer like so:
echo $crosstab->write(writer: new \CliffordVickrey\Crosstabs\Writer\CrosstabBootstrapHtmlWriter());

// some inferential stats. Degrees of freedom are equal to the number of columns (minus 1) multiplied by the number of
// rows (minus 1). Chi-squared is a test statistic, comparing actual values with ones we'd expect if no relationship
// existed between the row and column variables
var_dump($crosstab->getDegreesOfFreedom()); // 15
var_dump($crosstab->getChiSquared()); // 598.35 (clearly significant!)

// now: let's add third dimension: device type
$builder->setTitle('Browser Usage by Platform by Device Type');
$builder->addLayer('Device Type');
// percentages will be of columns within each layer category; great for visualizing the effects of control variables
$builder->setPercentType(\CliffordVickrey\Crosstabs\Options\CrosstabPercentType::ColumnWithinLayer);
$crosstab = $builder->build();
echo $crosstab->write();

// want a simpler display? Let's just show a frequency distribution of browsers
$builder = new \CliffordVickrey\Crosstabs\CrosstabBuilder();
$builder->setRawData($rawData);
$builder->setTitle('Browser Usage');
$builder->setRowVariableName('Browser');
$builder->setShowPercent(true);
echo $crosstab->write();

类API

构建器： \CliffordVickrey\Crosstab\CrosstabBuilder

构建器用于配置和创建所需的表格。在配置时，您通常会设置 rawData 和 rowVariableName。在大多数情况下，您还想要设置 colVariableName（如果您正在可视化两个或更多分类变量）。

@build(): void

构建表格。如果选项无效，则抛出 \CliffordVickrey\Crosstab\Exception\CrosstabInvalidArgumentException

@addLayer(CrosstabVariable|array|string $layer, ?string $description = null, ?array $categories = []): void

向交叉表格添加一个层变量

@addLayers(CrosstabVariableCollection|iterable $layers): void

添加多个层变量

@setColVariableDescription(?string $colVariableDescription): void

设置列变量的标签。如果没有设置，则使用名称

@setColVariableName(?string $colVariableName): void

设置原始数据中列变量的名称

@setColVariableCategories(array $colVariableCategories): void

显式定义原始数据中列变量的类别；否则，将推断出来。用于重新标记/重新编码分类值

@setKeyFrequency(?string $keyFrequency): void

设置源数据中表示行中案例数量的键。如果此信息不存在，则将每一行视为单个案例。默认为 "n"

@setKeyWeightedFrequency(?string $keyWeightedFrequency): void

设置源数据中表示行权重的键。如果此信息不存在，则每一行将平等加权。默认为 "weight"

@setLayers(CrosstabVariableCollection|iterable $layers = []): void

设置多个层变量

@setLocale(string $locale): void

设置用于数字格式化的区域设置。默认为 "en_US。" 请参阅intl扩展文档

@setMathematicalScale(int $mathematicalScale): void

设置用于浮点数学的刻度。默认为 "16"，大约是PHP大多数构建中浮点数的精度

@setMessageExpectedFrequency(string $messageExpectedFrequency): void

设置用于期望频率表格单元格的标签。默认为 "Frequency (Expected)"

@setMessageExpectedPercent(string $messageExpectedPercent): void

设置用于期望百分比的表格单元格的标签。默认为 "% (Expected)"

@setMessageFrequency(string $messageFrequency): void

设置用于频率表格单元格的标签。默认为 "Frequency"

@setMessageNil(string $messageNil): void

设置用于表中NULL值的标签。默认为 "-"

@setMessageNoData(string $messageNoData): void

设置用于空表的标签。默认为 "There is no data to display"

@setMessagePercent(string $messagePercent): void

设置用于百分比单元格的标签。默认为 "%"

@setMessageTotal(string $messageTotal): void

设置用于总单元格的标签。默认为 "Total"

@setMessageWeightedExpectedFrequency(string $messageWeightedExpectedFrequency): void

设置用于加权预期百分比单元格的标签。默认为 "Expected Frequency (Weighted)"

@setMessageWeightedExpectedPercent(string $messageWeightedExpectedPercent): void

设置用于加权预期百分比单元格的标签。默认为 "Expected % (Weighted)"

@setMessageWeightedFrequency(string $messageWeightedFrequency): void

设置用于加权频率单元格的标签。默认为 "Frequency (Weighted)"

@setMessageWeightedPercent(string $messageWeightedPercent): void

设置用于加权百分比单元格的标签。默认为 "% (Weighted)"

@setPercentType(CrosstabPercentType $percentType): void

设置百分比类型（行、列、总等）。有关允许选项的列表，请参阅 \CliffordVickrey\Crosstabs\Options\CrosstabPercentType 枚举。默认为 CrosstabPercentType::Total

@setRawData(iterable $rawData): void

要制表的原始数据。应为可迭代的迭代器（行）。行被转换为数组。"n" 和 "weight" 键在每个数组中可选用于计算，如果您需要表示每行多个案例或捕获调查加权

@setrowVariableDescription(?string $rowVariableDescription): void

设置行变量的标签。如果没有设置，则使用名称

@setrowVariableName(?string $rowVariableName): void

设置原始数据中行变量的名称

@setrowVariableCategories(array $rowVariableCategories): void

显式定义原始数据中行变量的类别；否则，它们会被推断。对于重新标记/重新编码分类值很有用

@setScaleDecimal(int $scaleDecimal): void

设置表格中格式化十进制值的比例。默认为 2

@setScalePercent(int $scalePercent): void

设置表格中格式化百分比值的比例。默认为 2

@setShowExpectedFrequency(bool $showExpectedFrequency): void

设置是否在表格中显示预期频率（例如，如果我们假设 X 和 Y 之间不存在关系时的值）。默认为 FALSE

@setShowExpectedPercent(bool $showExpectedPercent): void

设置是否在表格中显示预期百分比（例如，如果我们假设 X 和 Y 之间不存在关系时的值）。默认为 FALSE

@setShowFrequency(bool $showFrequency): void

设置是否在表格中显示频率。默认为 TRUE

@setShowPercent(bool $showPercent): void

设置是否在表格中显示百分比。默认为 FALSE

@setShowWeightedExpectedFrequency(bool $showWeightedExpectedFrequency): void

设置是否在表格中显示加权预期频率（例如，如果我们假设 X 和 Y 之间不存在关系时的值）。默认为 FALSE

@setShowWeightedExpectedPercent(bool $showWeightedExpectedPercent): void

设置是否在表格中显示加权预期百分比（例如，如果我们假设 X 和 Y 之间不存在关系时的值）。默认为 FALSE

@setShowWeightedFrequency(bool $showWeightedFrequency): void

设置是否在表格中显示加权频率。默认为 FALSE

@setShowWeightedPercent(bool $showWeightedPercent): void

设置是否在表格中显示加权频率。默认为 FALSE

@setTitle(?string $title): void

设置可选的标题以出现在表格标题中。默认为 NULL（即不显示标题）

交叉表： CliffordVickrey\Crosstabs\Crosstab

封装了交叉表的数据和表示元素。实现了 \Traversable；遍历将返回行对象（CliffordVickrey\Crosstabs\Crosstab\CrosstabRow），当遍历这些对象时，它们自身提供单元格对象（CliffordVickrey\Crosstabs\Crosstab\CrosstabRow）。这些单元格包含表格的表示数据，而矩阵（通过getter公开）包含制表数据。

@getCell(int $x, int $y): ?CrosstabCell

根据指定的笛卡尔坐标返回单元格。如果不存在，则返回NULL

@getDegreesOfFreedom(): int

获取用于计算卡方检验统计量的独立值数量。度数越多，检验统计量达到显著性就越困难。公式是 (rowCount - 1) * (colCount - 1)

@getChiSquared(bool $weighted = false, ?int $scale = null): float

获取卡方检验统计量。值越高，以及用于计算统计量的单元格数量越少，行变量和列变量的总体参数之间存在关系的可能性就越大

@getMatrix(): array

获取表示交叉表内数据的矩形矩阵的值对象

@write(array $options = [], ?CrosstabWriterInterface $writer = null): string

将交叉表写入字符串的便捷方法。如果没有提供写入器，将使用默认的HTML写入器（CliffordVickrey\Crosstabs\Writer\CrosstabHtmlWriter）。请参阅该方法的类常量以获取输出选项。返回字符串输出

@writeToFile(array $options = [], ?CrosstabWriterInterface $writer = null): string

将交叉表写入文件的便捷方法。如果没有提供写入器，将使用默认的HTML写入器（CliffordVickrey\Crosstabs\Writer\CrosstabHtmlWriter）。请参阅该方法的类常量以获取输出选项。如果没有提供文件名，将创建一个临时文件。返回写入的文件名