Skip to content

hluling/CBDBtoSNA

master
Switch branches/tags
Code
This branch is up to date with hlulingtu/CBDBtoSNA:master.
Contribute

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 

CBDBtoSNA

Created by: Luling Huang (luling.huang@temple.edu) & Marcus Bingenheimer (bingenheimer@temple.edu)

一、简介 / I. Introduction:

CBDBtoSNA.py 是一个将中国历代人物传记资料库 (China Biographical Database) 中的人物关系网络转换成:

Python 3程序。GEXF 和 GraphML 格式文件可用于 Gephi 中的网络关系可视化。

CBDBtoSNA.py is a Python 3 script that transforms the social relations data contained in the CBDB (China Biographical Database) into either:

that can be used to visualize the data (e.g., in Gephi).

二、输入文件 / II. Input File:

a_cbdb_data.xml

  • 请根据实际情况修改输入文件名 Please change filename accordingly
  • 此输入文件须与CBDBtoSNA.py在同一文件夹中 An input file and CBDBtoSNA.py should be in the same folder.

三、输出文件 / III. Output File:

xxxxx.gexf 或/or xxxxx.graphml

四、使用前 / IV. Prerequisites:

用户端设备须有 Python 3。 另外,用户须安装 Python 工具库-lxml

User's computer must have Python 3 installed. In addition, users must install the Python library—lxml.

五、使用 / V. How to Run the Script:

用户可在命令行界面(Command-Line Interface)中运行 CBDBtoSNA.py。 输入文件 (xxxxx.xml) 之路径须与 CBDBtoSNA.py 之路径相同。 输出文件将在同一个路径中。

Users can run CBDBtoSNA.py from a command-line interface. The path of the input file (xxxxx.xml) must be the same as the path of CBDBtoSNA.py. The output file will be in the same path.

六、人物范围选取 / VI. Selectors:

由于资料库包含历代人物近四十万,且 Gephi 中所能处理的节点数与关系数有限,用户须根据以下三类参数来设定所取人物范围:

  • 年份
  • 性别
  • 人物编号

参数设定只针对于 CBDB 中某个人物(即源 XML 中某个 <Person>,见附录三)。

  1. 年份: 用户可通过设定两个或一个年份来定义一个年份范围。 如: -- 两个年份:-202(-代表公元前)和 9 所定义的年份范围是公元前202年(含)至公元9年(含)。 CBDBtoSNA.py a_cbdb_data.xml gexf -f -202 -t 9 选取出生/死亡/指数年份在公元前202年(含)与公元9年(含)之间的人物之人物关系。 -- 一个年份:-202 所定义的年份范围可以是公元前202年(含)及之前或公元前202年(含)及之后。 CBDBtoSNA.py a_cbdb_data.xml -t -202 选取出生/死亡/指数年份在公元前202年(含)及之前的人物之人物关系。 CBDBtoSNA.py a_cbdb_data.xml -f -202 选取出生/死亡/指数年份在公元前202年(含)及之后的人物之人物关系。 -- 注:年份参数可与性别参数(见下)搭配使用,但不可与人物编号(见下)搭配使用。

  2. 性别: 参数值:1为男性,2为女性 (ISO/IEC 5218) CBDBtoSNA.py a_cbdb_data.xml gexf -f -202 -t 9 -g 2 选取出生/死亡/指数年份在公元前202年(含)与公元9年(含)之间的女性人物之人物关系。 -- 注1:性别参数可与年份参数搭配使用,但不可与人物编号(见下)搭配使用。 -- 注2:为避免输出文件过大,建议勿仅使用性别参数,性别应搭配年份使用。

  3. 个人网络(根据 CBDB 人物编号): 用户可输入至多十个(至少一个)人物编号来选取人物。 用户可通过CBDB网上查询系统获取人物编号。 CBDBtoSNA.py a_cbdb_data.xml graphml -pid 1762 38653 选取CBDB人物编号为1762及38653的两个人物之人物关系。 -- 注1:人物编号不可与性别或年份参数搭配使用。 -- 注2:如使用人物编号,对于其中某人物(A),用户可选择将A之网络关系目标(B)之目标(C)一并加入到网络中,此为两个延伸度(Degree of 2)。用户还可选择将A之网络关系目标(B)之目标(C)之目标(D)一并加入到网络中,此为三个延伸度(Degree of 3)。延伸度为正整数,预设值为1,最大值为3。

