RankedList（排名列表）

排名列表是一个对样本中的数据进行定位、区间统计的Python库。给定一组样本数据，将该数据进行升序、降序排序，得到一个有序列表。对于该有序列表，RankedList提供了两种定位的方式：绝对位置和相对位置。

• 绝对位置：从1开始计，要找的值排第几位。例如15表示排第15位的数据，-1表示排倒数第1位的数据。
• 相对位置：取值在0~1之间，表示要找的值在百分之多少的位置，可以以小数或百分比形式给出，例如0.34和'34%'均可表示排在第34%处的数据。

基于这两种定位方式，可以通过绝对/相对位置找出一个值或一组值；也可以反过来，找出一个值或一组值对应的绝对/相对位置。

另外，还可以通过区间统计获得落在某个区间内的值的数量，包括单个区间的统计和一系列区间的统计。

如何安装或更新

1.通过pip安装：

• pip install rankedlist

2.通过pip更新版本：

• pip install rankedlist --upgrade
  如果更新失败，可以尝试先卸载旧版本，再安装新版本：
• pip uninstall rankedlist
• pip install rankedlist

3.在pypi上下载analyticlab源代码并安装：

• 打开网址https://pypi.python.org/pypi/rankedlist
• 通过download下载tar.gz文件，解压到本地，通过cd指令切换到解压的文件夹内
• 通过python setup.py install实现安装

使用教程

1.导入RankedList类：

通过以下指令实现RankedList类的导入：

from rankedlist import RankedList

2.创建一个排名列表：

要创建一个排名列表，需要给定要排名的数据，以及排列顺序（升序、降序还是维持原有顺序不变）。数据可以以两种方式给出：直接在程序中列出数据，或者从txt文件中读取数据。下面依次介绍两种创建排名列表的方式：

2.1 直接列数据创建：

直接列数据，即通过RankedList类的构造方法创建排名列表。RankedList类的构造方法如下：

RankedList(values, order=1)

• 其中values是排名列表中的数据，可以以list给出，比如[1.66,1.76,1.82,1.71,1.75]；也可以字符串形式给出，此时数据之间要以空格隔开，比如'1.66 1.76 1.82 1.71 1.75'；如果已有现成的RankedList，那么直接将现成的RankedList作为values即可。
• order为数据的排序方式。order=1时为升序，-1时为降序，0时为维持现有顺序不变。默认使用的是升序排列。

下面举例说明：

>>> r1 = RankedList([1.61, 3.20, 2.49, 2.61, 2.91])  #通过list给出数据
>>> r2 = RankedList('1.61 3.20 2.49 2.61 2.91')  #通过字符串形式给出数据
>>> r3 = RankedList(r2, order=-1)  #基于现有的排名列表创建新的排名列表，且降序排列
>>> r1
[1.61, 2.49, 2.61, 2.91, 3.2]
>>> r2
[1.61, 2.49, 2.61, 2.91, 3.20]
>>> r3
[3.20, 2.91, 2.61, 2.49, 1.61]

可以注意到，尽管r1、r2的数据相同，但输出的排名列表中，r1和r2的最后一个数值3.2和3.20的输出位数不同，这是因为对于输入数据为小数的情形，当以list给出时，多余的0会被舍去，即3.20会输出成3.2；而以字符串形式给出时，数据会被以FFloat数据类型储存（后续会介绍该数据类型），该数据类型可以保留数值原有的格式，即3.20仍会输出成3.20。

2.2 通过txt文件读取数据创建：

当需要排名的数据量很大时，将数据直接列到程序里会很不方便，这时可以把数据放在txt文件里，然后通过RankedList类的fromTxt静态方法创建排名列表。fromTxt方法如下：

def fromTxt(fName, splitter='\t', order=1)

下面以一个名为scores.txt的文件为例，来说明如何读取数据。scores.txt的文件内容如下：

81	88	83	86	87	91	90	86	93	90	79	81

