Struct ProvenanceRelation 

pub struct ProvenanceRelation<F: Ord, P: Ord> { /* private fields */ }

Deterministic exact provenance attached to stored facts.

ProvenanceRelation<F, P> maps each stored fact to a deterministic set of provenance tokens. Repeated insertion of the same (fact, token) pair is idempotent. Inserting a new token for an existing fact combines provenance by exact set union.

In this first additive provenance slice, every stored fact is a base fact. The module does not yet derive new tuples. Self::why explains stored facts only; derived-tuple explanations and why_not queries remain later work.

Examples

use relmath::{UnaryRelation, provenance::ProvenanceRelation};

let gene_disease = ProvenanceRelation::from_facts([
    (("BRCA1", "BreastCancer"), "paper_12"),
    (("BRCA1", "BreastCancer"), "curated_panel"),
    (("TP53", "BreastCancer"), "paper_77"),
]);

let supported = gene_disease.to_binary_relation();
let brca1 = UnaryRelation::singleton("BRCA1");

assert_eq!(supported.image(&brca1).to_vec(), vec!["BreastCancer"]);
assert_eq!(
    gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation")
        .to_vec(),
    vec!["curated_panel", "paper_12"]
);

Implementations

impl<F: Ord, P: Ord> ProvenanceRelation<F, P>

pub fn new() -> Self

Creates an empty provenance relation.

Examples

use relmath::provenance::ProvenanceRelation;

let mut evidence = ProvenanceRelation::new();

assert!(evidence.insert(("BRCA1", "BreastCancer"), "paper_12"));
assert!(!evidence.insert(("BRCA1", "BreastCancer"), "paper_12"));
assert!(evidence.contains_fact(&("BRCA1", "BreastCancer")));
assert_eq!(
    evidence
        .provenance_of(&("BRCA1", "BreastCancer"))
        .expect("expected explanation")
        .to_vec(),
    vec!["paper_12"]
);

pub fn from_facts<I>(facts: I) -> Self

where I: IntoIterator<Item = (F, P)>,

Creates a provenance relation from (fact, token) entries.

Repeated facts accumulate tokens by exact set union.

Examples found in repository

examples/provenance.rs (lines 6-10)

fn main() {
    let gene_disease = ProvenanceRelation::from_facts([
        (("BRCA1", "BreastCancer"), "curated_panel"),
        (("BRCA1", "BreastCancer"), "paper_12"),
        (("TP53", "BreastCancer"), "paper_77"),
    ]);

    let disease_drug = relmath::BinaryRelation::from_pairs([
        ("BreastCancer", "Olaparib"),
        ("BreastCancer", "Tamoxifen"),
    ]);

    let supported_gene_disease = gene_disease.to_binary_relation();
    let gene_drug = supported_gene_disease.compose(&disease_drug);
    let brca1 = UnaryRelation::singleton("BRCA1");
    let brca1_witness = gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation");

    assert_eq!(
        gene_drug.image(&brca1).to_vec(),
        vec!["Olaparib", "Tamoxifen"]
    );
    assert_eq!(brca1_witness.to_vec(), vec!["curated_panel", "paper_12"]);
    assert!(brca1_witness.contains_token(&"paper_12"));
    assert_eq!(
        gene_disease
            .provenance_of(&("BRCA1", "BreastCancer"))
            .expect("expected explanation")
            .to_vec(),
        brca1_witness.to_vec()
    );
    assert_eq!(
        gene_disease.support().to_vec(),
        vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
    );
    assert!(gene_disease.why(&("BRCA1", "Olaparib")).is_none());

    println!(
        "why BRCA1 links to BreastCancer in the base evidence: {:?}",
        brca1_witness.to_vec()
    );
}

examples/capability_boundaries.rs (lines 23-26)

