原文地址：https://npyc-toolbox.readthedocs.io/en/latest/tutorials/tutorial.html

使用 nPYc 工具箱

数据集导入及元数据映射（Importing datasets & mapping metadata）

nPYc工具箱中的 Datasets 由 Dataset类的子类实例表示。Dataset的每一个实例都代表了在代谢分析实验中测量的特性的丰度，以及样本和特征元数据（measured abundances of features, plus sample and feature metadata）。

根据数据类型，对象可以从包含多个样本的单个文档中初始化，或者通过集成原始数据文件的目录：

msDataset = nPYc.MSDataset('~/path to file.csv', fileType='xcms')

或者

nmrDataset = nPYc.NMRDataset('~/path to Topspin experiment directory/', fileType='Bruker')

一旦创建，您可以查询它所包含的特性或样本（features or samples）的数量：

dataset.noFeatures
dataset.noSamples

或者直接检查示例或特性元数据，以及原始度量（sample or feature metadata, and the raw measurements）：

dataset.sampleMetadata
dataset.featureMetadata
​
dataset.intensityData

额外的研究设计参数或样本元数据（ sample metadata）可以使用addSampleInfo() 方法映射到Dataset中。为了标准化QC过滤程序，nPYc工具箱定义了一组用于描述参考样本类型和设计元素的术语（reference sample types and design elements），并罗列在nomenclature中。

简而言之， precision reference 的测定是为了描述分析变异性，而 linearity reference 测定提供了度量样本对丰度变化的响应的方法。 这些测量可以在n synthetic reference mixtures中进行，反复测量一个 representative matrix的样本，或者研究中的样本pool 。

对于基本的实验设计，“Basic CSV”格式（请参阅这里 的详细信息）指定了一种将分析数据与元数据相匹配的简单方法：

datasetObject.addSampleInfo(descriptionFormat='Basic CSV', filePath='~/path to basic csv file')

ISA-TAB 格式的研究设计文档提供了一种将丰富的实验设计参数映射到对象的方法：

datasetObject.addSampleInfo(descriptionFormat='ISATAB', filePath='~/path to study file.csv')

“Basic CSV”文件根据“Sample File Name”列中的条目匹配 sampleMetadata表中的“Sample File Name”。Sample types 和 assay roles 可以使用在enumerations模块中定义的值来描述。如果“Include Sample”的值是False，这个样本的 sampleMask将被设置为False。在默认情况下，不能与“Basic CSV”文件中的条目匹配的样本也将被屏蔽（masked）。

表1：一个“Basic CSV”文件的最小结构

“Basic CSV”文件任何附加的列的信息将作为附加样本元数据（additional sample metadata）追加到 sampleMetadata表中。

当分析文件（analytical file ）的名称是根据一种允许研究设计参数被解析的标准生成的时候，样本元数据的获得可以熟练的通过正则表达式的方法捕获named groups中的参数

datasetObject.addSampleInfo(descriptionFormat='Filenames', filenameSpec='regular expression string')

把元数据映射到一个对象是一个累计操作，因此可以使用多个调用来映射来自多个数据源的元数据：

# Load analytical data to sample ID mappings
datasetObject.addSampleInfo(descriptionFormat='NPCLIMS', filePath='~/path to LIMS file')
​
# Use the mappings to map in sample metadata
datasetObject.addSampleInfo(descriptionFormat='NPC Subject Info', filePath='~/path to Subject Info file')
​
# Get samples info from filenames
datasetObject.addSampleInfo(descriptionFormat='filenames')

当多次增加元数据时，在sampleMetadata中已经存在的列的内容将被添加的元数据中的相同名称的列覆盖。请参阅 addSampleInfo()的文档，以获得可能的选项。

质量评估分析（Assessing Analytical Quality）

nPYc工具箱将分析质量的概念直接包含到Dataset的子类中。根据分析平台和操作流程（analytical platform and protocol）的不同，质量度量可以根据样本-样本（sample-by-sample）比较或特征-特征（feature-by-feature）比较来判断，或者同时根据两者来判断。

要生成质量分析的报告，请调用 generateReport() 函数，并用dataset对象作为参数：