• 其中fName为数据文件的文件名（含扩展名），在这里即为'scores.txt'。
• splitter为数据之间的分隔符，这里数据之间使用一个缩进隔开的，故splitter为'\t'。
• order为排序，希望数据降序排列，故order为-1。

故导入scores.txt文件的数据以创建排名列表的代码如下：

>>> r = RankedList.fromTxt('scores.txt', order=-1)  #这里splitter为默认值'\t'，故省略

3. 访问排名列表中的数据：

对于一个RankedList排名列表，可以访问其中的单个元素或一系列元素。数值的访问可通过绝对位置或相对位置的定位实现。例如有100个数据从高到低排列，要访问其中第10个元素，可以通过10给出其绝对位置，或者通过0.1(小数形式)或'10%'(百分数形式)给出其相对位置。

下面以排名列表sc为例，详细说明元素的访问方法：

>>> sc = RankedList('81.9 87.5 83.3 86.2 90.1 85.5 89.1 79.4 82.2 86.7 91.2 88.7 83.6', order=-1)
>>> sc
[91.2, 90.1, 89.1, 88.7, 87.5, 86.7, 86.2, 85.5, 83.6, 83.3, 82.2, 81.9, 79.4]

3.1 访问单个元素：

3.1.1 通过绝对位置访问：

绝对位置访问，是指给定要访问的数据是第几个，或倒数第几个元素，来实现单个元素的访问，例如：

访问第5个元素，这时使用正数5。注意这与list中元素的访问不同，正数索引是从1开始的，而不是list那样从0开始：

>>> sc[5]
87.5

访问倒数第2个元素，这时使用负数-2。负数索引与list相同：

>>> sc[-2]
81.9

3.1.2 通过相对位置访问：

相对位置可以用一个介于0~1之间的小数，或者100%以内的百分数来表示，下面以要访问30%处的数据，来举例说明：

以小数表示相对位置时，小数直接以float形式给出即可：

>>> sc[0.3]
89.1

以百分数表示相对位置时，由于百分数有'%'符号，因此要以字符串形式给出：

>>> sc['30%']
89.1

3.2 访问多个元素：

多个元素的访问与单个元素类似，可以通过绝对位置或相对位置访问。访问多个元素的方法有列举法(列举出要访问哪几个元素)和区间法(给出要访问的元素在哪个区间)两种。

3.2.1 通过列举法访问：

将要访问的元素的位置以绝对位置或相对位置一一列举出来，元素之间以逗号隔开，例如访问第1、3、4、5个元素：

>>> sc[1,3,4,5]
[91.2, 89.1, 88.7, 87.5]

访问第13%、40%处的元素：

>>> sc['13%', '40%']
[91.2, 87.5]

3.2.2 通过区间法访问：

区间法访问排名列表类似于list，使用:访问一个区间的数据，但要注意区间必须以字符串形式给出，如'3:7','-4:','30%:'。下面举例说明：

访问排第3~6个数据，注意第6个也被包含在内，这是与list不同的地方：

>>> sc['3:6']
[89.1, 88.7, 87.5, 86.7]

访问倒数第3个及以后的数据：

>>> sc['-3:']
[82.2, 81.9, 79.4]

访问第30%~60%处的数据：

>>> sc['30%:60%']
[88.7, 87.5, 86.7, 86.2]

访问第25%之前的数据：

>>> sc[':25%']
[91.2, 90.1, 89.1]

4. 数据定位：

通过排名列表的数据定位功能，可以得到单个或多个数值在排名列表中的位置(可以是绝对位置或相对位置)。要定位的数值可以是排名列表中的一个特定的数值，如87.5；如果要定位的数值不在排名列表中，如87，会找到与该数值最接近的数值，以最接近的数值所在的位置作为87所在的位置。

通过RankedList的pos类方法实现数据定位，pos类方法如下： def pos(value, method='%')

