ClassificationByMarkerSpec
From NCOR Wiki
Jump to navigationJump to search
Goal
Write a protocol for recording of CYTOF experimental results and a method for determining cell type based on recorded markers.
Status
This is an early draft. In particular since writing this I have come to the conclusion that we should be using more information in the determination of cell type, and that information necessary to do the determination should reside in both the Cell Ontology and the Ontology for Biomedical Investigations. See Motivation for ontological representation of cell type identification assays for flow cytometry and CyTOF presented at the ImmPort_Ontology_Conference
Draft
Protocol for classifying and recording cell type/populations from CYTOF experiments
Alan Ruttenberg
Assumptions:
===========
1. Clustering/gating of CYTOF results will be done by the submitter. If
this assumption is incorrect we should describe the clustering in a
separate protocol (protocol-clustering)
2. Targeted proteins will be clearly identified. Where an antibody is
used as surrogate, and if the submitter wishes to use the antibody to
identify the protein, the antibody must be identified by an Immport
antibody registry identifier. If the antibody is not yet present in
the Immport antibody registry, it needs to be submitted and
curated according to (protocol-antibody)
3. Information specifying a protein target will generally be in most
cases unambiguous. However it may be determined to be ambiguous, for
example, in a case where we have a protein specified as CD8 (or an
antibody whose target is so specified), and whose specification is
thus ambiguous as to whether CD8a or CD8b is targeted, or in the case
that where protein has isoforms and the isoform is not specified. In
such cases the submitter should be queried as to whether this was
intended. The submitter can either fix the ambiguity, explain how we
should handle it in the analysis (e.g. perform analysis for each
possibility, ignore differences in isoforms), or remove the protein
target from the submission.
How to read this document
=========================
(type:xx) informally indicates a data type, which may be referred in
different parts of this protocol. The data types will be formalized in
subsequent revision.
For each data type, elements are enumerated by a common letter and ascending number
p1.
p2.
...
g1.
...
Inputs:
======
CYTOF results data for which cell type needs to be determined or
validated. Note that not all CYTOF experiments are of this nature - of
the experiments reported at http://www.cytobank.org/nolanlab/reports/,
for example, one characterized phases of the cell cycle using known
markers for cell types probed, one validated a surrogate CYTOF-based
marker for cell death. Such experiments are outside the scope of this
protocol.
Input data should consist of sets of proteins that were probed in the
experiment and which are grouped together as representative of a cell
type or state, analogous to gating information for flow cytometry
experiments.
--
type: cytof-experiment-protein-set
The first part of the input should be a complete listing of the
proteins used in the experiement
s1. Name or identifier of this protein set
--
type: cytof-experiment-protein-readout
For each of the proteins probed in the name set s1 the following
information should be provided:
p1. Name and/or identifiers of the target protein. Where more than one
identifier or more than one name is known to the investigator as a
common way to identify the protein, please include these.
p2. If a modified form of the protein is targeted (e.g. phosphorylated
at a specific site) then include a description of the targeted
form. If the protein is known not to be modified in certain ways, then
make this knowledge explicit (e.g. report 'not phosphorylated at
S235')
p3. If the readout is of an antibody to the protein, then the clone
name, manufacturer (if commercial) or other source (if not), and
catalog number (if manufacturer) or other identifier.
p4. If the readout is of some other marker, information that specifies
that marker.
p5. If the researcher expects that the marker may be ambiguous -
e.g. targets more than one isoform, or different gene products, please
include this information.
p6. A local synonym(handle) for the protein, for the purposes of easily
referring to it elsewhere during the protocol.
p7. In the case that a PRO identifier for the protein is known or has
been obtained through Immport resources, it can be substituted for p1
and p2.
p8. In the case that the antibody or marker has been registered and
curated into an Immport resource, it's Immport-chosen identifier can
be used in place of p1-p7. However, inclusion of redundant information
can serve as a quality check and so the submitter is encouraged to
include all fields if feasible.
--
type: cytof-cluster-protein-markers
Each set of proteins that are grouped together as representative of a
cell type or state, should have
g1. a name for the group
g2. The name of the complete set of proteins probed as named in s1
g3. Whether or not proteins in s1 but not listed as members of this cluster
should be considered as not having detectable levels ('assume-absent')
or whether only the listed proteins should be considered part of the
group ('assumed-complete').
--
type: cytof-cluster-protein-marker-level
The following information for each protein in a
cytof-cluster-protein-markers should be provided.
ml1. The chosen local synonym/handle for the protein (p6), or PRO identifer (p7)
ml2. Whether the targeted protein was present or the amount was below
detectable levels. ('present'/'+' or 'absent'/'-')
ml3. If the targeted protein is present and quantitated then the
quantity of the protein and associated unit (give unit name), unless
the measurement is relative to an arbitrary standard. (enter as
'experiment unit')
ml4. If available, a qualitative assessment of the level of the
protein, one of:
'high' (synonym: 'bright')
'low' (synonym: 'dim')
Question: Do we need "mid", as in "CD38mid"
If the submitter does not want to use qualitative level in the query, instead write
'ignore'
If the submitter wants the qualitative assesment computed write
'computed' (Question: do we want to allow this?)
Notes:
If protein levels are quantitated in ml3, and ml4 is 'compute', then we
need to design (protocol-assign-qualitative-marker-level)
If ml4 is 'ignore' then only 'absent'/'present' information will be used
--
Validation
==========
Ensure required combinations of fields are present in input
Ensure that any antibodies specified in place of proteins are
registered in Immport antibody registry
Ensure that if any cytof-cluster-protein-marker-level ml4 is
'computed', then all cytof-cluster-protein-marker-level ml3 must be
quantitated
Ensure that all cytof-cluster-protein-marker-level ml3 units are either
'experiement unit' or all are units that are convertible with one
another.
Ensure that for any cytof-protein-marker-level that where ml2 is
absent, ml3 and ml4 are empty
Question: Are there more validations (Alan guesses yes)
If any validation fails, return the submission to investigator with
report.
== TODO: Provide an example of valid input.==
Processing each protein target in cytof-experiment-protein-set
==============================================================
1. For proteins specified using an antibody in the Immport antibody
registry, retrieve the associated PRO ID.
2. For proteins that are not specified by a PRO ID, first
a. Attempt to look up the PRO entry given the information, or if that fails
b. Submit a term request for the protein to Alex Diehl for submission to the PRO team
3. If the the result of 2 is that the pro term is ambiguous, contact
the submitter for instructions on how to handle the ambiguity.
4. When all proteins have PRO IDs we can proceed to the processing of
the cytof-cluster-protein-markers
Processing of each cytof-cluster-protein-markers
================================================
type: cl-triple-store
Required: A triple store providing SPARQL query answering over the
fully reasoner CL.
sqa1: The SPARQL endpoint for the triple store
Assumes: All protein targets have PRO IDs
1. If any ml4 is 'compute' use protocol-assign-qualitative-marker-level to assign qualitative levels
2. Construct a class query based on all the cytof-cluster-protein-marker-level in the cytof-cluster-protein-markers. This query will be a conjunction of terms. Below we list the
forms the terms using OWL2 functional syntax (http://www.w3.org/TR/owl2-syntax/)
The relations we will use are:
<lacks_part> <http://purl.obolibrary.org/obo/cl#lacks_part>
<has_high_plasma_membrane_amount> <http://purl.obolibrary.org/obo/cl#has_high_plasma_membrane_amount>
<has_low_plasma_membrane_amount> <http://purl.obolibrary.org/obo/cl#has_low_plasma_membrane_amount>
<has_plasma_membrane_part> <http://purl.obolibrary.org/obo/RO_0002104>
(note: some of these relations have legacy URLs - check/fix)
If mp2 is 'absent' or '-'
then the clause is ObjectSomeValuesFrom(<lacks_part> <PRO_ID>)
If mp2 is 'present' or '+' and p4 is 'ignore'
then the clause is ObjectSomeValuesFrom(<has_plasma_membrane_part> <PRO_ID>)
If mp2 is 'present' and p4 is 'high' or 'bright'
then the clause is ObjectSomeValuesFrom(<has_high_plasma_membrane_amount> <PRO_ID>)
If mp2 is 'present' and p4 is 'low' or 'dim'
then the clause is ObjectSomeValuesFrom(<has_low_plasma_membrane_amount> <PRO_ID>)
If mp3 is 'assume-absent' then for each protein identified in
cytof-experiment-protein-set that is not identified in a
cytof-experiment-protein-readout (ap), add the clause
add the clause ObjectSomeValuesFrom(<lacks_part> <PRO_ID of ap>)
join the terms above using ObjectIntersectionOf
The class (ObjectIntersectionOf <cell> <E1>) defines a class of cells
(C1) with the markers as specified.
2. Using the expression for C1 above we will construct 2 SPARQL queries.
- A query Q1 for the most specific of the more general class types - this will yield the immediate superclasses of C1
- A query Q2 for the most general of the more specific class types - this will yield the immediate subclasses of C1
To construct Q1, Q2, first render the expression for C1 as RDF triples
<R>. This can be accomplished with a call to the OWLAPI, or equivalent
(see below, LSW2 code)
Retrieve the node that is the class defined by the expression. (S)
For the subclasses query, construct the sparql query
SELECT ?subclasses where { ?subclasses rdfs:subClassOf S . <R> }
For the superclasses query, construct the SPARQL query
SELECT ?superclasses where { S rdfs:subClassOf ?superclasses . <R> }
Here is an example of this transformation using LSW2.
(sparql-stringify ;; render a sparql query from sexp
`(:select
(?subclasses) ;; The variable for which we want solutions
()
,@(let ((p1 !<http://purl.obolibrary.org/obo/PR_P01730>) ;; CD4 human
(p2 !<http://purl.obolibrary.org/obo/PR_000025405>) ;; CD8a human
(has-high !<http://purl.obolibrary.org/obo/cl#has_high_plasma_membrane_amount>)
(cell !<http://purl.obolibrary.org/obo/CL_0000000>)) ;; Cell
(let ((translated
(butlast
(t-collect
`(ontology (object-intersection-of
,cell
(object-some-values-from ,has-high ,p1)
(object-some-values-from ,has-high ,p2)))))))
(let ((class-defined (first (first translated)))) ;; The blank node representing the defined class
`((?subclasses ,!rdfs:subClassOf ,class-defined) ;; The additional triple
,@translated)))))) ;; The rest of the RDF triples
PREFIX obo: <http://purl.obolibrary.org/obo/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX owl: <http://www.w3.org/2002/07/owl#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
SELECT ?subclasses
WHERE {
?subclasses rdfs:subClassOf _:b2 .
_:b2 owl:intersectionOf _:b3 .
_:b3 rdf:rest _:b4 .
_:b4 rdf:rest _:b6 .
_:b6 rdf:rest rdf:nil .
_:b6 rdf:first _:b7 .
_:b7 owl:someValuesFrom obo:PR_000025405 .
_:b7 owl:onProperty <http://purl.obolibrary.org/obo/cl#has_high_plasma_membrane_amount> .
_:b7 rdf:type owl:Restriction .
_:b4 rdf:first _:b5 .
_:b5 owl:someValuesFrom obo:PR_P01730 .
_:b5 owl:onProperty <http://purl.obolibrary.org/obo/cl#has_high_plasma_membrane_amount> .
_:b5 rdf:type owl:Restriction .
_:b3 rdf:first obo:CL_0000000 .
_:b2 rdf:type owl:Class . }
== TO BE DONE: Add clauses to get just the immediate subs and supers ==
Construct a report:
For each cytof-cluster-protein-markers give it's name, g1
Show the logical definition of the class defined for the query of this cluster (C1)
List the immediate superclasses, each of their URI, their logical definitions, and their textual definitions.
List the same for the immediate subclasses
We can predict a number of cases, but at this point in development we
should present this report to the submitter for review and comment.
Some cases we can imagine:
Result: The immediate superclasses and subclasses yield a single class.
Interpretation: Direct hit - the population measured is precisely C1
Result: The superclass expression(s) only differ from C1 by including
clauses that reflect absences of protein.
Interpretation: Here a judgement may need to be made as to whether the
absences reflect knowledge missing at the time the CL term was
curated, or whether they might define a distinct population.
Result: The subclass expression(s) only differ from C1 by the presence
of clauses that reflect properties or capabilities not measured in
this experiment.
Interpretation: Here a judgement may need to be made as to whether the
the extra conditions in the subclass expressions are also true of
the cell defined by the cluster, or whether they might be a distinct
population.
Result: The subclasses and superclasses look odd/incorrect.
Interpretation: The cluster might represent a population including different cell types.
================================================================
Our next step is review of several experiements and scrutiny of the
generated reports to gain experience with the protocol, with the aim
of removing or shortening the review step as much as possible.
