Skip to content
No description, website, or topics provided.
Python
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
CBDBtoSNA_v0.10.py
README.md

README.md

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.
You can’t perform that action at this time.