• value为要定位的数值，可以是单个数值(如86)，或多个数值组成的list(如[81,85,89])。
• method为对于找到的数值，如何表示它们的位置。method在以下三个值中选择：
  • 'd'：整数形式的绝对位置，例如5表示要定位的数据排第5。
  • 'rat'：分数形式的绝对位置与元素总数之比，例如5/16表示要定位的数据在16个数据中排第5。
  • 'f'：小数形式的相对位置，例如0.38461538461538464表示要定位的数据排38.46%。
  • '%'：百分数形式的相对位置，例如'32.61%'表示要定位的数据排32.61%。默认使用的是'%'。

下面以第3部分的排名列表sc举例说明：

>>> sc.pos(88)
'38.26%'
>>> sc.pos(88, 'd')
5
>>> sc.pos(88, 'rat')
'5/13'
>>> sc.pos(88, 'f')
0.38461538461538464
>>> sc.pos([90,85,80], 'd')
['15.38%', '61.54%', '100.00%']

5. 区间统计：

5.1 单个区间统计：

通过RankedList的countInRange类方法，可以数值位于每个某个区间内的元素总个数，countInRange类方法如下： def countInRange(start, end) 参数start、end分别为区间的起始、结束值，start可以小于end，也可以大于end。例如要找出sc中介于85~88之间的数据，以下两种方式皆可：

>>> sc.countInRange(85, 88)
4
>>> sc.countInRange(88, 85)
4

5.2 区间统计表格与直方图：

每调用一次countInRange类方法，只能获得一个区间内的元素总个数。如果要获得当前排名列表中全部区间的元素总个数，可以通过rangeTable类方法实现。rangeTable类方法可以实现区间统计表格及直方图的显示，通过参数调整要显示表格和直方图中的哪些项，其结构如下： def rangeTable(step, rFormat, show='1111', name='区间|数量|比例|累计数量|累计比例', hist='0000')

• step为步进，即每两个区间之间的改变量是多少，为float形式，根据步进是递增还是递减，可以是正数或复数。例如从4.2到1.5进行区间统计，以4.2-4.1、4.1-4.0、4.0-3.9、...、1.6-1.5为区间，那么step为-0.1；从78到92进行区间统计，以78-80、80-82、...、90-92为区间，那么step为2。
• rFormat表示区间用什么格式进行编码，例如'%.1f'会得到4.2-4.1、4.1-4.0、...、1.6-1.5，'%.2f'会得到4.20-4.10、4.10-4.00、...、1.60-1.50。
• 区间统计表格除了区间之外，还有数量、比例、累计数量、累计比例四项，参数show用于设置要显示这四项中的哪几项，其中1表示显示，0表示不显示。例如'1111'表示四项都显示，'1100'表示显示数量和比例，不显示累计数量和累计比例。默认show='1111'，即四项都显示。
• 除了区间统计表格之外，还可以展示按数量、比例、累计数量、累计比例的直方图，与参数show类似，例如'1010'表示展示按数量、累计数量的直方图，另外两个直方图不展示。默认hist='0000'，即不展示直方图。

生成的表格会根据程序运行环境，来决定用什么格式展示。命令行环境下（如Python shell、IPython），会展示出纯文本格式的表格：

+---------+------+--------+----------+
|   区间  | 数量 |  比例  | 累计比例 |
+---------+------+--------+----------+
| 4.2-4.0 |  5   | 1.04%  |  1.04%   |
| 4.0-3.8 |  12  | 2.51%  |  3.55%   |
| 3.8-3.6 |  29  | 6.05%  |  9.60%   |
| 3.6-3.4 |  47  | 9.81%  |  19.42%  |
| 3.4-3.2 |  50  | 10.44% |  29.85%  |
| 3.2-3.0 |  56  | 11.69% |  41.54%  |
| 3.0-2.8 |  63  | 13.15% |  54.70%  |
| 2.8-2.6 |  66  | 13.78% |  68.48%  |
| 2.6-2.4 |  43  | 8.98%  |  77.45%  |
| 2.4-2.2 |  25  | 5.22%  |  82.67%  |
| 2.2-2.0 |  36  | 7.52%  |  90.19%  |
| 2.0-1.8 |  22  | 4.59%  |  94.78%  |
| 1.8-1.6 |  11  | 2.30%  |  97.08%  |
| 1.6-1.4 |  9   | 1.88%  |  98.96%  |
| 1.4-1.2 |  2   | 0.42%  |  99.37%  |
| 1.2-1.0 |  2   | 0.42%  |  99.79%  |
| 1.0-0.8 |  1   | 0.21%  | 100.00%  |
+---------+------+--------+----------+

