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

数据集类型（Dataset classes）

nPYc工具箱是围绕一个核心 Dataset 类构建的，它代表了一个度量集合，带有与每个样本相关联的生物和分析元数据，以及与观察值相关联的分析和化学元数据。

Dataset类及其子类的实例能够从常见的数据类型中实例化自己，包括某些原始数据格式、常见的交换格式和流行的数据处理工具的输出。

Dataset族类包括将额外元数据映射到对象的方法（参见 addSampleInfo()），并以各种格式导出Dataset（参见exportDataset() 方法）

Dataset 的子集都有三个主要的属性：

• sampleMetadata: 一个n x p的dataframe：包含n个 样本（sample）的一共p个标识符和元数据

• featureMetadata: 一个m x q的pandas的dataframe：包含m个特征（feature ）的一共q个标识符和元数据

• intensityData: 一个n x m的numpy矩阵：包含n个 样本（sample）和m个特征（feature ）之间的测量值

Fig. 1 一个Dataset 对象的关键属性的结构。值得注意的是，featureMetadata的Dataframe中的行对应于intensityData矩阵中的列。

当初始化时，可以通过从 sop中指定的 JSON 文件加载的 SOP parameters来配置Dataset 对象。然后将参数存储在Attributes 字典中。

Dataset

Dataset对象作为 MSDataset、TargetedDataset和NMRDataset共同的父集，通常不应该独立地实例化。

class nPYc.objects.Dataset(sop='Generic', sopPath=None, **kwargs)

nPYc dataset对象的基类。

• Parameters:

  • sop (str) – 从指定的SOP JSON文件加载配置参数

  • sopPath – 默认情况下，SOPs是从nPYc/StudyDesigns/SOP/目录中加载的。如果不是 None， 将会在内建的SOP目录之前，在 sopPath=指定的目录中进行检索。

• featureMetadata = None

  一个m x q的pandas的dataframe：包含m个特征（feature ）的一共q个标识符和元数据

  featureMetadata表可以包括任何可以存储在pandas cell中的数据类型。但是工具箱规定了一些列需要具备的要求，以便后续函数的分析：

  Column	dtype	Usage
  Feature Name	str or float	在这个列中展示了特征（feature）的 ID。每个“Feature Name”必须在表中是唯一的。如果“Feature Name”是数字，那么列应该按升序或降序排序。

• sampleMetadata = None

  一个n x p的dataframe：包含n个 样本（sample）的一共p个标识符和元数据。

  sampleMetadata表可以包括任何可以存储在pandas cell中的数据类型。但是工具箱规定了一些列需要具备的要求，以便后续函数的分析：

  Column	dtype	Usage
  Sampling ID	str	这个样本的sampling event的 ID
  AssayRole	AssayRole	定义了这个实验的角色
  SampleType	SampleType	定义获得的样本类型
  Sample File Name	str	分析数据的唯一文件名（Unique file name）
  Sample Base Name	str	连接分析数据和Sampling ID的通用标识符（Common identifier）
  Dilution	float	当AssayRole是LinearityReference的地方，这里显示了预期的丰度
  Batch	int	获取批次
  Correction Batch	int	当检测和纠正 batch和 Run-Order 效应时，运行顺序效应在样本共享相同的纠正批处理中被描述，而在不同的值之间检测到批处理效果。run-order效应将在共享相同Correction Batch的样本中进行刻画，同时，batch 效应在不同的值（distinct values）之间检测到根据
  Acquired Time	datetime.datetime	获取原始数据的日期和时间
  Run order	int	样品采集顺序
  Exclusion Details	str	标记为排除的详细原因
  Metadata Available	bool	是否可以从.addSampleInfo()方法获得样本的元数据记录

• featureMask = None

  包含m个元素的向量，其中 True表示用于分析的特性，False 表示排除在分析之外的元素

• sampleMask = None

  包含p个元素的向量，其中 True表示用于分析的样本，False 表示排除在分析之外的样本