nPYc.reports.generateReport(datasetObject, 'feature summary')

质量控制程序的参数可以在Dataset对象创建时候根据 SOP JSON文件进行详细的规定。同时，Dataset对象创建后，依然可以通过修改 Attributes字典中的相关条目来修改质量控制程序的参数

每个对象类型都支持自己的QC测试，请在 Preprocesssing & Quality-control of NMR profiling datasets、Preprocesssing & Quality-control of UPLC-MS profiling datasets和Preprocesssing & Quality-control of targeted datasets 中查看详细信息。

样品和变量的过滤（Filtering of samples & variables）

根据为每种类型的dataset定义的通用程序对特征（features）进行过滤，该过滤过程是根据从 SOP 中加载的阈值和在Attributes中定义的阈值，通过updateMasks()方法完成的。当该方法被调用的时候，在 featureMask中的元素（elements）被设置为False，表明特征（features）不符合质量标准；同时，对于哪些没有通过质量标准，或者样本类型和角色没有规定的样本，在 sampleMask中的元素（elements）将被设置为False。

updateMasks() 方法中默认参数将被用来过滤的dataset，最终只包含研究样本和研究参考样本，并且只有符合质量标准的特征（features）才能保留：

dataset.updateMasks(filterSamples=True, filterFeatures=True, sampleTypes=[SampleType.StudySample, SampleType.StudyPool], assayRoles=[AssayRole.Assay, AssayRole.PrecisionReference])

特定的样本或特征（samples or features）可以根据它们的 ID 或其他相关的元数据，通过excludeFeatures()和excludeSamples()方法排除。

上述两个方法是将在featureMask和sampleMask 向量中的相关的条目设置 为False来实现功能的，而且这种操作可以进一步分析中将样本或特征（samples or features）隐藏。从dataset中屏蔽的元素可以通过 applyMasks()方法永久删除。

归一化（Normalisation）

通过将normalisation子模块中的一个类附加到Dataset的Normalisation属性中，可以使对全局样本强度的稀释效应归一化。

默认情况下，新的Dataset 对象会有一个 NullNormaliser附上，而这不会实行归一化。我们需要通过为这个属性分配一个 Normaliser类的实例：

totalAreaNormaliser = nPYc.utilities.normalisation.TotalAreaNormaliser
dataset.Normalisation = totalAreaNormaliser

才能调用全部 intensityData，从而返回通过标准化程序（normaliser）转化的值。.

基本的多元可视化（Basic Multivariate Visualisation）

一个 Dataset的简单PCA模型可以通过multivariateQCreport()函数进行可视化。这个函数获得的报告将采用dataset的 pyChemomentrics PCA模型，使模型的得分和负载（scores and loadings）可视化，并根据提供的样本元数据，选择性的突出显示的对应的得分。

此外，可以通过 plotScoresInteractive() 和 plotLoadingsInteractive()函数，交互式地探索由multivariateQCreport() 生成的模型的得分和负载（scores and loadings）。

导出数据集（Exporting Datasets）

Dataset 对象可以导出为多种格式，以便导入到其他分析的包。另外，工具箱生成的自动报告可以保存为html文档，并包含一些图片。

保存报告（Saving reports）

由reports模块交互式生成的报告保存为带有静态图像的html文档，并可以通过generateReport()函数中的output=参数设置报告和图片的保存路径。

导出数据（Exporting data）

Datasets可以通过 exportDataset() 方法以多种格式导出。“UnifiedCSV”提供了一种良好的默认输出格式，将:-:~nPYc.objects.Dataset.sampleMetadata、 featureMetadata和 intensityData连接起来，作为一个单独的逗号分隔的文本文件输出。在这个文件中，以行为样本（samples ），以列为特征（features）。dataset中的特性（features）的数量可能导致一个文件中包含太多的列，导致只有某些软件包可以打开这个文件，幸运的是 “CSV ”参数允许我们将sampleMetadata、featureMetadata和 intensityData分别保存到一个 CSV 文件中。nPYc工具箱目前还支持以 ISATAB 格式导出元数据。