analysis pipelines
1.0.0
Project Crane （危机种族主义和叙事评估）旨在支持希望使用最先进的文本分析算法研究特定事件如何影响在线仇恨言论和种族主义叙事的研究人员和反种族主义组织。 Crane Toolbox是一个Python软件包：安装后，起重机中的工具可作为用户在Python程序中或直接通过终端使用的功能可用。起重机以基本编程为目标，但没有机器学习技能。
跳过快速启动
回到顶部
危机种族主义和叙事评估或简称起重机是在弹性挑战赛（COVID19驱动的黑客马拉松）中诞生的。在九周内，由学生和专业设计师，程序员和计算机科学研究人员组成的跨学科团队开发了一个原型网站，用于实时监测与Covid19大流行有关的种族主义修辞。该项目是由波士顿大学Gianluca Stringhini提出的，他在COVID19（SARS-COV-2）大流行期间就早期出现在线恐怖行为。读者可能会在相应的DevPost页面和该存储库的相应DevPost页面和弹性 - 挑战 - 依据分支上找到有关弹性挑战的方法的更多详细信息。
在进行文学综述时，我们注意到，关于在线仇恨言论监控的论文很少有社会学研究方法和最新的自然语言处理工具。这些文献似乎主要分为方法论论文，旨在开发新的机器学习工具来检测和表征种族主义，而传统的社会学研究方法，无论是定性和定量的，这些方法都无法充分利用可用的数据和分析方法。
我们知道，这部分是由于很难从非常不同的领域收集跨学科团队，部分原因是自动仇恨言论检测的年轻和不稳定的本质。
我们在黑客马拉松期间的经验使我们相信，通过为社会科学研究人员提供用户友好的工具来利用当前仇恨言论检测和分析方法更强大的用户友好工具，从而有所缓解这些问题。
Crane Toolbox旨在支持研究人员和反种族主义组织研究特定事件如何影响在线仇恨言论和种族主义叙事。最先进的文本分析算法迅速发展，它们的传播通常仅限于计算机科学研究的专门领域。起重机工具箱将其中的一些方法（即典型的社会科学问题）包裹在不需要机器学习技能的用户友好工具中。
起重机工具箱是Python软件包。安装后，用户可以在其Python脚本中调用其功能，或者使用其直接通过其终端提供的工具。这些工具是用称为模块的几个子包进行组织的。每个模块对应于一般分析管道中的一步。
Crane工具箱的第一个版本为用户提供了工具和文档，以过滤和格式化他们从Twitter（导入模块）中提取的数据，准备它以进行分析（预处理模块），执行其选择的分析（ES）（分析模块），并获得结果的基本图形表示（可视化模块）。
回到顶部
本节适合经验丰富的程序员，他们希望首先跳入深处。如果您不知道我们在那里在说什么，请不要逃跑！尽管包装文档的长度可能会使它有些艰巨，但我们会牢记非专家，因此您应该找到使用起重机工具箱所需的所有说明和建议。
pip install cranetoolbox第一步是将您的数据转换为我们的共同数据交换格式，即三列CSV文件。我们使用crane-import模块执行此步骤。它采用每行包含一个JSON Tweet对象的源文件，并将它们转换为轻量级的CSV文件。可用参数在“导入模块”部分中详细介绍。
crane-import --source-folder ./my_source --output-folder ./my_output在数据分析之前清理文本数据很重要。我们提供了一个CLI工具来执行此步骤，并提供多个预处理选项。可用参数在“预处理模块”部分中详细介绍。
crane-preprocess ./my_output ./my_preproc_output我们目前提供了一个单个统计分析工具，该工具使用提供的一组关键字对数据集执行基本频率分析。所需的输入格式和可用参数在“分析模块”部分中详细介绍。
crane-analysis-quanti ./my_preproc_output keywords.json quanti_results.csv回到顶部
本节分为两个部分：第一个描述如何在终端中以命令行模式或通过python脚本中的函数调用来安装起重机工具箱并运行其工具；第二个提供了每个模块的详细信息，特别是数据格式和参数选择。
高级用户可以找到有关代码文档中每个模块内容的其他信息。
为了成功安装Crane工具箱，您将需要：
强烈建议使用编程和命令线方面的一些基本知识，但是勇敢和勤奋的人可能会选择继续进行。
如果上面的列表为您清楚，请跳过安装说明。否则，请阅读以下段落，以便准备好您的环境。
终端是一个接口，您可以在其中键入并执行基于文本的命令。您可能在这里找到一个更详细的说明，以及这里终端的样子的图片。
终端已经安装在您的计算机上。如果您使用的是基于UNIX的操作系统（ MACOSX或Linux发行版），则恰当地命名为终端，并与其他应用一起生活。如果您使用的是Windows操作系统，则将其命名为命令提示，可以在您的开始菜单中找到。对于Windows 8和10，它位于Windows系统文件夹中。
要在终端中运行命令，只需输入并按Enter。
Python 3是一种编程语言。
安装过程取决于您的操作系统。可以在Python官方网站上找到基本说明，但是您可以在互联网上轻松找到更多详细的指南。
PIP是软件包管理器：它可以帮助您下载Python软件包并在必要时更新它们。
可以在其官方网站上找到其安装的基本说明。它被广泛使用，因此在互联网上很容易找到逐步指南和其他资源。
pip3命令。您可以通过在终端中运行pip --version （ python -m pip --version for Windows用户）来检查哪个版本的pip 。
我们强烈建议使用pip安装起重机工具箱。在终端中运行pip install cranetoolbox 。该命令可能需要一些时间，因为pip还将自动安装起重机工具箱所需的所有Python软件包。您可以在[Crane Toolbox的PYPI页面]上检查依赖项列表（链接到PYPI页面）。
也可以从此存储库中可用的源代码手动安装起重机工具箱。
命令行模式是使用此软件包的最简单方法，它使用户能够快速运行软件包的所有部分并在很短的时间内生成可用的统计信息。
工具箱中有三种不同的CLI命令，它们是crane-import ， crane-preprocess和crane-analysis-quanti 。为了顺序，他们将导入/转换为标准的CSV格式，将数据预处理成可用的格式，并最终计算给定关键字的每日频率。
有关每个CLI工具下提供的参数的详细信息，请检查下面的详细文档。
此包已记住了重复使用。尽管CLI工具易于用作独立工具，但可以在另一个Python项目中导入和使用起重机工具箱。所有功能均通过标准Python软件包使用供用户使用。此外，单个高级功能对应于每个CLI工具，因此用户可以直接从Python调用所需的管道。
可以从crane-import命令行入口点访问导入模块。
该模块的目的是将原始的Twitter JSON数据转换为更易于管理和轻巧的管道，以供其余管道使用。这不是必需的步骤，可以由用户手动执行，也可以通过其他工具进行操作，因为数据在模块之间作为文件传递。
该模块可以处理大量的大型（多GB）文件，而不会严重依赖交换或内存使用情况。这是通过通过块读取文件（用户可以指定选项中的行数）以及在块中写作来完成的。这样可以确保在任何给定时刻仅保存一定数量的数据。
此外，它删除了分析管道不需要的额外推文数据，减少文件大小并提高此软件包中以后步骤的性能。
该模块将尝试读取指定文件夹中的任何文件，无论扩展名，名称等如何。它支持任何基于文本的文件格式（.json，.csv，.txt）。此外，它可以处理压缩的tar档案，并在给定的焦油档案中处理多个文件或文件夹。tar.gz或类似格式。
无论使用哪种确切的文件类型，都应使用n作为线结束字符，每行中始终使用一个JSON对象推文存储数据。
该模块将将所有文件与以下列相连为单个CSV文件：
| ID | 文本 | 创建的_at |
|---|---|---|
| Tweet的独特ID | 全文推文 | 推文的时间戳 |
CSV文件没有标题，逗号分隔符和文本的可选双引号。
根据推文是否超过140个字符，本文本列是动态选择的，有关扩展推文的更多信息，请参阅扩展推文上的官方文档
如果输出文件已经存在，则将附加到现有文件。在不存在的情况下，如果没有指定默认路径（“ ./filtered_data.csv”），则将创建一个新的。
该导入软件包可以用作命令行工具，并支持几个不同的选项。
--source-folder源文件夹或文件以扫描文件/档案进行处理。--output-folder以保存输出。必须存在指定的文件夹。默认为./ 。--output-name ，包括输出文件的名称，包括扩展名。默认为output.csv 。--text-name to text字段的名称，案例此字段具有不同的名称。--date-name为创建的five facter_at字段，案例此字段具有不同的名称。--id-name为ID字段，案例此字段具有不同的名称。--tweet-language保存在文件中的推文语言。基于JSON对象中的语言字段。默认为en 。--max-lines-in-memory最大的最大线路数量将在内存中保存。可以将其调整为以优化性能或内存有限的计算机。默认为50000 。--retweets使用此标志在输出集中包含转发。默认为false命令行入口点的完整示例：
crane-import --source-folder tweets/november --output-folder mydataset/data --max-lines-in-memory 2000 --output-name dataset.csv从crane-preprocess命令行入口点可以访问预处理管道。
所提出的预处理改编自Effrosynidis等。 （2017），使用技术9、0、1、3、5和7和4。
作为第一个位置参数给出的数据集可以是CSV文件的文件夹，也可以是单个CSV文件。每个CSV文件应包含3列（输入的ID，应该是唯一的，int； Tweet的文本，字符串；时间戳：时间戳字符串），没有标题，逗号分隔符和文本的可选双引号。
| ID | 文本 | 创建的_at |
|---|---|---|
| Tweet的独特ID | 全文推文 | 推文的时间戳 |
按顺序和给定的字符串，它将：
u002c ），-url ，则将其删除，-mention-hashtag ，则分割主题标签，punct ，否则下强调字符除外，-num ，则将其删除。主题标签被分割，即使用词段包分为单词。
处理后的数据集保存在给出的文件夹中，作为第二个位置参数。如果不存在，将创建文件夹。对于每个输入文件，都会生成处理后的文件。文件名是通过将“ _preprocessed”附加到相应输入文件的名称中生成的。每个CSV文件包含4列（输入的ID，应该是唯一的，int； Tweet的原始文本，字符串； Tweet的预处理文本，字符串；时间戳：Timestamp String），无标题，逗号分隔符和文本的可选双引号。
| ID | onigral_text | clean_text | 创建的_at |
|---|---|---|---|
| Tweet的独特ID | 全文推文 | 推文的预处理文本 | 推文的时间戳 |
该管道有两个强制性的位置论点和五个可选论点：
-url或--remove-url使用此标志从推文中删除URL，而不是用“ URL”替换它们。-mention或--remove-mentions使用此标志从推文中删除用户提及的“ @userhandle”，而不是用“ atuser”代替它们。-hashtag或--segment-hashtags使用此标志来分割主题标签，而不是简单地删除前面的“＃”字符。-punct或--remove-punctuation使用此标志来删除所有标点符号期望连字符，而不是更换重复的符号和新线。-num或--remove-numbers使用此标志从推文中删除所有数字，而不是用其文本版本替换它们。命令行入口点的完整示例：
crane-preprocess mydataset/data mydataset/preprocessedData -punct当前，分析模块仅提供一些简单的定量分析管道，以计算给定关键字的日常频率。
该分析管道可从crane-analysis-quanti命令行的入口点访问。
它计算数据集中给定关键字的每日频率。它允许使用关键字的变体。例如，“男孩”和“ boyz”的出现可以一起计算。
作为第一个位置参数给出的数据集可以是CSV文件的文件夹，也可以是单个CSV文件。每个CSV文件应包含4列（输入的ID，应该是唯一的，int； tweet的原始文本，字符串； tweet的预处理文本，字符串；时间戳：时间戳字符串），没有标题，逗号分隔符和文本的可选双引号。假定预处理文本是低案例。
| ID | onigral_text | clean_text | 创建的_at |
|---|---|---|---|
| Tweet的独特ID | 全文推文 | 推文的预处理文本 | 推文的时间戳 |
关键字是在JSON字典中定义的，其中键是每个关键字的主要变体，并且值是变体列表。所有关键字都应是较低的字符串。例如：
{
"color" : [
" colour " ,
" color "
],
"chinese" : [
" chinese " ,
" chineze " ,
" chines "
]
}The output is a CSV file with a day date column (format "%Y-%m-%d"), a total_count column with the daily total number of tweets in the dataset, a [keyword]_count column for each keyword (its main variant is used to name the column) with the daily number of tweets containing at least one variant of the keyword and a [keyword]_freq column for each keyword (its main variant is used to将列的命名为每日频率，其中包含关键字的至少一个变体的推文。
例如，对于以上设置的关键字：
| 天 | total_count | color_count | 中文_count | color_freq | 中文_freq |
|---|---|---|---|---|---|
| 日期 | 每日推文数量 | 每日带有“颜色”或变体的推文数量 | 每天的“中文”或变体的推文数量 | 带有“颜色”或变体的推文的每日频率 | 带有“中文”或变体的推文的每日频率 |
该管道有三个强制性的位置论点和一个可选的论点：
-d或--date-format字符串定义数据集中的日期格式。默认值为％a％a％b％d％h：％m：％s％z％y”。命令行入口点的完整示例：
crane-analysis-quanti mydataset/preprocessedData keywords.json quanti_results.csv -d " %d %b %a %h:%M:%S %z %Y " 尚未实施
回到顶部
我们欢迎所有贡献！如果您有疑问，功能请求或一些反馈，请使用GitHub的问题功能。
这些问题页面的工作方式与您的旧论坛页面相当，具有针对编程和GIT版本的许多其他功能。 GitHub为它们提供了详细的指南，但这是基本知识：
欢迎您提交有关开放问题的拉请请求。尤其是，标记为“帮助”的问题通常是核心团队正在努力的问题。这是我们在为代码库做出贡献时要求您遵循的准则。
如果您想进一步参与自己（审查PRS，计划新功能，研究机器学习方法，进行用户研究，...），您可以通过通过电子邮件向Bolduc2（AT）Hotmail（DOT）FR发送电子邮件来加入核心团队，以加入。当然，我们欢迎开发人员，也欢迎设计师，所有学术领域的研究人员，技术作家...
我们选择私下登上人员，而不是出于两个原因，而不是在存储库中分享我们的所有资源。首先，我们希望使不使用开源项目的用户更容易找到所需的东西。其次，我们的一些资源包含来自用户研究的私人信息。
回到顶部
https://crane-toolbox.github.io/#/是在弹性挑战赛期间建立的原型网站，以试图量化和表征COVID19大流行对在线恐怖分子仇恨言论的影响。我们将其作为一个非常基本的数据分析类型的示例，可以使用起重机工具箱进行。
我们目前不打算。由于团队的组成，我们决定将精力集中在起重机工具箱上，我们相信我们可以有所作为。
lachapeliere | gianluca stringhini ？ | Marko Shiva Pavlovic | Claudio Catterina | Svetlanamd ？ ？ ？ ？ | 伊恩 | 保罗汉 |
凯利 ？ ？ | Gabriel Ribeiro | 以撒 | TomášLokša | 朱迪思·范·斯蒂格伦（Judith Van Stegeren） |
表情符号密钥
该项目遵循全企业规范。欢迎任何形式的贡献！
该项目第一阶段的黑客马拉松贡献者列表可以在Crane DevPost页面上找到。
是的！查看贡献部分。
Python是用于数据分析任务的非常常见的编程语言。软件包是基本Python语言的可安装附加组件。粗略地说，模块是带有Python代码的文件。
就是说，如果您完全不熟悉Python，则可能需要在使用起重机工具箱之前对其进行一些尝试。
请使用此存储库的问题页面。查看贡献部分以获取更多详细信息。
起重机工具箱根据GNU Affero通用公共许可证v3.0分发。
您可以使用它，但要使用它，只要您尊重许可要求：包括许可证和版权通知，说明您所做的更改，披露您的来源（此回购），并根据相同的许可证分发代码。请注意，无论您对此代码的使用，我们都不承担任何责任，并且我们不提供任何保修。
请链接到此仓库。
Twitter开发人员条款限制了Tweets数据集的共享。您将无法找到具有推文内容的公开可用数据集，而是Tweet ID的数据集。可以使用水合物进行水合。
从那里，这确实取决于您的研究主题和问题。有些非常敏感，有些则少。如果您的时间不太敏感，请使用常规的搜索引擎尝试运气。有些人需要一个天真的数据集，代表了Twitter的完整信息流。在这种情况下，最好的选择是与研究团队进行频繁分析Twitter内容的合作。他们可能会保持流的运行，以收集每日Twitter数据的1％。其他人则需要一个已经过滤的数据集，以针对特定的关键字或用户进行过滤。如果是您的情况，请使用常规搜索引擎尝试运气。如果您不需要历史数据，也可以启动自己的Twitter流以精确收集所需的数据。
我们正在努力将多种标准输入格式包含到我们的导入模块中。如果不支持您的数据格式，请与我们联系，我们将尽最大努力将其支持在起重机工具箱中或指导您将其转换为我们支持的格式之一。
也许我们不知道这一点，也许我们还没有时间实施它，也许我们选择不出于给定的原因不包括它。请与我们联系以告诉我们有关。 （除非这是使用使用费的专有方法。）