• VariableType = None

  VariableType 会枚举所代表的指定数据类型

• Attributes = None

  对象配置属性的字典，包括从SOP 文件中加载的属性。

  定义的属性如下

  Key	dtype	Usage
  ‘dpi’	positive int	绘制图时的光栅分辨率
  ‘figureSize’	positive (float, float)	绘制图的大小
  ‘figureFormat’	str	图保存的格式
  ‘histBins’	positive int	绘制直方图时要使用的箱数
  ‘Feature Names’	Column in featureMetadata	主要“Feature Names”的 ID

• intensityData

  一个n x m的numpy矩阵：包含n个 样本（sample）和m个特征（feature ）之间的测量值

• noSamples

  Returns：在dataset (n)中的样本数量

  Return type：int

• noFeatures

  Returns：在dataset (m)中的特征数量

  Return type：int

  Returns:Number of features in the dataset (m)Return type:int

• log

  以字符串形式返回日志条目

• name

  返回或者重设dataset的名字，名称必须是字符串（string）格式

• Normalisation

  Normaliser 对象用于转换intensityData中的测量值

• validateObject(verbose=True, raiseError=False, raiseWarning=True)

  检查类定义中指定的所有属性是否存在，以及所需的类或值。检查属性是否存在以及类型。检查强制列的存在，但是不检查列值（类型或唯一性）。如果“sampleMetadataExcluded”、“intensityDataExcluded”、“featureMetadataExcluded” 或者“excludedFlag”存在， 则会检查排除的存在和数量（基于“sampleMetadataExcluded”）

  Parameters:

  • verbose (bool) – 如果是True，每个检查的结果都被打印出来（默认为True）

  • raiseError (bool) – 如果是True，在检查失败且验证被中断时打印错误（默认为False）

  • raiseWarning (bool) – 如果是True，检查失败时会发出警告

  Returns：当检查对象符合基本的 Dataset，返回 True

  Return type：bool

  Raises:

  • TypeError – 如果Object class是错误的

  • AttributeError – 如果self.Attributes不存在

  • TypeError – 如果self.Attributes不是一个字典

  • AttributeError – 如果self.Attributes[‘Log’] 不存在

  • TypeError – 如果self.Attributes[‘Log’] 不是一个列表

  • AttributeError – 如果self.Attributes[‘dpi’] 不存在

  • TypeError – 如果self.Attributes[‘dpi’] 不是一个整数

  • AttributeError – 如果self.Attributes[‘figureSize’]不存在

  • TypeError – 如果self.Attributes[‘figureSize’] 不是一个列表

  • ValueError – 如果self.Attributes[‘figureSize’]的长度不是2

  • TypeError – 如果self.Attributes['figureSize'][0]不是整数或者浮点数（int or float）

  • TypeError – 如果self.Attributes['figureSize'][1]不是整数或者浮点数（int or float）

  • AttributeError – 如果self.Attributes[‘figureFormat’] 不存在

  • TypeError – 如果self.Attributes[‘figureFormat’] 不是一个字符串（str）

  • AttributeError – 如果self.Attributes[‘histBins’] 不存在

  • TypeError – 如果self.Attributes[‘histBins’]不是一个整数

  • AttributeError – 如果self.Attributes[‘noFiles’]不存在

  • TypeError – 如果self.Attributes[‘noFiles’]不是一个整数

  • AttributeError –如果self.Attributes[‘quantiles’] 不存在

  • TypeError – 如果self.Attributes[‘quantiles’]不是一个列表

  • ValueError – 如果self.Attributes[‘quantiles’] 的长度不是2

  • TypeError – 如果self.Attributes['quantiles'][0]不是整数或者浮点数（int or float）

  • TypeError – 如果self.Attributes['quantiles'][1]不是整数或者浮点数（int or float）

  • AttributeError – 如果self.Attributes[‘sampleMetadataNotExported’] 不存在

  • TypeError – 如果self.Attributes[‘sampleMetadataNotExported’]不是一个列表

  • AttributeError – 如果self.Attributes[‘featureMetadataNotExported’]不存在

  • TypeError – 如果self.Attributes[‘featureMetadataNotExported’] 不是一个列表

  • AttributeError – 如果self.Attributes[‘analyticalMeasurements’] 不存在

  • TypeError – 如果self.Attributes[‘analyticalMeasurements’] 不是一个字典

  • AttributeError – 如果self.Attributes[‘excludeFromPlotting’]不存在

  • TypeError – 如果self.Attributes[‘excludeFromPlotting’] 不是一个列表

  • AttributeError – 如果self.VariableType不存在

  • AttributeError – 如果self._Normalisation不存在

  • TypeError – 如果self._Normalisation不是 Normaliser ABC

  • AttributeError – 如果self._name不存在

  • TypeError – 如果self._name不是一个字符串

  • AttributeError – 如果 self._intensityData不存在

  • TypeError – 如果self._intensityData不是一个 numpy.ndarray

  • AttributeError – 如果self.sampleMetadata不存在

  • TypeError – 如果self.sampleMetadata 不是一个pandas.DataFrame

  • LookupError – 如果self.sampleMetadata 没有一个 ”Sample File Name“列

  • LookupError – 如果 self.sampleMetadata 没有一个 ”AssayRole“列

  • LookupError – 如果self.sampleMetadata 没有一个 ”SampleType “列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Dilution “列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Batch “列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Correction Batch“列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Run Order“列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Sampling ID“列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Sample Base Name“列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Acquired Time“列

  • LookupError – 如果self.sampleMetadata 没有一个 ”Exclusion Details“列

  • AttributeError – 如果self.featureMetadata不存在

  • TypeError – 如果self.featureMetadata 不是一个pandas.DataFrame

  • LookupError – 如果self.featureMetadata 没有一个 ”Feature Name“列

  • AttributeError – 如果self.sampleMask 不存在

  • TypeError – 如果self.sampleMask 不是一个numpy.ndarray

  • ValueError –如果self.sampleMask 不是布尔型（bool）

  • AttributeError – 如果 self.featureMask不存在

  • TypeError – 如果 self.featureMask 不是一个numpy.ndarray

  • ValueError – 如果self.featureMask 不是布尔型（bool）

  • AttributeError – 如果self.sampleMetadataExcluded 不存在

  • TypeError – 如果self.sampleMetadataExcluded不是一个列表

  • AttributeError – 如果self.intensityDataExcluded不存在

  • TypeError – 如果self.intensityDataExcluded不是一个列表

  • ValueError – 如果self.intensityDataExcluded 与self.sampleMetadataExcluded排除的数量不相同

  • AttributeError – 如果self.featureMetadataExcluded不存在

  • TypeError – 如果self.featureMetadataExcluded 不是一个列表

  • ValueError – 如果self.featureMetadataExcluded 与self.sampleMetadataExcluded排除的数量不相同

  • AttributeError – 如果self.excludedFlag 不存在

  • TypeError – 如果self.excludedFlag不是一个列表

  • ValueError – 如果self.excludedFlag与self.sampleMetadataExcluded排除的数量不相同

