Skip to content

Commit

Permalink
Add decorators to track provenance.
Browse files Browse the repository at this point in the history
These allow a structure to be tagged with a tree of provenance
nodes, that explain how the structure was created.
Relates salilab/imp#976.
  • Loading branch information
benmwebb committed Oct 17, 2017
1 parent 3dd7d08 commit 3e94522
Show file tree
Hide file tree
Showing 10 changed files with 372 additions and 15 deletions.
2 changes: 2 additions & 0 deletions ChangeLog.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
Change Log {#changelog}
==========

- A new category of decorators 'provenance' allows information about how the
structure was generated to be added to the file.
- The new RMF::decorator::Reference decorator allows for a node to mark
another node as its reference.
- The new RMF::decorator::ExplicitResolution decorator allows attaching an
Expand Down
31 changes: 31 additions & 0 deletions doc/DecoratorsAndAttributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ The category name is `sequence` and it includes information about the types and
| `state index` | int | An arbitrary integer to label different states of a hierarchy. |
| `explicit resolution` | float | Explicitly-specified resolution for a hierarchy. |
| `reference` | int | The RMF::NodeID of the reference node |
| `provenance` | int | The RMF::NodeID of the provenance node |


## Decorators ## {#sequencedecorators}
Expand All @@ -85,6 +86,7 @@ The category name is `sequence` and it includes information about the types and
| RMF::decorator::State | RMF::REPRESENTATION | state index |
| RMF::decorator::ExplicitResolution | RMF::REPRESENTATION | explicit resolution |
| RMF::decorator::Reference | RMF::REPRESENTATION | pointer to reference node |
| RMF::decorator::Provenance | RMF::REPRESENTATION | pointer to provenance node |


# Feature # {#feature}
Expand Down Expand Up @@ -207,3 +209,32 @@ should be loaded as a child of the current node.
| Name | Node Type | Attributes |
|--------------------------------:|:-----------------------:|:-----------------------------------|
| RMF::decorator::JournalArticle | RMF::ORGANIZATIONAL | title, journal, pubmed id, year, authors |

# Provenance # {#provenance}

The category name is `provenance`. It includes information about how the
structure was generated.

## Attributes ## {#provenanceattributes}

| Name | Type | Description |
|---------------:|-------------:|:------------------------------------------|
| `filename` | string | File from which the structure was read |
| `chain` | string | Chain ID of the structure that was read |
| `method` | string | Sampling method utilized |
| `frames` | int | Number of frames in an ensemble |
| `iterations` | int | Number of sampling iterations used |
| `runs` | int | Number of sampling runs utilized |
| `threshold` | float | Score threshold to discard bad models |
| `members` | int | Number of members in a cluster |


## Decorators ## {#provenancedecorators}

| Name | Node Type | Attributes |
|------------------------------------:|:-----------------------:|:---------------------------|
| RMF::decorator::StructureProvenance | RMF::ORGANIZATIONAL | filename, chain |
| RMF::decorator::SampleProvenance | RMF::ORGANIZATIONAL | method, frames, iterations |
| RMF::decorator::CombineProvenance | RMF::ORGANIZATIONAL | runs, frames |
| RMF::decorator::FilterProvenance | RMF::ORGANIZATIONAL | threshold, frames |
| RMF::decorator::ClusterProvenance | RMF::ORGANIZATIONAL | members |
161 changes: 161 additions & 0 deletions include/RMF/decorator/provenance.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
/**
* \file RMF/decorator/provenance.h
* \brief Add a pointer from a node to another provenance node.
*
* Copyright 2007-2017 IMP Inventors. All rights reserved.
*
*/

#ifndef RMF_DECORATOR_PROVENANCE_H
#define RMF_DECORATOR_PROVENANCE_H

#include <RMF/config.h>
#include <RMF/infrastructure_macros.h>
#include <RMF/NodeHandle.h>
#include <RMF/FileHandle.h>
#include <RMF/Decorator.h>
#include <RMF/constants.h>
#include <RMF/Vector.h>
#include <RMF/decorator/provenance_types.h>
#include <boost/array.hpp>
#include <boost/lexical_cast.hpp>

RMF_ENABLE_WARNINGS
namespace RMF {
namespace decorator {

/** See also Provenance and ProvenanceFactory.
*/
class ProvenanceConst : public Decorator {
friend class ProvenanceFactory;
friend class Provenance;
IntKey provenance_;
ProvenanceConst(NodeConstHandle nh, IntKey provenance)
: Decorator(nh), provenance_(provenance) {}

public:
NodeConstHandle get_provenance() const {
try {
return get_node().get_file().get_node(
NodeID(get_node().get_value(provenance_)));
}
RMF_DECORATOR_CATCH();
}
NodeConstHandle get_frame_provenance() const {
try {
return get_node().get_file().get_node(
NodeID(get_node().get_frame_value(provenance_)));
}
RMF_DECORATOR_CATCH();
}
NodeConstHandle get_static_provenance() const {
try {
return get_node().get_file().get_node(
NodeID(get_node().get_static_value(provenance_)));
}
RMF_DECORATOR_CATCH();
}

static std::string get_decorator_type_name() { return "ProvenanceConst"; }
RMF_SHOWABLE(ProvenanceConst, "Provenance: " << get_node());
};
/** See also ProvenanceFactory.
*/
class Provenance : public ProvenanceConst {
friend class ProvenanceFactory;
Provenance(NodeHandle nh, IntKey provenance)
: ProvenanceConst(nh, provenance) {}

public:

NodeHandle get_provenance() const {
try {
return get_node().get_file().get_node(
NodeID(get_node().get_value(provenance_)));
}
RMF_DECORATOR_CATCH();
}
NodeHandle get_frame_provenance() const {
try {
return get_node().get_file().get_node(
NodeID(get_node().get_frame_value(provenance_)));
}
RMF_DECORATOR_CATCH();
}
NodeHandle get_static_provenance() const {
try {
return get_node().get_file().get_node(
NodeID(get_node().get_static_value(provenance_)));
}
RMF_DECORATOR_CATCH();
}

void set_provenance(NodeConstHandle v) {
try {
get_node().set_value(provenance_, v.get_id().get_index());
}
RMF_DECORATOR_CATCH();
}
void set_frame_provenance(NodeConstHandle v) {
try {
get_node().set_frame_value(provenance_, v.get_id().get_index());
}
RMF_DECORATOR_CATCH();
}
void set_static_provenance(NodeConstHandle v) {
try {
get_node().set_static_value(provenance_, v.get_id().get_index());
}
RMF_DECORATOR_CATCH();
}

static std::string get_decorator_type_name() { return "Provenance"; }
};

/** Create decorators of type Provenance.
*/
class ProvenanceFactory : public Factory {
Category cat_;
IntKey provenance_;

public:
ProvenanceFactory(FileConstHandle fh)
: cat_(fh.get_category("sequence")),
provenance_(fh.get_key<IntTag>(cat_, "provenance")) {}
ProvenanceFactory(FileHandle fh)
: cat_(fh.get_category("sequence")),
provenance_(fh.get_key<IntTag>(cat_, "provenance")) {}
/** Get a ProvenanceConst for nh.*/
ProvenanceConst get(NodeConstHandle nh) const {
RMF_USAGE_CHECK((nh.get_type() == RMF::REPRESENTATION),
std::string("Bad node type. Got \"") +
boost::lexical_cast<std::string>(nh.get_type()) +
"\" in decorator type Provenance");
return ProvenanceConst(nh, provenance_);
}
/** Get a Provenance for nh.*/
Provenance get(NodeHandle nh) const {
RMF_USAGE_CHECK((nh.get_type() == RMF::REPRESENTATION),
std::string("Bad node type. Got \"") +
boost::lexical_cast<std::string>(nh.get_type()) +
"\" in decorator type Provenance");
return Provenance(nh, provenance_);
}
/** Check whether nh has all the attributes required to be a
ProvenanceConst.*/
bool get_is(NodeConstHandle nh) const {
return (nh.get_type() == RMF::REPRESENTATION) &&
!nh.get_value(provenance_).get_is_null();
}
bool get_is_static(NodeConstHandle nh) const {
return (nh.get_type() == RMF::REPRESENTATION) &&
!nh.get_static_value(provenance_).get_is_null();
}
RMF_SHOWABLE(ProvenanceFactory, "ProvenanceFactory");
};

} /* namespace decorator */
} /* namespace RMF */
RMF_DISABLE_WARNINGS

#endif /* RMF_DECORATOR_PROVENANCE_H */
1 change: 1 addition & 0 deletions include/RMF/decorators.h
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
#include "RMF/decorator/feature.h"
#include "RMF/decorator/physics.h"
#include "RMF/decorator/publication.h"
#include "RMF/decorator/provenance.h"
#include "RMF/decorator/sequence.h"
#include "RMF/decorator/shape.h"
#include "RMF/decorator/bond.h"
Expand Down
36 changes: 34 additions & 2 deletions src/show_hierarchy.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
#include "RMF/decorator/alternatives.h"
#include "RMF/decorator/shape.h"
#include "RMF/decorator/reference.h"
#include "RMF/decorator/provenance.h"
#include "RMF/enums.h"
#include "RMF/infrastructure_macros.h"
#include "RMF/types.h"
Expand Down Expand Up @@ -175,6 +176,12 @@ void show_node_decorators(
decorator::ChainFactory chaincf, decorator::DomainFactory fragcf,
decorator::CopyFactory copycf, decorator::DiffuserFactory diffusercf,
decorator::TypedFactory typedcf, decorator::ReferenceFactory refcf,
decorator::ProvenanceFactory provcf,
decorator::StructureProvenanceFactory strucpcf,
decorator::SampleProvenanceFactory samppcf,
decorator::CombineProvenanceFactory combpcf,
decorator::FilterProvenanceFactory filtpcf,
decorator::ClusterProvenanceFactory clustpcf,
std::string) {
using std::operator<<;
out << "\"" << n.get_name() << "\"" << node_suffix << " [" << n.get_type()
Expand Down Expand Up @@ -219,6 +226,18 @@ void show_node_decorators(
else if (diffusercf.get_is(n)) out << " diffuser";
if (refcf.get_is_static(n)) out << " reference(s)";
else if (refcf.get_is(n)) out << " reference";
if (provcf.get_is_static(n)) out << " provenance(s)";
else if (provcf.get_is(n)) out << " provenance";
if (strucpcf.get_is_static(n)) out << " structure provenance(s)";
else if (strucpcf.get_is(n)) out << " structure provenance";
if (samppcf.get_is_static(n)) out << " sample provenance(s)";
else if (samppcf.get_is(n)) out << " sample provenance";
if (combpcf.get_is_static(n)) out << " combine provenance(s)";
else if (combpcf.get_is(n)) out << " combine provenance";
if (filtpcf.get_is_static(n)) out << " filter provenance(s)";
else if (filtpcf.get_is(n)) out << " filter provenance";
if (clustpcf.get_is_static(n)) out << " cluster provenance(s)";
else if (clustpcf.get_is(n)) out << " cluster provenance";
out << "]";
}

Expand Down Expand Up @@ -278,6 +297,12 @@ struct ShowDecorators {
decorator::DiffuserFactory diffusercf;
decorator::TypedFactory typedcf;
decorator::ReferenceFactory refcf;
decorator::ProvenanceFactory provcf;
decorator::StructureProvenanceFactory strucpcf;
decorator::SampleProvenanceFactory samppcf;
decorator::CombineProvenanceFactory combpcf;
decorator::FilterProvenanceFactory filtpcf;
decorator::ClusterProvenanceFactory clustpcf;
ShowDecorators(FileConstHandle fh)
: bdf(fh),
ccf(fh),
Expand All @@ -296,12 +321,19 @@ struct ShowDecorators {
copycf(fh),
diffusercf(fh),
typedcf(fh),
refcf(fh) {}
refcf(fh),
provcf(fh),
strucpcf(fh),
samppcf(fh),
combpcf(fh),
filtpcf(fh),
clustpcf(fh) {}
void operator()(NodeConstHandle cur, std::string prefix, std::string suffix,
std::ostream& out) {
show_node_decorators(cur, suffix, out, bdf, ccf, pcf, ipcf, rpcf, scf,
repcf, bcf, cycf, segcf, rcf, acf, chaincf, fragcf,
copycf, diffusercf, typedcf, refcf, prefix + " ");
copycf, diffusercf, typedcf, refcf, provcf, strucpcf,
samppcf, combpcf, filtpcf, clustpcf, prefix + " ");
}
};
}
Expand Down
12 changes: 8 additions & 4 deletions src/signature.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
#include "RMF/decorator/feature.h"
#include "RMF/decorator/bond.h"
#include "RMF/decorator/reference.h"
#include "RMF/decorator/provenance.h"
#include "RMF/decorator/shape.h"

RMF_ENABLE_WARNINGS
Expand All @@ -37,7 +38,7 @@ std::string get_static_signature(
decorator::AtomFactory acf, decorator::ChainFactory chaincf,
decorator::DomainFactory fragcf, decorator::CopyFactory copycf,
decorator::DiffuserFactory diffusercf, decorator::TypedFactory typedcf,
decorator::ReferenceFactory refcf) {
decorator::ReferenceFactory refcf, decorator::ProvenanceFactory provcf) {
std::ostringstream ret;
ret << "hierarchy [\n";
RMF_FOREACH(NodeID n, file.get_node_ids()) {
Expand Down Expand Up @@ -72,6 +73,7 @@ std::string get_static_signature(
if (typedcf.get_is_static(nh)) ret << " typed";
if (diffusercf.get_is_static(nh)) ret << " diffuser";
if (refcf.get_is_static(nh)) ret << " reference";
if (provcf.get_is_static(nh)) ret << " provenance";
ret << "\n";
}
ret << "]\n";
Expand All @@ -88,7 +90,7 @@ std::string get_frame_signature(
decorator::AtomFactory acf, decorator::ChainFactory chaincf,
decorator::DomainFactory fragcf, decorator::CopyFactory copycf,
decorator::DiffuserFactory diffusercf, decorator::TypedFactory typedcf,
decorator::ReferenceFactory refcf) {
decorator::ReferenceFactory refcf, decorator::ProvenanceFactory provcf) {
std::ostringstream ret;
ret << file.get_current_frame() << " [\n";
RMF_FOREACH(NodeID n, file.get_node_ids()) {
Expand All @@ -113,6 +115,7 @@ std::string get_frame_signature(
if (typedcf.get_is(nh)) ret << " typed";
if (diffusercf.get_is(nh)) ret << " diffuser";
if (refcf.get_is(nh)) ret << " reference";
if (provcf.get_is(nh)) ret << " provenance";
ret << "\n";
}
ret << "]\n";
Expand All @@ -138,18 +141,19 @@ std::string get_signature_string(FileConstHandle file) {
decorator::DiffuserFactory diffusercf(file);
decorator::TypedFactory typedcf(file);
decorator::ReferenceFactory refcf(file);
decorator::ProvenanceFactory provcf(file);

std::string ret = get_static_signature(file, bdf, ccf, pcf, ipcf, rpcf, scf,
bcf, cycf, segcf, rcf, acf, chaincf,
fragcf, copycf, diffusercf, typedcf,
refcf);
refcf, provcf);
RMF_FOREACH(FrameID frame, file.get_frames()) {
file.set_current_frame(frame);
ret += std::string("\n") + get_frame_signature(file, bdf, ccf, pcf, ipcf,
rpcf, scf, bcf, cycf, segcf,
rcf, acf, chaincf, fragcf,
copycf, diffusercf, typedcf,
refcf);
refcf, provcf);
}
return ret;
}
Expand Down
2 changes: 2 additions & 0 deletions swig/RMF.decorator.i
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,5 @@
%include "RMF/decorator/bond.h"
%include "RMF/decorator/labels.h"
%include "RMF/decorator/reference.h"
%include "RMF/decorator/provenance.h"
%include "RMF/decorator/provenance_types.h"
Loading

0 comments on commit 3e94522

Please sign in to comment.