README

这个库是为了评估信息检索系统中任何算法的有效性，并分析它们的性能而创建的。为此，汇集了14种不同的有效性度量。所有这些度量在文献中都是常用的。它们如下所示

• Average Precision @n (AP@n)
• Mean Average Precision (MAP)
• Geometric Mean Average Precision (GMAP)
• Eleven Point - Interpolated Average Precision (IAP)
• R-Precision
• F-Measure
• Cumulative Gain (CG)
• Normalized Cumulative Gain (NCG)
• Discounted Cumulative Gain (DCG)
• Normalized Discounted Cumulative Gain (NDCG)
• Mean Reciprocal Rank (MRR)
• Rank-Biased Precision (RBP)
• Expected Reciprocal Rank (ERR)
• BPref

这个库还包含了5个数据集，这些数据集是为了学习和使用不同的参数来测试每种方法而组织的。尽管这个库在带有真实用户数据的在线IR系统中动态使用，但它也可以用于静态数据集。

开始之前

关于数据集的一些解释

共享的数据集格式为txt。数据集中的每一行都由管道符号分隔。尽管这些数据集具有相似的特征，但它们被创建在不同的格式中，并在不同的测量中使用，或者单独使用，以展示方法的工作原理以及这些方法需要什么样的属性（参数）。数据集中使用的属性如下

• id：这是交互的唯一标识符
• query_id：这可以被认为是一个会话标识符
• total_result：查询返回的结果数量
• related_document_id：这是已知与查询相关的文档的标识符。为了更好地理解，可以认为专家在查询之前已经确定了与查询相关的文档
• visited_or_related_document_id：在在线系统中，结果列表中被点击的页面的ID可以被认为是与查询对应的文档ID。另一方面，这种情况也可以在静态数据集中被计算为相同。例如，假设一个算法被测试，并提交了一个查询。根据related_document_id属性，结果列表中某些文档的ID可以被认为是相关文档ID
• order_number_of_the_document：在结果列表中被点击/相关的文档的顺序号
• assessment_of_the_document：属于被点击/相关的文档的评估。该属性在1到5的数值范围内，对于这个库来说，这个范围必须是相同的格式，即使范围限制发生变化（例如：0-5，1-3，0-3，1-7等）
• judgement_of_the_document：属于被点击/相关的文档的判断。这个属性有布尔值0或1，表示页面/文档是否与查询相关

方法中使用的参数

在方法中使用5个不同的参数。虽然其中一些参数是通用的，但还有一些参数是单独使用的。所有参数及其解释如下

• data：这个参数包括用户或专家的评估（范围），用户或专家的判断（布尔值）以及用户交互，并在每个方法中使用。
• 边界（默认值：['all']）：此参数表示总结果的截止点。这样，我们可以根据截止点分析性能。可以以数组格式分配5、10等数值或字符串值（如'全部'）给它。如果截止点是数值且低于总结果，则处理过的行将被添加到总计算中。另一方面，如果截止点不是数值，则使用数据集中的所有行进行计算。
• 常数（默认值：'0.3'）：此参数仅在GMAP的计算中使用，以避免计算中出现零值。
• 持久性（或概率）级别（默认值：[0.5, 0.8, 0.95]）：此参数仅在RBP的计算中使用。
• 最大等级级别（默认值：'5'）：此参数仅在ERR参数的计算中使用。最低级别也用于计算，但不需要作为参数包含在此测量中。

安装

可以使用以下代码安装该包

composer require ozcan39/ir_evaluation_php

将包导入研究

安装包后，使用以下代码

require_once ('vendor/autoload.php');
use \ir_evaluation\effectiveness;

$ir=new effectiveness(); # --> an object, which we can use all methods in it, is created

在情况不同数据集将被使用时，可能不希望包含示例数据集。

查看数据集

以下示例用于查看数据集1。

$dataset = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset1.txt", "r") or die("Unable to open file!");
while(!feof($dataset))
{
    var_dump(trim(fgets($dataset)));
}

可以通过只需更改第一行末尾的dataset1一词末尾的数字（1到5）来查看其他数据集。

方法的使用

如前所述，每种方法都使用一些数据集一起或分别。在这种情况下，需要相同数据集的方法已经一起解释。

基于精度的方法：AP@n、MAP、GMAP、IAP、R-Precision和F-Measure

