ts_ids_components.pcr package#
Module contents#
This module contains components for quantitative PCR (qPCR) and digital PCR (dPCR) IDSs.
Polymerase Chain Reaction (PCR) and quantitative DNA analysis#
Polymerase chain reaction (PCR) takes advantage of a thermally activated DNA chemistry to repeatedly replicate (or amplify) target DNA sequences for quantitative analysis. Specificity is achieved by designing primers tailored to a target sequence, combined with a fluorescent mechanism that produces a signal on a successful reaction thus indicating the presence of the target sequence.
In conventional “real-time” or quantitative PCR (qPCR), targets in a sample are amplified in batch producing a fluorescent signal proportional to the target amplicons (amplified DNA). The signal is measured in “real-time” at the end of each amplification cycle and, briefly stated, fit to an exponential model to estimate the initial abundance. Typically, an experiment is designed to provide a “relative quantification” measure of target abundance, compared to that of a stable reference gene or reference sample using the delta-cycle-threshold (ΔCt) and delta-delta-cycle-threshold (ΔΔCt) methods respectively. Alternatively an “absolute quantification” experiment can be performed by comparing the target signal to a “standard curve” generated from samples with known concentrations of the target DNA. Correct quantification here is sensitive to target-specific amplification efficiencies and the quality of the standard library.
Digital PCR (dPCR), including digital droplet PCR (ddPCR), is a more recent technology able to isolate and amplify individual DNA molecules in a high-throughput fashion and then count all reactions in a sample for a positive or negative signal indicating presence of a target sequence. Directly counting discrete reactions in a sample enables a more straight-forward derivation of target abundance.
For both techniques the methods describing PCR chemistry with target and reporter specifications are very similar, though how results are calculated and reported are unique.
The IDS components presented here were designed to capture methods and results from PCR experiments and should be used to transform data from disparate instrument vendors/models into a consistent format. Notably absent is a structure representing the PCR thermocycling parameters, these are often not included in data exports. Please contact TetraScience to discuss a use-case requiring an update to this standard.
Methods components#
The PcrMethodsTarget component is built to hold relevant experimental setup information around a molecular target.
In both qPCR and dPCR experiments this typically includes information on the target type (e.g. a Reference or
Unknown) and the reporter & quencher chemistry used to develop a reaction signal. Optionally, a
reference target name and/or reference copy number may be required for some experimental setups (e.g Copy Number Variation
or Relative Quantification).
Quantitative PCR (qPCR) results components#
The QPcrResultsTarget component holds results pertaining to a single target within a qPCR experiment.
This includes the cycle_threshold (Ct) and control normalized delta_cycle_threshold (ΔCt) which are typically calculated for
each target. Optional standard_curve parameters can also be set depending on the experiment design.
For relative quantification experiments the delta_delta_cycle_threshold (ΔΔCt) and relative_quantity values are determined. For an absolute quantification experiment the absolute_quantity can be set as well as a standard_curve for the reference sample targets.
Digital PCR (dPCR) results components#
The DPcrResultsTarget component holds results for an individual target within a dPCR sample.
This includes the fluorescent intensity threshold, from which each reaction is determined to be positive or negative,
the count of all reactions in a sample, the derived concentration of the target and when appropriate the copy number variation.
Building a custom IDS data schema#
Here is an example of defining a dPCR schema from these components and populating it in Python. This shows data being manually populated in the script itself, but in typical usage, this data would be parsed from a raw data file. Note the addition of foreign key fields to the ResultsTarget object linking to the appropriate Sample and MethodsTarget.
from typing import ClassVar, List
from ts_ids_core.annotations import Required, UUIDForeignKey
from ts_ids_core.schema import (
IdsField,
Location,
RawValueUnit,
SchemaExtraMetadataType,
TetraDataSchema,
)
from typing_extensions import Literal
from ts_ids_components.pcr import DPcrResultsTarget as BaseResultsTarget
from ts_ids_components.pcr import PcrMethodsTarget, ReactionMeasure
from ts_ids_components.plate_reader import PlateReaderSample
# Define a digital pcr model which only uses the defaults provided by PlateReaderSchema
namespace = "private-xyz"
ids_slug_name = "demo-dpcr"
version = "v1.0.0"
class DPcrResultsTarget(BaseResultsTarget):
"""DPcrResultsTarget with a fk to a method target"""
fk_sample: UUIDForeignKey = IdsField(
primary_key="/properties/samples/items/properties/pk",
description="Foreign key to the corresponding item in `samples[*]`",
)
fk_methods_target: UUIDForeignKey = IdsField(
primary_key="/properties/methods_targets/items/properties/pk",
description="Foreign key to the corresponding item in `methods_targets[*]`",
)
class DigitalPcrModel(TetraDataSchema):
schema_extra_metadata: ClassVar[SchemaExtraMetadataType] = {
"$id": f"https://ids.tetrascience.com/{namespace}/{ids_slug_name}/{version}/schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
}
ids_type: Required[Literal[ids_slug_name]] = IdsField(
default=ids_slug_name, alias="@idsType"
)
ids_version: Required[Literal[version]] = IdsField(
default=version, alias="@idsVersion"
)
ids_namespace: Required[Literal[namespace]] = IdsField(
default=namespace, alias="@idsNamespace"
)
samples: List[PlateReaderSample]
methods_targets: List[PcrMethodsTarget]
results_targets: List[DPcrResultsTarget]
# Example UUIDs - these would come from a UUID generator in a task script
uuid1 = "abc00000-0000-0000-0000-000000000001"
uuid2 = "abc00000-0000-0000-0000-000000000002"
uuid3 = "abc00000-0000-0000-0000-000000000003"
# Populate the model with example data
instance = DigitalPcrModel(
samples=[
PlateReaderSample(
pk=uuid1,
id_="sample_in_well_A01",
location=Location(position="A01"),
),
],
methods_targets=[
PcrMethodsTarget(
pk=uuid2,
name="Target 1",
type="Reference",
reporter_name="FAM",
quencher_name="NFQ-MGB",
),
PcrMethodsTarget(
pk=uuid3,
name="Target 2",
type="Unknown",
reporter_name="VIC",
quencher_name="NFQ-MGB",
reference_target_name="Target 1",
reference_copies=RawValueUnit(raw_value="2", value=2.0, unit="Count"),
),
],
results_targets=[
DPcrResultsTarget(
fk_sample=uuid1,
fk_methods_target=uuid2,
threshold=RawValueUnit(
raw_value="500.5", value=500.5, unit="Intensity"
),
concentration=RawValueUnit(
raw_value="5", value=5.0, unit="CountPerMicroliter"
),
accepted_reactions=ReactionMeasure(
count=20000,
mean_amplitude=RawValueUnit(
raw_value="500.5", value=500.5, unit="Intensity"
),
),
positive_reactions=ReactionMeasure(
count=1000,
mean_amplitude=RawValueUnit(
raw_value="987.9", value=987.9, unit="Intensity"
),
),
negative_reactions=ReactionMeasure(
count=19000,
mean_amplitude=RawValueUnit(
raw_value="123", value=123.0, unit="Intensity"
),
),
),
DPcrResultsTarget(
fk_sample=uuid1,
fk_methods_target=uuid3,
threshold=RawValueUnit(raw_value="110", value=110.0, unit="Intensity"),
concentration=RawValueUnit(
raw_value="10", value=10.0, unit="CountPerMicroliter"
),
accepted_reactions=ReactionMeasure(
count=20000,
mean_amplitude=RawValueUnit(
raw_value="555.5", value=555.5, unit="Intensity"
),
),
positive_reactions=ReactionMeasure(
count=2000,
mean_amplitude=RawValueUnit(
raw_value="987.9", value=987.9, unit="Intensity"
),
),
negative_reactions=ReactionMeasure(
count=18000,
mean_amplitude=RawValueUnit(
raw_value="123", value=123.0, unit="Intensity"
),
),
copy_number_variation=RawValueUnit(
raw_value="4.01", value=4.01, unit="Count"
),
),
],
)
Then, the data could be dumped to JSON by calling instance.model_dump_json(indent=2)
The resulting IDS JSON looks like this:
{
"@idsType": "demo-dpcr",
"@idsVersion": "v1.0.0",
"@idsNamespace": "private-xyz",
"samples": [
{
"id": "sample_in_well_A01",
"location": {
"position": "A01"
},
"pk": "abc00000-0000-0000-0000-000000000001"
}
],
"methods_targets": [
{
"pk": "abc00000-0000-0000-0000-000000000002",
"name": "Target 1",
"type": "Reference",
"reporter_name": "FAM",
"quencher_name": "NFQ-MGB"
},
{
"pk": "abc00000-0000-0000-0000-000000000003",
"name": "Target 2",
"type": "Unknown",
"reporter_name": "VIC",
"quencher_name": "NFQ-MGB",
"reference_target_name": "Target 1",
"reference_copies": {
"value": 2.0,
"unit": "Count",
"raw_value": "2"
}
}
],
"results_targets": [
{
"threshold": {
"value": 500.5,
"unit": "Intensity",
"raw_value": "500.5"
},
"concentration": {
"value": 5.0,
"unit": "CountPerMicroliter",
"raw_value": "5"
},
"accepted_reactions": {
"count": 20000,
"mean_amplitude": {
"value": 500.5,
"unit": "Intensity",
"raw_value": "500.5"
}
},
"positive_reactions": {
"count": 1000,
"mean_amplitude": {
"value": 987.9,
"unit": "Intensity",
"raw_value": "987.9"
}
},
"negative_reactions": {
"count": 19000,
"mean_amplitude": {
"value": 123.0,
"unit": "Intensity",
"raw_value": "123"
}
},
"fk_sample": "abc00000-0000-0000-0000-000000000001",
"fk_methods_target": "abc00000-0000-0000-0000-000000000002"
},
{
"threshold": {
"value": 110.0,
"unit": "Intensity",
"raw_value": "110"
},
"concentration": {
"value": 10.0,
"unit": "CountPerMicroliter",
"raw_value": "10"
},
"accepted_reactions": {
"count": 20000,
"mean_amplitude": {
"value": 555.5,
"unit": "Intensity",
"raw_value": "555.5"
}
},
"positive_reactions": {
"count": 2000,
"mean_amplitude": {
"value": 987.9,
"unit": "Intensity",
"raw_value": "987.9"
}
},
"negative_reactions": {
"count": 18000,
"mean_amplitude": {
"value": 123.0,
"unit": "Intensity",
"raw_value": "123"
}
},
"copy_number_variation": {
"value": 4.01,
"unit": "Count",
"raw_value": "4.01"
},
"fk_sample": "abc00000-0000-0000-0000-000000000001",
"fk_methods_target": "abc00000-0000-0000-0000-000000000003"
}
]
}
- Model PcrMethodsTarget[source]#
Bases:
IdsElementMethod information for a PCR Target
Show JSON schema
{ "description": "Method information for a PCR Target", "type": "object", "properties": { "pk": { "@primary_key": true, "description": "Primary key of a methods target", "type": "string" }, "name": { "description": "Name of the target. Can be descriptive or an index, e.g. '1', 'GAPDH'", "type": [ "string", "null" ] }, "type": { "description": "Type description of target in experimental context, e.g. 'Reference', 'Unknown'", "type": [ "string", "null" ] }, "reporter_name": { "description": "Name of the reporter or dye used in the reaction, e.g. 'FAM', 'HEX'", "type": [ "string", "null" ] }, "quencher_name": { "description": "Name of any quencher used in the reaction, e.g. 'NFQ-MGB', 'QSY'", "type": [ "string", "null" ] }, "reference_target_name": { "description": "Name of any reference target if applicable, may reference another MethodsTarget.name. Could contain a house-keeping gene or CNV normalization target.", "type": [ "string", "null" ] }, "reference_copies": { "$ref": "#/definitions/RawValueUnit", "description": "Known copy number of the reference target in a CNV calculation if applicable" } }, "additionalProperties": false, "required": [ "pk" ], "definitions": { "RawValueUnit": { "additionalProperties": false, "description": "A value with a unit, including the raw representation of the value from the primary data.", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] } }, "required": [ "value", "unit", "raw_value" ], "type": "object" } } }
- Validators:
- field pk: str#
Primary key of a methods target
- Constraints:
func = <function validate_uuid at 0x7f83f18f3550>
json_schema_input_type = PydanticUndefined
- field reference_copies: RawValueUnit#
Known copy number of the reference target in a CNV calculation if applicable
- field reference_target_name: str | None#
Name of any reference target if applicable, may reference another MethodsTarget.name. Could contain a house-keeping gene or CNV normalization target.
- Model ReactionMeasure[source]#
Bases:
IdsElementResult count data for a droplet measurement
Show JSON schema
{ "description": "Result count data for a droplet measurement", "type": "object", "properties": { "count": { "description": "Count of characteristic reaction", "type": [ "integer", "null" ] }, "mean_amplitude": { "$ref": "#/definitions/RawValueUnit", "description": "Mean amplitude of the reactions" } }, "additionalProperties": false, "definitions": { "RawValueUnit": { "additionalProperties": false, "description": "A value with a unit, including the raw representation of the value from the primary data.", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] } }, "required": [ "value", "unit", "raw_value" ], "type": "object" } } }
- Validators:
- field mean_amplitude: RawValueUnit#
Mean amplitude of the reactions
- Model DPcrResultsTarget[source]#
Bases:
IdsElementdPCR Result Target values from raw data
Show JSON schema
{ "description": "dPCR Result Target values from raw data", "type": "object", "properties": { "threshold": { "$ref": "#/definitions/RawValueUnit", "description": "Fluorescent intensity threshold for positive/negative determination" }, "concentration": { "$ref": "#/definitions/RawValueUnit", "description": "Concentration of the target in the sample" }, "accepted_reactions": { "$ref": "#/definitions/ReactionMeasure", "description": "Count of accepted reactions" }, "positive_reactions": { "$ref": "#/definitions/ReactionMeasure", "description": "Count of positive reactions" }, "negative_reactions": { "$ref": "#/definitions/ReactionMeasure", "description": "Count of negative reactions" }, "copy_number_variation": { "$ref": "#/definitions/RawValueUnit", "description": "Copy number variation of the target if applicable" } }, "additionalProperties": false, "definitions": { "RawValueUnit": { "additionalProperties": false, "description": "A value with a unit, including the raw representation of the value from the primary data.", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] } }, "required": [ "value", "unit", "raw_value" ], "type": "object" }, "ReactionMeasure": { "additionalProperties": false, "description": "Result count data for a droplet measurement", "properties": { "count": { "description": "Count of characteristic reaction", "type": [ "integer", "null" ] }, "mean_amplitude": { "$ref": "#/definitions/RawValueUnit", "description": "Mean amplitude of the reactions" } }, "type": "object" } } }
- Validators:
- field accepted_reactions: ReactionMeasure#
Count of accepted reactions
- field concentration: RawValueUnit#
Concentration of the target in the sample
- field copy_number_variation: RawValueUnit#
Copy number variation of the target if applicable
- field negative_reactions: ReactionMeasure#
Count of negative reactions
- field positive_reactions: ReactionMeasure#
Count of positive reactions
- field threshold: RawValueUnit#
Fluorescent intensity threshold for positive/negative determination
- Model RawValueUnitStatistics[source]#
Bases:
RawValueUnitValue Unit Mean Standard Deviation information.
Show JSON schema
{ "description": "Value Unit Mean Standard Deviation information.", "type": "object", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] }, "mean": { "$ref": "#/definitions/RawValueUnit", "description": "Mean value of the data" }, "standard_deviation": { "$ref": "#/definitions/RawValueUnit", "description": "Standard deviation of the data" } }, "additionalProperties": false, "required": [ "value", "unit", "raw_value" ], "definitions": { "RawValueUnit": { "additionalProperties": false, "description": "A value with a unit, including the raw representation of the value from the primary data.", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] } }, "required": [ "value", "unit", "raw_value" ], "type": "object" } } }
- Validators:
- field mean: RawValueUnit#
Mean value of the data
- field standard_deviation: RawValueUnit#
Standard deviation of the data
- Model QPcrStandardCurve[source]#
Bases:
IdsElementStandard Curve information.
Show JSON schema
{ "description": "Standard Curve information.", "type": "object", "properties": { "y_intercept": { "$ref": "#/definitions/RawValueUnit", "description": "Y-intercept of the standard curve" }, "slope": { "$ref": "#/definitions/RawValueUnit", "description": "Slope of the standard curve" }, "efficiency": { "$ref": "#/definitions/RawValueUnit", "description": "Amplification efficiency from the standard curve" }, "r_squared": { "$ref": "#/definitions/RawValueUnit", "description": "R-squared value of the standard curve" } }, "additionalProperties": false, "definitions": { "RawValueUnit": { "additionalProperties": false, "description": "A value with a unit, including the raw representation of the value from the primary data.", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] } }, "required": [ "value", "unit", "raw_value" ], "type": "object" } } }
- Validators:
- field efficiency: RawValueUnit#
Amplification efficiency from the standard curve
- field r_squared: RawValueUnit#
R-squared value of the standard curve
- field slope: RawValueUnit#
Slope of the standard curve
- field y_intercept: RawValueUnit#
Y-intercept of the standard curve
- Model QPcrResultsTarget[source]#
Bases:
IdsElementqPCR Result Target values from raw data
Show JSON schema
{ "description": "qPCR Result Target values from raw data", "type": "object", "properties": { "cycle_threshold": { "$ref": "#/definitions/RawValueUnitStatistics", "description": "Cycle threshold (Ct) value for the target" }, "delta_cycle_threshold": { "$ref": "#/definitions/RawValueUnitStatistics", "description": "Control normalized delta cycle threshold (\u0394Ct) value" }, "delta_delta_cycle_threshold": { "$ref": "#/definitions/RawValueUnitStatistics", "description": "Delta delta cycle threshold (\u0394\u0394Ct) value to derive relative quantification" }, "standard_curve": { "$ref": "#/definitions/QPcrStandardCurve", "description": "Standard curve parameters created for this target if applicable" }, "relative_quantity": { "$ref": "#/definitions/RawValueUnitStatistics", "description": "Relative quantity value for relative quantification if applicable " }, "absolute_quantity": { "$ref": "#/definitions/RawValueUnitStatistics", "description": "Absolute quantity value for absolute quantification from a known standard curve value if applicable" } }, "additionalProperties": false, "definitions": { "QPcrStandardCurve": { "additionalProperties": false, "description": "Standard Curve information.", "properties": { "y_intercept": { "$ref": "#/definitions/RawValueUnit", "description": "Y-intercept of the standard curve" }, "slope": { "$ref": "#/definitions/RawValueUnit", "description": "Slope of the standard curve" }, "efficiency": { "$ref": "#/definitions/RawValueUnit", "description": "Amplification efficiency from the standard curve" }, "r_squared": { "$ref": "#/definitions/RawValueUnit", "description": "R-squared value of the standard curve" } }, "type": "object" }, "RawValueUnit": { "additionalProperties": false, "description": "A value with a unit, including the raw representation of the value from the primary data.", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] } }, "required": [ "value", "unit", "raw_value" ], "type": "object" }, "RawValueUnitStatistics": { "additionalProperties": false, "description": "Value Unit Mean Standard Deviation information.", "properties": { "value": { "description": "A numerical value.", "type": [ "number", "null" ] }, "unit": { "description": "Unit for the numerical value.", "type": [ "string", "null" ] }, "raw_value": { "description": "The raw, untransformed value from the primary data.", "type": [ "string", "null" ] }, "mean": { "$ref": "#/definitions/RawValueUnit", "description": "Mean value of the data" }, "standard_deviation": { "$ref": "#/definitions/RawValueUnit", "description": "Standard deviation of the data" } }, "required": [ "value", "unit", "raw_value" ], "type": "object" } } }
- Validators:
- field absolute_quantity: RawValueUnitStatistics#
Absolute quantity value for absolute quantification from a known standard curve value if applicable
- field cycle_threshold: RawValueUnitStatistics#
Cycle threshold (Ct) value for the target
- field delta_cycle_threshold: RawValueUnitStatistics#
Control normalized delta cycle threshold (ΔCt) value
- field delta_delta_cycle_threshold: RawValueUnitStatistics#
Delta delta cycle threshold (ΔΔCt) value to derive relative quantification
- field relative_quantity: RawValueUnitStatistics#
Relative quantity value for relative quantification if applicable
- field standard_curve: QPcrStandardCurve#
Standard curve parameters created for this target if applicable