As the complete CDBD is too large to be displayed efficiently, users are advised to select a subset of the data using the following parameters:

  • date
  • gender
  • Ego-Networks (based on Person IDs)

The parameter settings are only for a person in the CBDB (i.e., a <Person> in the source XML, see Appendix III).

  1. Year Date (-from & -to): The user can define a range of years.

    -- Using both -from and -to : -f -202 (- for BC) and -t 9 defines a range of years from 202 BCE (inclusive) to 9 CE (inclusive). CBDBtoSNA.py a_cbdb_data.xml gexf -f -202 -t 9 selects all relational information on people with birth/death/index years between -202 BCE (inclusive) and 9 CE (inclusive).

    -- Using only one date parameter:
    -t -202 = 202 BCE (inclusive) and before CBDBtoSNA.py a_cbdb_data.xml graphml -t -202 selects all relational information on people with birth/death/index years before -202 BCE (inclusive). -f -202 = 202 BCE (inclusive) and after CBDBtoSNA.py a_cbdb_data.xml gexf -f -202 selects all relational information on people with birth/death/index years after -202 BCE (inclusive).

    -- Note: The date parameters can be used with gender parameter, but not with ego-network (i.e., Person ID) parameter.

  2. Gender: Parameter values: 1 = male, 2 = female (ISO/IEC 5218) CBDBtoSNA.py a_cbdb_data.xml gexf -f -202 -t 9 -g 2 selects all relational information on people who are female with birth/death/index years between -202 BCE and 9 CE (inclusive). -- Note 1: The gender parameter can be used with the year parameter, but not with the person number (see below). -- Note 2: In order to avoid large output files,it is advisable to use -gender with the date parameters -from and -to.

  3. Ego-Networks (based on Person IDs): Users can enter between 1 and 10 Person IDs to select CBDB entries. Users can retrieve Person IDs from CBDB's online query website. CBDBtoSNA.py a_cbdb_data.xml graphml -pid 1762 38653 selects all relational information on people whose CBDB Person IDs are 1762 and 38653. -- Note 1: IDs cannot be used with gender or date parameter. -- Note 2: Degree parameter: Users can specify to expand the ego-networks to the 2nd and 3rd degree by setting the degree parameter (-d / -degree) to 2 or 3.

七、命令行中参数设定(详情见上文四,范例见下文八)/ VII. Command line Parameters (for details, see Section IV above; for examples, see Section VIII below):

Argparse 预设参数(Default argument):
-h      --help          显示帮助信息(英文)
					    Show help information (in English)。

Argparse 必选参数(Positional arguments; Required)
xmlInput                输入文件名 (xxxxx.xml; 区分大小写)
					    Input xml file name(xxxxx.xml; Case sensitive)
outputFormat            输出格式名(gexf 或 graphml; 不区分大小写)
					    Output format (Values: gexf or graphml; NOT case sensitive)

Argparse 可选参数(Optional arguments)
-f      --fromY         指定起始年份(含)。如为公元前年份,在数字前加'-'。
					    Specify starting year (inclusive). For BCE, prepend '-'.
-t      --toY           指定终止年份(含)。如为公元前年份,在数字前加'-'。
					    Specify ending year (inclusive). For BCE, prepend '-'.
-g      --gender        指定性别:1为男性,2为女性。
					    Specify gender. 1 for male, 2 for female.
-pid    --personID      指定CBDB中人物编号。请勿在某个编号前加零。两个或以上编号须以空格间隔。至多十个,至少一个。
					    Specify CBDB Person ID(s). Please do not prepend zero to an ID.
						Separate two IDs by a space. There should be at least one Person ID (no more than ten).
-d      --degree        指定个人网络之延伸度。正整数,预设值为1,最大值为3。
					    Specify degree of ego-network.
					    The value should be a positive integer (default is one, maximum is 3).

Argparse 详情/details: https://docs.python.org/3.6/library/argparse.html#module-argparse

八、命令行中参数设定范例 / VIII. Examples:

1. 两个年份 / Select all persons between 202 BCE and 9 CE, return a .gexf file:
CBDBtoSNA.py a_cbdb_data.xml gexf -f -202 -t 9
    
2. 两个年份及女性 / Select all women between 202 BCE and 9 CE, return a .gexf file:
CBDBtoSNA.py a_cbdb_data.xml gexf -f -202 -t 9 -g 2
    