• initialiseMasks()

  重新初始化featureMask和 sampleMask来匹配当前intensityData的规模，并包含所有的样本。

• updateMasks(filterSamples=True, filterFeatures=False, sampleTypes=[<SampleType.StudySample>, <SampleType.StudyPool>], assayRoles=[<AssayRole.Assay>, <AssayRole.PrecisionReference>], kwargs)

  根据参数更新 sampleMask 和 featureMask 。

  哪些不符合分析标准的条目，updateMasks()将在 sampleMask 或者 featureMask 上设置为False 。

  注意：

  为了避免重新引入手工排除的项目，这种方法只会将条目设置为False。因此，如果您希望从更严格的标准转移到不那么严格的集合，您将需要使用 initialiseMasks()来重置所有的条目True。

  Parameters：

  • filterSamples (bool) – 如果是 False 不修改 sampleMask

  • filterFeatures (bool) – 如果是 False 不修改 featureMask

  • sampleTypes (SampleType) – 要保留的样本类型列表

  • sampleRoles (AssayRole) – 要保留的assays roles列表

• applyMasks()

  根据sampleMask 和 featureMask（那些设置为False）的设置永久删除屏蔽的元素, 而这些设置是根据 featureMetadata、sampleMetadata和 intensityData的信息来的。

• addSampleInfo(descriptionFormat=None, filePath=None, **kwargs)

  加载额外的元数据并将其映射到 sampleMetadata表

  可能的选项：

  • ‘NPC LIMS’：NPC LIMS文件将原始分析数据的名称映射到样本 IDs

  • ‘NPC Subject Info’ ：从NPC样本清单文件（在PCSOP.082中定义的格式）映射主题元数据

  • ‘Raw Data’ ：从原始数据文件中提取分析参数

  • ‘ISATAB’ ：ISATAB研究设计

  • ‘Filenames’ ：根据在 filenamespec 中传递的正则表达式中的铺货的信息，从文件名中解析样本信息

  • ‘Basic CSV’ ：将在 filePath= 中的csv 文件的内容加入到 sampleMetadata 表中，通过两个表格中的”Sample File Name“列完成匹配（具体参考Basic CSV Sample Metadata Import）。

  Parameters：

  • descriptionFormat (str) – 要添加的元数据格式

  • filePath (str) – 要添加的附加数据的路径

  Raises：

  • NotImplementedError – 如果不理解描述的格式