这些方法一起使用数据集3和数据集4。在调用方法之前，创建一个名为interactions的变量，如下所示

$interactions=array();

# dataset3 formation: id|query_id|related_document_id

$dataset = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset3.txt", "r") or die("Unable to open file!");
while(!feof($dataset))
{
    $row=explode('|',trim(fgets($dataset)));
    $interactions[$row[1]]['related_documents'][]=$row[2];
}
fclose($dataset);

# dataset4 formation: id|query_id|total_result|visited_or_related_document_id|order_number_of_the_document

$dataset2 = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset4.txt", "r") or die("Unable to open file!");
while(!feof($dataset2))
{
    $row=explode('|',trim(fgets($dataset2)));
    $interactions[$row[1]]['total_result']=$row[2];
    $interactions[$row[1]]['visited_documents'][]=$row[3];
    $interactions[$row[1]]['visited_documents_orders'][$row[3]]=$row[4];
}
fclose($dataset2);

创建交互变量后，相关方法的用法如下

########################################################################################
# parameters => (data, boundaries)

echo "<h1>Average Precision@n</h1>";
$ap_at_n=$ir->ap_at_n($interactions,array(5,10,15,20,'all'));
var_dump($ap_at_n);

echo "<h1>R-Precision</h1>";
$rprecision=$ir->rprecision($interactions,array(5,10,15,20,'all'));
var_dump($rprecision);

echo "<h1>Mean Average Precision</h1>";
$mean_ap=$ir->mean_ap($interactions,array(5,10,15,20,'all'));
var_dump($mean_ap);

echo "<h1>F-Measure</h1>";
$fmeasure=$ir->fmeasure($interactions,array(5,10,15,20,'all'));
var_dump($fmeasure);
########################################################################################
# parameters -> (data, constant, boundaries)

echo "<h1>Geometric Mean Average Precision</h1>";
$gmap=$ir->gmap($interactions,0.3,array(5,10,15,20,'all'));
var_dump($gmap);
########################################################################################
# parameters -> (data)

echo "<h1>Eleven Point - Interpolated Average Precision</h1>";
echo "<h4>Recall => Precision</h4>";
$iap=$ir->iap($interactions);
var_dump($iap);

基于增益的方法：CG、NCG、DCG和NDCG

这些方法仅使用数据集1。在调用方法之前，创建一个名为interactions的变量，如下所示

$interactions=array();

# dataset1 formation: id|query_id|total_result|visited_or_related_document_id|order_number_of_the_document|assessment_of_the_document
# assessment_of_the_document: assessment is between 1 and 5 for this example

$dataset = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset1.txt", "r") or die("Unable to open file!");
while(!feof($dataset))
{
    $row=explode('|',trim(fgets($dataset)));
    $interactions[$row[1]]['total_result']=$row[2];
    $interactions[$row[1]]['assessed_documents'][$row[3]]=array($row[4],$row[5]);
}
fclose($dataset);

创建交互变量后，相关方法的用法如下

# parameters => (data, boundaries)

echo "<h1>Cumulative Gain</h1>";
$cgain=$ir->cgain($interactions,array(5,10,15,20,"all"));
var_dump($cgain);

echo "<h1>Normalized Cumulative Gain</h1>";
$ncgain=$ir->ncgain($interactions,array(5,10,15,20));
var_dump($ncgain);

echo "<h1>Discounted Cumulative Gain</h1>";
$dcgain=$ir->dcgain($interactions,array(5,10,15,20));
var_dump($dcgain);

echo "<h1>Normalized Discounted Cumulative Gain</h1>";
$ndcgain=$ir->ndcgain($interactions,array(5,10,15,20,"all"));
var_dump($ndcgain);

Mean Reciprocal Rank (MRR)

此方法仅使用数据集2。在调用方法之前，创建一个名为interactions的变量，如下所示

$interactions=array();

# dataset2 formation: id|query_id|visited_or_related_document_id|order_number_of_the_document

$dataset = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset2.txt", "r") or die("Unable to open file!");
while(!feof($dataset))
{
    $row=explode('|',trim(fgets($dataset)));
    $interactions[$row[1]]['visited_documents_orders'][]=$row[3];
}
fclose($dataset);

创建交互变量后，方法的用法如下