fn main() {
    let evidence = ProvenanceRelation::from_facts([
        (("alice", "review"), "directory"),
        (("bob", "approve"), "policy"),
    ]);
    let permissions = AnnotatedRelation::from_facts([
        (("alice", "review"), BooleanSemiring::TRUE),
        (("bob", "approve"), BooleanSemiring::TRUE),
    ]);
    let schedule = ValidTimeRelation::from_facts([
        (
            ("alice", "review"),
            Interval::new(1, 3).expect("expected valid interval"),
        ),
        (
            ("bob", "approve"),
            Interval::new(2, 4).expect("expected valid interval"),
        ),
    ]);

    let exact_evidence = exact_pairs(&evidence);
    let exact_permissions = exact_pairs(&permissions);
    let exact_schedule = exact_pairs(&schedule);

    assert_eq!(
        exact_evidence.to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(exact_permissions.to_vec(), exact_evidence.to_vec());
    assert_eq!(exact_schedule.to_vec(), exact_evidence.to_vec());

    assert_eq!(
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        vec!["directory"]
    );
    assert_eq!(
        permissions.annotation_of(&("alice", "review")),
        Some(&BooleanSemiring::TRUE)
    );
    assert_eq!(
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        vec![Interval::new(1, 3).expect("expected valid interval")]
    );

    println!(
        "witness={:?}, annotation={:?}, interval_support={:?}, exact_support={:?}",
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        permissions.annotation_of(&("alice", "review")),
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        exact_schedule.to_vec()
    );
}

pub fn insert(&mut self, fact: F, token: P) -> bool

Inserts one provenance token for a fact.

Returns true when the token was not already attached to the fact.

pub fn contains_fact(&self, fact: &F) -> bool

Returns true when the relation contains the given fact.

pub fn why(&self, fact: &F) -> Option<&ProvenanceSet<P>>

Returns why fact is present in this provenance relation.

When fact is present, the returned witness is the deterministic exact set of provenance tokens attached to that stored fact. When fact is absent, this returns None.

In this first G3 slice, every stored fact is a base fact with at least one token, so None means the relation has no explanation for the fact because the fact is absent.

Examples

use relmath::provenance::ProvenanceRelation;

let evidence = ProvenanceRelation::from_facts([
    (("BRCA1", "BreastCancer"), "paper_12"),
    (("BRCA1", "BreastCancer"), "curated_panel"),
]);

let why = evidence
    .why(&("BRCA1", "BreastCancer"))
    .expect("expected explanation");

assert!(why.contains_token(&"paper_12"));
assert!(why.contains_token(&"curated_panel"));
assert!(evidence.why(&("BRCA1", "Olaparib")).is_none());

Examples found in repository

examples/provenance.rs (line 21)

fn main() {
    let gene_disease = ProvenanceRelation::from_facts([
        (("BRCA1", "BreastCancer"), "curated_panel"),
        (("BRCA1", "BreastCancer"), "paper_12"),
        (("TP53", "BreastCancer"), "paper_77"),
    ]);

    let disease_drug = relmath::BinaryRelation::from_pairs([
        ("BreastCancer", "Olaparib"),
        ("BreastCancer", "Tamoxifen"),
    ]);

    let supported_gene_disease = gene_disease.to_binary_relation();
    let gene_drug = supported_gene_disease.compose(&disease_drug);
    let brca1 = UnaryRelation::singleton("BRCA1");
    let brca1_witness = gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation");

    assert_eq!(
        gene_drug.image(&brca1).to_vec(),
        vec!["Olaparib", "Tamoxifen"]
    );
    assert_eq!(brca1_witness.to_vec(), vec!["curated_panel", "paper_12"]);
    assert!(brca1_witness.contains_token(&"paper_12"));
    assert_eq!(
        gene_disease
            .provenance_of(&("BRCA1", "BreastCancer"))
            .expect("expected explanation")
            .to_vec(),
        brca1_witness.to_vec()
    );
    assert_eq!(
        gene_disease.support().to_vec(),
        vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
    );
    assert!(gene_disease.why(&("BRCA1", "Olaparib")).is_none());

    println!(
        "why BRCA1 links to BreastCancer in the base evidence: {:?}",
        brca1_witness.to_vec()
    );
}

examples/capability_boundaries.rs (line 55)

fn main() {
    let evidence = ProvenanceRelation::from_facts([
        (("alice", "review"), "directory"),
        (("bob", "approve"), "policy"),
    ]);
    let permissions = AnnotatedRelation::from_facts([
        (("alice", "review"), BooleanSemiring::TRUE),
        (("bob", "approve"), BooleanSemiring::TRUE),
    ]);
    let schedule = ValidTimeRelation::from_facts([
        (
            ("alice", "review"),
            Interval::new(1, 3).expect("expected valid interval"),
        ),
        (
            ("bob", "approve"),
            Interval::new(2, 4).expect("expected valid interval"),
        ),
    ]);

    let exact_evidence = exact_pairs(&evidence);
    let exact_permissions = exact_pairs(&permissions);
    let exact_schedule = exact_pairs(&schedule);

    assert_eq!(
        exact_evidence.to_vec(),
        vec![("alice", "review"), ("bob", "approve")]
    );
    assert_eq!(exact_permissions.to_vec(), exact_evidence.to_vec());
    assert_eq!(exact_schedule.to_vec(), exact_evidence.to_vec());

    assert_eq!(
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        vec!["directory"]
    );
    assert_eq!(
        permissions.annotation_of(&("alice", "review")),
        Some(&BooleanSemiring::TRUE)
    );
    assert_eq!(
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        vec![Interval::new(1, 3).expect("expected valid interval")]
    );

    println!(
        "witness={:?}, annotation={:?}, interval_support={:?}, exact_support={:?}",
        evidence
            .why(&("alice", "review"))
            .expect("expected witness")
            .to_vec(),
        permissions.annotation_of(&("alice", "review")),
        schedule
            .valid_time_of(&("alice", "review"))
            .expect("expected interval support")
            .to_vec(),
        exact_schedule.to_vec()
    );
}

pub fn provenance_of(&self, fact: &F) -> Option<&ProvenanceSet<P>>

Returns the deterministic provenance set for one fact.

Prefer Self::why for explanation-oriented queries.

Examples found in repository

examples/provenance.rs (line 32)

fn main() {
    let gene_disease = ProvenanceRelation::from_facts([
        (("BRCA1", "BreastCancer"), "curated_panel"),
        (("BRCA1", "BreastCancer"), "paper_12"),
        (("TP53", "BreastCancer"), "paper_77"),
    ]);

    let disease_drug = relmath::BinaryRelation::from_pairs([
        ("BreastCancer", "Olaparib"),
        ("BreastCancer", "Tamoxifen"),
    ]);

    let supported_gene_disease = gene_disease.to_binary_relation();
    let gene_drug = supported_gene_disease.compose(&disease_drug);
    let brca1 = UnaryRelation::singleton("BRCA1");
    let brca1_witness = gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation");

    assert_eq!(
        gene_drug.image(&brca1).to_vec(),
        vec!["Olaparib", "Tamoxifen"]
    );
    assert_eq!(brca1_witness.to_vec(), vec!["curated_panel", "paper_12"]);
    assert!(brca1_witness.contains_token(&"paper_12"));
    assert_eq!(
        gene_disease
            .provenance_of(&("BRCA1", "BreastCancer"))
            .expect("expected explanation")
            .to_vec(),
        brca1_witness.to_vec()
    );
    assert_eq!(
        gene_disease.support().to_vec(),
        vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
    );
    assert!(gene_disease.why(&("BRCA1", "Olaparib")).is_none());

    println!(
        "why BRCA1 links to BreastCancer in the base evidence: {:?}",
        brca1_witness.to_vec()
    );
}

pub fn iter(&self) -> impl Iterator<Item = (&F, &ProvenanceSet<P>)>

Returns an iterator over facts and provenance in deterministic order.

Examples

use relmath::provenance::ProvenanceRelation;

let evidence = ProvenanceRelation::from_facts([
    (("BRCA1", "BreastCancer"), "paper_12"),
    (("BRCA1", "BreastCancer"), "curated_panel"),
    (("TP53", "BreastCancer"), "paper_77"),
]);

assert_eq!(
    evidence
        .iter()
        .map(|(fact, witness)| (*fact, witness.to_vec()))
        .collect::<Vec<_>>(),
    vec![
        (("BRCA1", "BreastCancer"), vec!["curated_panel", "paper_12"]),
        (("TP53", "BreastCancer"), vec!["paper_77"]),
    ]
);

pub fn support(&self) -> UnaryRelation<F>

where F: Clone,

Returns the exact support relation of stored facts as a unary relation.

This support forgets provenance and keeps only which facts are present. Generic code can access the same relation-level boundary through crate::ExactSupport::exact_support.

Examples

use relmath::provenance::ProvenanceRelation;

let evidence = ProvenanceRelation::from_facts([
    (("BRCA1", "BreastCancer"), "paper_12"),
    (("BRCA1", "BreastCancer"), "curated_panel"),
    (("TP53", "BreastCancer"), "paper_77"),
]);

assert_eq!(
    evidence.support().to_vec(),
    vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
);

Examples found in repository

examples/provenance.rs (line 38)

fn main() {
    let gene_disease = ProvenanceRelation::from_facts([
        (("BRCA1", "BreastCancer"), "curated_panel"),
        (("BRCA1", "BreastCancer"), "paper_12"),
        (("TP53", "BreastCancer"), "paper_77"),
    ]);

    let disease_drug = relmath::BinaryRelation::from_pairs([
        ("BreastCancer", "Olaparib"),
        ("BreastCancer", "Tamoxifen"),
    ]);

    let supported_gene_disease = gene_disease.to_binary_relation();
    let gene_drug = supported_gene_disease.compose(&disease_drug);
    let brca1 = UnaryRelation::singleton("BRCA1");
    let brca1_witness = gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation");

    assert_eq!(
        gene_drug.image(&brca1).to_vec(),
        vec!["Olaparib", "Tamoxifen"]
    );
    assert_eq!(brca1_witness.to_vec(), vec!["curated_panel", "paper_12"]);
    assert!(brca1_witness.contains_token(&"paper_12"));
    assert_eq!(
        gene_disease
            .provenance_of(&("BRCA1", "BreastCancer"))
            .expect("expected explanation")
            .to_vec(),
        brca1_witness.to_vec()
    );
    assert_eq!(
        gene_disease.support().to_vec(),
        vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
    );
    assert!(gene_disease.why(&("BRCA1", "Olaparib")).is_none());

    println!(
        "why BRCA1 links to BreastCancer in the base evidence: {:?}",
        brca1_witness.to_vec()
    );
}

impl<T: Ord + Clone, P: Ord> ProvenanceRelation<T, P>

pub fn to_unary_relation(&self) -> UnaryRelation<T>

Converts scalar facts into a unary relation support set.

Generic code can access the same unary materialization boundary through crate::ToExactUnaryRelation.

Examples

use relmath::provenance::ProvenanceRelation;

let concepts = ProvenanceRelation::from_facts([
    ("Relations", "lecture_1"),
    ("Relations", "worksheet"),
    ("Closure", "lecture_2"),
]);

assert_eq!(concepts.to_unary_relation().to_vec(), vec!["Closure", "Relations"]);

impl<A: Ord + Clone, B: Ord + Clone, P: Ord> ProvenanceRelation<(A, B), P>

pub fn to_binary_relation(&self) -> BinaryRelation<A, B>

Converts pair facts into a binary relation support set.

Generic code can access the same binary materialization boundary through crate::ToExactBinaryRelation.

Examples

use relmath::provenance::ProvenanceRelation;

let evidence = ProvenanceRelation::from_facts([
    (("Alice", "Reader"), "directory"),
    (("Bob", "Editor"), "directory"),
]);

assert_eq!(
    evidence.to_binary_relation().to_vec(),
    vec![("Alice", "Reader"), ("Bob", "Editor")]
);

Examples found in repository

examples/provenance.rs (line 17)

fn main() {
    let gene_disease = ProvenanceRelation::from_facts([
        (("BRCA1", "BreastCancer"), "curated_panel"),
        (("BRCA1", "BreastCancer"), "paper_12"),
        (("TP53", "BreastCancer"), "paper_77"),
    ]);

    let disease_drug = relmath::BinaryRelation::from_pairs([
        ("BreastCancer", "Olaparib"),
        ("BreastCancer", "Tamoxifen"),
    ]);

    let supported_gene_disease = gene_disease.to_binary_relation();
    let gene_drug = supported_gene_disease.compose(&disease_drug);
    let brca1 = UnaryRelation::singleton("BRCA1");
    let brca1_witness = gene_disease
        .why(&("BRCA1", "BreastCancer"))
        .expect("expected explanation");

    assert_eq!(
        gene_drug.image(&brca1).to_vec(),
        vec!["Olaparib", "Tamoxifen"]
    );
    assert_eq!(brca1_witness.to_vec(), vec!["curated_panel", "paper_12"]);
    assert!(brca1_witness.contains_token(&"paper_12"));
    assert_eq!(
        gene_disease
            .provenance_of(&("BRCA1", "BreastCancer"))
            .expect("expected explanation")
            .to_vec(),
        brca1_witness.to_vec()
    );
    assert_eq!(
        gene_disease.support().to_vec(),
        vec![("BRCA1", "BreastCancer"), ("TP53", "BreastCancer")]
    );
    assert!(gene_disease.why(&("BRCA1", "Olaparib")).is_none());

    println!(
        "why BRCA1 links to BreastCancer in the base evidence: {:?}",
        brca1_witness.to_vec()
    );
}

impl<T: Ord + Clone, P: Ord> ProvenanceRelation<Vec<T>, P>

pub fn to_nary_relation<I, S>( &self, schema: I, ) -> Result<NaryRelation<T>, NaryRelationError>

where I: IntoIterator<Item = S>, S: Into<String>,

Converts row facts into an n-ary relation with the given schema.

The explicit schema preserves the current exact n-ary boundary where row values do not themselves encode column names. This method reuses the current NaryRelation validation rules, so duplicate or blank column names and row-arity mismatches return NaryRelationError. Generic code can access the same n-ary materialization boundary through crate::ToExactNaryRelation.

Examples

use relmath::provenance::ProvenanceRelation;

let rows = ProvenanceRelation::from_facts([
    (vec!["Alice", "Math", "passed"], "gradebook"),
    (vec!["Alice", "Math", "passed"], "reviewed"),
    (vec!["Bob", "Physics", "passed"], "gradebook"),
]);

let relation = rows
    .to_nary_relation(["student", "course", "status"])
    .expect("expected valid support relation");

assert_eq!(
    relation.to_rows(),
    vec![
        vec!["Alice", "Math", "passed"],
        vec!["Bob", "Physics", "passed"],
    ]
);

Trait Implementations

impl<F: Clone + Ord, P: Clone + Ord> Clone for ProvenanceRelation<F, P>

fn clone(&self) -> ProvenanceRelation<F, P>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: Debug + Ord, P: Debug + Ord> Debug for ProvenanceRelation<F, P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: Ord, P: Ord> Default for ProvenanceRelation<F, P>

fn default() -> Self

Returns the “default value” for a type.

impl<F: Ord + Clone, P: Ord> ExactSupport<F> for ProvenanceRelation<F, P>

fn exact_support(&self) -> UnaryRelation<F>

Returns the exact support of stored facts in deterministic fact order.

impl<F: Ord, P: Ord> Extend<(F, P)> for ProvenanceRelation<F, P>

fn extend<I: IntoIterator<Item = (F, P)>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<F: Ord, P: Ord> FiniteRelation for ProvenanceRelation<F, P>

fn len(&self) -> usize

Returns the number of stored tuples in the relation.

fn is_empty(&self) -> bool

Returns true when the relation contains no tuples.

impl<F: Ord, P: Ord> FromIterator<(F, P)> for ProvenanceRelation<F, P>

fn from_iter<I: IntoIterator<Item = (F, P)>>(iter: I) -> Self

Creates a value from an iterator.

impl<F: PartialEq + Ord, P: PartialEq + Ord> PartialEq for ProvenanceRelation<F, P>

fn eq(&self, other: &ProvenanceRelation<F, P>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<F: Eq + Ord, P: Eq + Ord> Eq for ProvenanceRelation<F, P>

impl<F: Ord, P: Ord> StructuralPartialEq for ProvenanceRelation<F, P>