• addFeatureInfo(filePath=None, descriptionFormat=None, featureId=None, **kwargs)

  加载额外的元数据并将其映射到 featureMetadata表。

  可能的选项:

  • ‘Reference Ranges’ 为一个特征（feature）指定上下参考范围的 JSON 文件

  Parameters：

  • filePath (str) – 要添加的附加数据的路径

  • descriptionFormat (str) –

  • featureId (str) – 提供与内部特征名称（internal Feature Name）匹配的元数据文件中的惟一特征 ID 字段（Unique feature Id field）

  Raises：

  • NotImplementedError – 如果不理解描述的格式

• excludeSamples(sampleList, on='Sample File Name', message='User Excluded')

  如果样品出现在 sampleList 中，则将在 sampleMask中将对应的样本设为False，以将其从dataset中屏蔽。

  Parameters：

  • sampleList (list) – 将被排除的样本 IDs 列表

  • on (str) – sampleMetadata中用来与 sampleList 相匹配的列的名称，默认为“Sample File Name”

  • message (str) – 将消息附加到每一个将被排除的样本的“Exclusion Details”字段，默认信息为“User Excluded”

  Returns：一个 IDs 列表，主要是 sampleList 无法与现有的样本 IDs匹配的 IDs

  Return type：list

• excludeFeatures(featureList, on='Feature Name', message='User Excluded')

  从dataset中排除 featureList 中列出的特征（features）

  Parameters：

  • sampleList (list) – 将被排除的特征 IDs 列表

  • on (str) – featureMetadata中用来与 featureList 相匹配的列的名称，默认为“Feature Name”

  • message (str) – 将消息附加到每一个将被排除的特征的“Exclusion Details”字段，默认信息为“User Excluded”

  Returns：一个 IDs 列表，主要是 featureList无法与现有的特征 IDs匹配的 IDs

  Return type：list