在Jupyter Notebook环境下，则会展示HTML格式的表格：

区间	数量	比例	累计比例
4.2-4.0	5	1.04%	1.04%
4.0-3.8	12	2.51%	3.55%
3.8-3.6	29	6.05%	9.60%
3.6-3.4	47	9.81%	19.42%
3.4-3.2	50	10.44%	29.85%
3.2-3.0	56	11.69%	41.54%
3.0-2.8	63	13.15%	54.70%
2.8-2.6	66	13.78%	68.48%
2.6-2.4	43	8.98%	77.45%
2.4-2.2	25	5.22%	82.67%
2.2-2.0	36	7.52%	90.19%
2.0-1.8	22	4.59%	94.78%
1.8-1.6	11	2.30%	97.08%
1.6-1.4	9	1.88%	98.96%
1.4-1.2	2	0.42%	99.37%
1.2-1.0	2	0.42%	99.79%
1.0-0.8	1	0.21%	100.00%

*6.FFloat数据类型：

先给定一组数据均为整数的排名列表，以及一组数据为小数的排名列表，来观察从中取出的元素的数据类型：

>>> r1 = RankedList('18 41 36 44 47 51 19 31 22 27')
>>> r2 = RankedList('11.69 12.44 12.67 12.00 12.33 12.37')
>>> type(r1[1])
int
>>> type(r2[1])
rankedlist.ffloat.FFloat

可以注意到，r1中的数据均为整数，故从r1中取得的元素为int类型；而r2的情况就有所不同，其数据为小数，从r1中取得的元素并不是float，而是FFloat类型，这一数据类型不同于float之处在于可以保持输入数据的格式，例如在'11.69 12.44 12.67 12.00 12.33 12.37'中，12.00会被保持为12.00，输出时不会输出12，而是12.00。但要注意只有排名列表中的数据以字符串形式给出时，才能保持其格式，若以[11.69,12.44,12.67,12.00,12.33,12.37]给出，那么12.00会输出成12。

FFloat类型可以与int、float等类型进行计算，计算会得到float类型，例如：

>>> type(r2[1])
rankedlist.ffloat.FFloat
>>> type(r2[1]+0)
float
>>> r2[1]/4
2.9225
>>> type(r2[1]/4)
float

要想将FFloat类型转换为float类型，除了通过r2[1]+0或r2[1]*1计算转换为float类型之外，还可以通过FFloat的toFloat()类方法实现转换：

>>> r2[1].toFloat()
11.69
>>> type(r2[1].toFloat())
float

*7.排名列表转list：

通过RankedList类的toList()类方法，可以讲RankedList转换为list：

>>> sc.toList()
[91.2, 90.1, 89.1, 88.7, 87.5, 86.7, 86.2, 85.5, 83.6, 83.3, 82.2, 81.9, 79.4]

当排名列表中的数据是以整数形式给出时，得到的list中的元素为int类型；而以小数形式给出时，得到的list中的元素不再是FFloat类型，而是float类型，即得到的list直接就是float组成的list。

运行环境

RankedList只能在Python 3.x环境下运行，不支持Python 2.x环境。要求系统已安装veryprettytable库，这个库用于在命令行状态下展示表格。在Jupyter Notebook环境下，会使用HTML展示表格。