3. 一个年份(此年份(含)及之前)/ Select all persons before 202 BCE (inclusive), return a .graphml file:
CBDBtoSNA.py a_cbdb_data.xml graphml -t -202
    
4. 一个年份(此年份(含)及之后)及男性 / Select all men after 9 CE (inclusive), return a .graphml file:
CBDBtoSNA.py a_cbdb_data.xml graphml -f 9 -g 1

5. 两个人物编号(王安石、吴氏)/ Select the ego-networks of two persons (Wang Anshi and Wu Shi), return a .gexf file:
CBDBtoSNA.py a_cbdb_data.xml gexf -pid 1762 38653

6. 三个人物编号及两个延伸度 / Select three persons returning a 2-degree ego network for each, return a .graphml file:
CBDBtoSNA.py a_cbdb_data.xml graphml -pid 128931 220217 34919 -d 2

附录 / Appendices

一、GEXF 与 GraphML 中的网络节点 / I. Node in GEXF and GraphML

1. 一节点对应一人物
2. 节点编号形式:
   “n” + CBDB中人物编号 
3. 节点属性:
    a. 拼音名(如此人在CBDB中,则默认为Gephi可视化中的节点标签,node label)
    b. 中文名(对应GEXF/GraphML之节点属性n@chName;如此人不在CBDB中,则为Gephi可视化中节点标签)
    c. 出生年份(如有;对应GEXF/GraphML之节点属性n@birthY)
    d. 死亡年份(如有;对应GEXF/GraphML之节点属性n@deathY)
    e. 指数年份(如有;对应GEXF/GraphML之节点属性n@indexYear)
    f. 朝代(如有;对应GEXF/GraphML之节点属性n@dynasty)
    
1. One node represents one person.
2. Node identifier's format:
   “n” + CBDB Person ID 
3. Node attributes:
    a. Pinyin name(If a person exists in CBDB as a <Person> element,the Pinyin name is the node label of that person in Gephi)
    b. Chinese name(corresponding to the node attribute name, n@chName, in GEXF/GraphML; If a person does not exist in CBDB as a <Person> element,the Chinese name is the node label of that person in Gephi)
    c. Birth year(If available: corresponding to the node attribute name, n@birthY, in GEXF/GraphML)
    d. Death year(If available: corresponding to the node attribute name, n@deathY, in GEXF/GraphML)
    e. Index year(If available: corresponding to the node attribute name, n@indexY, in GEXF/GraphML)
    f. Dynasty(If available: corresponding to the node attribute name, n@dynasty, in GEXF/GraphML)

二、GEXF / GraphML 中的网络关系 / II. Edge in GEXF / GraphML

1. 某关系中两个节点的编号对应上述节点编号(附录一)。
2. 关系无方向性。
3. 关系编号形式:
   “e” + 自然数
4. 关系属性:
    a. 关系性质:亲属关系或社会关系 (对应GEXF/GraphML之关系属性e@edgeType)
    b. 关系内容 (对应GEXF/GraphML之关系属性e@label)
    c. 资料来源 (对应GEXF/GraphML之关系属性e@bibl)

1. Node identifiers in edge follow the node identifier format specified above (see Appendix I).
2. Edge is undirectional.
3. Edge identifier format:
    "e" + natural number
4. Edge attributes:
     a. Edge type: 'Kinship' or 'Association' (corresponding to the edge attribute name, e@edgeType, in GEXF/GraphML)
     b. Edge label: Nature of a relationship (corresponding to the edge attribute name, e@label, in GEXF/GraphML)
     c. Source of information (corresponding to the edge attribute name, e@bibl, in GEXF/GraphML)

三、关于年份与性别设定范围与输出文件中人物范围 / III. The user-specified range of persons and the range of persons in output

由于参数设定只针对于CBDB中某个人物(即源XML中某个<Person>),若视人物(<Person>)为某关系中的X,则此关系中的Y有可能在所设年份及性别范围之外。

Parameter setting applies only to the attributes found in <Person> elements in a CBDB XML input file. That is, the source of an edge always comes from <Person> and is always within a user-specified range of date and/or gender. However, the target of an edge may be outside the user-specified range.

About

CBDBtoSNA transforms the social relations data contained in the CBDB database into network visualization.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 100.0%