• exportDataset(destinationPath='.', saveFormat='CSV', isaDetailsDict={}, withExclusions=True, escapeDelimiters=False, filterMetadata=True)

  以各种格式导出dataset对象，以便导入到其他软件中，根据dataset对象的 name 属性命名导出。

  可能的保存格式：

  • CSV ：基础的CSV 输出， featureMetadata、 sampleMetadata 和intensityData 输出三个独立的 CSV 文件，并保存在desitinationPath指定的目录下

  • UnifiedCSV ：将featureMetadata、sampleMetadata 和intensityData 合并输出到一个单独的 CSV 文件中。

  • ISATAB ：将 sampleMetadata以 ISATAB 格式导出

  Parameters：

  • destinationPath (str) – 将数据保存到这里指定的目录中

  • format (str) – 保存数据的文件格式，默认为CSV

  • withExclusions (bool) – 如果是True，标记的特征和样本将被排除在外

  • escapeDelimiters (bool) – 如果是True，从元数据中删除csv文件中常用的分隔符

  • filterMetadata (bool) – 将数据保存到，不导出在出现 self.Attributes[‘sampleMetadataNotExported’] 和 self.Attributes[‘featureMetadataNotExported’] 中的sampleMetadata 和 featureMetadata 的列的信息

  • detailsDict (dict) – 包含几个键：用于导出 ISATAB 的值对

    ## detailsDict的格式：
    detailsDict = {
        'investigation_identifier': “i1”,
        'investigation_title': "Give it a title",
        'investigation_description': "Add a description",
        'investigation_submission_date': "2016-11-03",
        'investigation_public_release_date': "2016-11-03",
        'first_name': "Noureddin",
        'last_name': "Sadawi",
        'affiliation': "University",
        'study_filename': "my_ms_study",
        'study_material_type': "Serum",
        'study_identifier': "s1",
        'study_title': "Give the study a title",
        'study_description': "Add study description",
        'study_submission_date': "2016-11-03",
        'study_public_release_date': "2016-11-03",
        'assay_filename': "my_ms_assay"
    }

  Raises：

  • ValueError – 如果 saveFormat 无法理解

• getFeatures(featureIDs, by=None, useMasks=True)

  根据名称或一定的区间获得一个特征或特征列表。

  如果 VariableType 是 Discrete，getFeature() 预期是一个值或值列表，并且返回匹配的特性。

  如果VariableType 是 Spectral，可以传递单个元组（min、max）或元组（min、max）的列表，返回的是一个元组之间的范围的特征。如果传递的元组之间存在重叠，则会返回并集的结果。

  Parameters：

  • featureIDs – 将要返回的单个特征 ID或特征 ID 的列表

  • by (None or str) – 用来搜索的 featureMetadata 列名；如果是 None ，将用 Attributes[‘Feature Names’]中定义的列来搜索

  Returns：(featureMetadata, intensityData)

  Return type：(pandas.Dataframe, numpy.ndarray)

MSDataset

class nPYc.objects.MSDataset(datapath, fileType='QI', sop='GenericMS', **kwargs)

MSDataset扩展了 Dataset，以表示 peak-picked LC- or DI-MS datasets（离散变量）和连续模式（光谱） 的 DI-MS datasets。

对象可以从各种常见的数据格式中进行初始化，当前，peak-picked数据是来自rogenesis QI 、 XCMS 、或者targeted Biocrates datasets。

• Progenesis QI

  QI 导入的是 CSV 文件，而这个文件是通过 QI 的菜单栏选项中的“Export Compound Measurements”导出的。导入需要同时存在归一化的datasets和原始的datasets，但只会导入原始的测量值（meaturenents）。

• XCMS

  XCMS导入的是 CSV 文件，默认情况下，这个文件中14列的特征参数，但是我们可以通过 noFeatureParams= 的关键字参数调整文件中需要的特征参数的列的数量

• Biocrates

  Biocrates导入的是由Biocrates MetIDQ导出的电子表格。默认情况下，从名为“Data Export”的表格中加载数据，但是我们也可以通过sheetName=参数指定导入表达的名称。如果样本元数据的列的数量与默认值不同，可以使用noSampleParams=修改导入的样本元数据的列的数量。