# parameters => (data)

echo "<h1>Mean Reciprocal Rank</h1>";
$mrr=$ir->mrr($interactions);
var_dump($mrr);

Rank-Biased Precision (RBP)

此方法仅使用数据集4。在调用方法之前，创建一个名为interactions的变量，如下所示

$interactions=array();

# dataset4 formation: id|query_id|total_result|visited_or_related_document_id|order_number_of_the_document

$dataset = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset4.txt", "r") or die("Unable to open file!");
while(!feof($dataset))
{
    $row=explode('|',trim(fgets($dataset)));
    $interactions[$row[1]]['total_result']=$row[2];
    $interactions[$row[1]]['visited_documents'][]=$row[3];
    $interactions[$row[1]]['visited_documents_orders'][$row[3]]=$row[4];
}
fclose($dataset);

创建交互变量后，方法的用法如下

# parameters => (data, persistence (or probability) levels, boundaries)

echo "<h1>Rank Biased Precision</h1>";
$rbprecision=$ir->rbprecision($interactions,array(0.5,0.8,0.95),array(5,10,15,20,'all'));
var_dump($rbprecision);

Expected Reciprocal Rank (ERR)

此方法仅使用数据集1。在调用方法之前，创建一个名为interactions的变量，如下所示

$interactions=array();

# dataset1 formation: id|query_id|total_result|visited_or_related_document_id|order_number_of_the_document|assessment_of_the_document
# assessment_of_the_document: assessment is between 1 and 5 for this example

$dataset = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset1.txt", "r") or die("Unable to open file!");
while(!feof($dataset))
{
    $row=explode('|',trim(fgets($dataset)));
    $interactions[$row[1]]['total_result']=$row[2];
    $interactions[$row[1]]['assessed_documents'][$row[3]]=array($row[4],$row[5]);
}
fclose($dataset);

创建交互变量后，方法的用法如下

# parameters => (data, max_grade_level, boundaries)

echo "<h1>Expected Reciprocal Rank</h1>";
$err=$ir->err($interactions,5,array(5,10,15,20,"all"));
var_dump($err);

BPref

此方法仅使用数据集5。在调用方法之前，创建一个名为interactions的变量，如下所示

$interactions=array();

# dataset5 just consists of judged documents. Similar to dataset1, but last column has 2 different (boolean) values: 1: related, 0: unrelated
# data, which belong to unjudged documents, do not need to be inside of the dataset
# dataset5 formation: id|query_id|total_result|visited_or_related_document_id|order_number_of_the_document|judgement_of_the_document

$dataset = fopen("vendor/ozcan39/ir_evaluation_php/src/datasets/dataset5.txt", "r") or die("Unable to open file!");
while(!feof($dataset))
{
    $row=explode('|',trim(fgets($dataset)));
    $interactions[$row[1]]['total_result']=$row[2];
    $interactions[$row[1]]['assessed_documents'][$row[3]]=array($row[4],$row[5]);
}
fclose($dataset);

创建交互变量后，方法的用法如下

# parameters => (data, boundaries)

echo "<h1>BPREF</h1>";
$bpref=$ir->bpref($interactions,array(5,10,15,20,"all"));
var_dump($bpref);

如何显示分析结果

如果方法具有边界参数，则针对每个截止点分别显示结果。例如

Mean Average Precision:
{
    5: {'count': 27, 'value': 0.33497942386831275},
    10: {'count': 19, 'value': 0.3966374269005848},
    15: {'count': 9, 'value': 0.4420940170940171},
    20: {'count': 3, 'value': 0.6923076923076922},
    'all': {'count': 28, 'value': 0.3850509113901969}
}

for MAP@5: 27 row records were used in total for calculation and the result has been found as the value (0.33497942386831275).
In this calculation, if the query has a result equal to 5 or higher than 5, the processed row data is added to the calculation process.

如果方法具有边界和持久性（或概率）级别参数，则针对每个截止点和持久性（或概率）级别分别显示结果。例如