• correlationToDilution

  返回特征与按样本计算的稀释（dilution）的相关性，其中样本在sampleMetadata中被标记为“Dilution Series”，并在“Dilution”中有稀释的值

  Returns：特征与稀释相关性的向量（Vector of feature correlations to dilution）

  Return type：numpy.ndarray

• artifactualLinkageMatrix

  获得得到重叠的人为特征（overlapping artifactual features）

• rsdSP

  根据sampleMetadata，对 Assay Role 是PrecisionReference 和 Sample Type 是StudyPool 的样本进行分析，返回dataset中每一个特征的相对标准偏差（ relative standard deviations）的百分比

  Returns：特征相对标准偏差的向量（Vector of feature RSDs）

  Return type：numpy.ndarray

• applyMasks()

  根据sampleMask 和 featureMask（那些设置为False）的设置永久删除屏蔽的元素, 而这些设置是根据 featureMetadata、 sampleMetadata 和 intensityData的信息来的。

• updateMasks(filterSamples=True, filterFeatures=True, sampleTypes=[<SampleType.StudySample>, <SampleType.StudyPool>], assayRoles=[<AssayRole.Assay>, <AssayRole.PrecisionReference>], correlationThreshold=None, rsdThreshold=None, varianceRatio=None, withArtifactualFiltering=None, deltaMzArtifactual=None, overlapThresholdArtifactual=None, corrThresholdArtifactual=None, blankThreshold=None, aggregateRedundantFeatures=False, kwargs)

  根据QC参数更新 sampleMask 和 featureMask 。

  哪些不符合分析标准的条目，updateMasks()将在 sampleMask 或者 featureMask 上设置为False 。

  注意：

  为了避免重新引入手工排除的项目，这种方法只会将条目设置为False。因此，如果您希望从更严格的标准转移到不那么严格的集合，您将需要使用 initialiseMasks()来重置所有的条目True。

  Parameters：

  • filterSamples (bool) – 如果是 False ，不修改 sampleMask

  • filterFeatures (bool) – 如果是 False ，不修改 featureMask

  • sampleTypes (SampleType) – 要保留的样本类型列表

  • assayRoles (AssayRole) – 要保留的assays roles列表

  • correlationThreshold (None or float) – 屏蔽相关性（correlation ）低于这个值的特征。如果是 None， 使用来自 Attributes[‘corrThreshold’] 的值

  • rsdThreshold (None or float) – 屏蔽RSD 低于这个值的特征。如果是 None， 使用来自 Attributes[‘rsdThreshold’] 的值

  • varianceRatio (None or float) – 比较研究样本（study samples）中测定的RSD与在研究参考样本（study reference samples ）中测定的RSD和varianceRatio*相乘的值的大小，如果小于，则屏蔽这些特征

  • withArtifactualFiltering (None or bool) – 如果是 None ，使用来自 Attributes['artifactualFilter']的值。如果是 False，则不执行人为信号（artifactual）的过滤。如果 Attributes['artifactualFilter'] 被设置为 False， 人为信号（artifactual）的过滤将不会发生，即使 withArtifactualFiltering被设置为 True.

  • deltaMzArtifactual (None or float) – Maximum allowed m/z distance between two grouped features. If None, use the value from Attributes[‘deltaMzArtifactual’]

  • overlapThresholdArtifactual (None or float) – Minimum peak overlap between two grouped features. If None, use the value from Attributes[‘overlapThresholdArtifactual’]

  • corrThresholdArtifactual (None or float) – Minimum correlation between two grouped features. If None, use the value from Attributes[‘corrThresholdArtifactual’]

  • blankThreshold (None**, False**, or float) – Mask features thats median intesity falls below blankThreshold x the level in the blank. If False do not filter, if None use the cutoff from Attributes[‘blankThreshold’], otherwise us the cutoff scaling factor provided