Rank Biased Precision:
{
    5: {
        '0.5': {'count': 27, 'value': 0.1724537037037037},
        '0.8': {'count': 27, 'value': 0.10601481481481481},
        '0.95': {'count': 27, 'value': 0.0339625578703704}
        },
    10: {
        '0.5': {'count': 19, 'value': 0.18045847039473684},
        '0.8': {'count': 19, 'value': 0.11351753566315788},
        '0.95': {'count': 19, 'value': 0.042275296240743256}
        },
    15: {
        '0.5': {'count': 9, 'value': 0.2048882378472222},
        '0.8': {'count': 9, 'value': 0.12131197674382221},
        '0.95': {'count': 9, 'value': 0.042236674585140445}
        },
    20: {
        '0.5': {'count': 3, 'value': 0.3333740234375},
        '0.8': {'count': 3, 'value': 0.13791463178239996},
        '0.95': {'count': 3, 'value': 0.04233933479437731}
        },
    'all': {
        '0.5': {'count': 28, 'value': 0.17031478881835938},
        '0.8': {'count': 28, 'value': 0.1224766315254345},
        '0.95': {'count': 28, 'value': 0.04952452518068968}
        }
}

如果方法仅具有数据参数，则结果以单个值显示，除了IAP方法。例如

Mean Reciprocal Rank:
0.3965163308913308

##############################################################

Eleven Point - Interpolated Average Precision:
Recall => Precision
{
    '0.0': 0.40527483429269134,
    '0.1': 0.40527483429269134,
    '0.2': 0.40527483429269134,
    '0.3': 0.40527483429269134,
    '0.4': 0.40527483429269134,
    '0.5': 0.40527483429269134,
    '0.6': 0.3731319771498342,
    '0.7': 0.3731319771498342,
    '0.8': 0.3731319771498342,
    '0.9': 0.3731319771498342,
    '1.0': 0.3731319771498342
}

许可证

此库根据LGPL 2.1许可证分发。请阅读LICENSE以获取有关库可用性和分发的信息。

关于引用此库

本节将进行更新。

关于测量方法的进一步阅读

平均精确度@n、平均平均精确度（MAP）、R-Precision:

Ricardo Baeza-Yates和Berthier Ribeiro-Neto。2011。《现代信息检索：搜索背后的概念和技术》（第2版）。Addison-Wesley出版公司，美国。

几何平均平均精确度：https://trec.nist.gov/pubs/trec15/appendices/CE.MEASURES06.pdf

Eleven Point - Interpolated Average Precision (IAP)

Bruce Croft、Donald Metzler和Trevor Strohman。2009。《搜索引擎：信息检索实践》（第1版）。Addison-Wesley出版公司，美国。

F-Measure

C. J. Van Rijsbergen。1979。《信息检索》（第2版）。Butterworth-Heinemann，美国。

累积增益，归一化累积增益，折扣累积增益，归一化折扣累积增益

Kalervo Järvelin 和 Jaana Kekäläinen. 2000. 高相关文档的IR评估方法. 在第23届国际ACM SIGIR信息检索研究与发展会议（SIGIR '00）论文集中. 计算机协会出版社，纽约，纽约，美国，41–48. DOI:https://doi.org/10.1145/345508.345545

Kalervo Järvelin 和 Jaana Kekäläinen. 2002. 基于累积增益的IR技术评估. ACM Trans. Inf. Syst. 20, 4（2002年10月），422–446. DOI:https://doi.org/10.1145/582415.582418

平均倒数秩

Ellen Voorhees. 1999. TREC-8问答跟踪报告. 第8届文本检索会议论文集. 77-82.

Rank-Biased Precision (RBP)

Alistair Moffat 和 Justin Zobel. 2008. 用于检索效果测量的排序偏置精度. ACM Trans. Inf. Syst. 27, 1，文章2（2008年12月），27页. DOI:https://doi.org/10.1145/1416950.1416952

期望倒数秩

Olivier Chapelle，Donald Metlzer，Ya Zhang，和 Pierre Grinspan. 2009. 分级相关性的期望倒数秩. 在第18届ACM信息与知识管理会议（CIKM '09）论文集中. 计算机协会出版社，纽约，纽约，美国，621–630. DOI:https://doi.org/10.1145/1645953.1646033

Bpref

Chris Buckley 和 Ellen M. Voorhees. 2004. 不完整信息下的检索评估. 在第27届国际ACM SIGIR信息检索研究与发展会议（SIGIR '04）论文集中. 计算机协会出版社，纽约，纽约，美国，25–32. DOI:https://doi.org/10.1145/1008992.1009000