This website uses Javascript to render markdown documents in your browser, apply syntax highlighting to code fragments and render $\LaTeX$ formulas. Below is the markdown source code of this page. You can either read that or enable Javascript to have it rendered to HTML.

# NAME

CInet::Relation - An abstract (local) CI relation

# SYNOPSIS

    # Create a relation from a string representation
    my $A = CInet::Relation->new(Cube(5) => '01111111110111111110111111110111111011111111111011111101111101111011111111011111');

    # Partially defined and oriented structures are supported
    # You may use '_' characters (which are ignored) for readbility
    my $U = CInet::Relation->new(Cube(4) => '****_---0_----_0---_++++_+*++');

    # Print all isomorphic relations (with repetition)
    # in the same binary format.
    use Algorithm::Combinatorics qw(permutations);
    say $A->permute($_) for permutations($A->cube->set);

# DESCRIPTION

`CInet::Relation` is the main object of interest of this distribution.
It represents an abstract CI relation (or CI structure), that is a
collection of local or elementary conditional independence statements
`(ij|K)`, potentially with abstract coefficients. Some methods also
deal with global or non-elementary CI statements of the form `(A,B|C)`,
but the CI structure is represented in the local mode assuming semigraphhoid
semantics; cf. [cival](#cival) for details.

Each relation requires a domain in the form of a [CInet::Cube](/doc/CInet%3A%3ACube) to be
attached to it, which provides access to the ground set of the relation.
A CInet::Relation is a mapping of its cube's `->squares` to certain
coefficients. The type of coefficients used determines the type of
relation and how it is treated by other code:

- **0** and **1** mean true and false, respectively. Read that again:
**0** means true and **1** means false. This may seem backwards at
first, but it makes sense when you think of conditional independence
(the symbol is true) as an equation and dependence (the symbol is
false) as an inequation. A CI structure using only these coefficients
is _ordinary_ and is the most common type.
- One can use additionally **+** and **-** to make the structure _oriented_.
The **+** and **-** refine dependencies (**1**) into positive and negative
correlations. It is legal to mix **+**, **-** and **1**, depending on how
much you know about specific dependencies.
- The symbol **\*** can be used for to denote unknown dependence status.
A CI structure with some **\*** coefficient is _partially defined_.
It may be ordinary or oriented otherwise.

This package provides methods for manipulating CI structures to the
extent that computational methods are available in this Base distribution:
acting with symmetry groups, taking minors, embedding, meeting and
joining structures.

Other topical modules in the `CInet::*` namespace will **extend**
this package from the outside by supplying new methods. For example,
[CInet::Polyhedral](/doc/CInet%3A%3APolyhedral) concerns approximations of the entropic region
with polyhedral cones. These approximations cast a combinatorial
shadow on conditional independence relations and so that module
would add a method to CInet::Relation to check whether a CI structure
is realized by a polymatroid. Another package, [CInet::Algebraic](/doc/CInet%3A%3AAlgebraic)
concerns Gaussian-like distributions over arbitrary fields and
adds a method to check realizability of a CInet::Relation in that
sense. If you load the topical module, these methods automatically
become available on every CInet::Relation instance you have around.

## Methods

### new

    my $A = CInet::Relation->new($cube);
    my $A = CInet::Relation->new($cube => '111010001...');
    my $A = CInet::Relation->new($cube => [[1,2],[3]], [[1,5],[2]], ...);

Create a new CInet::Relation object. The first argument is the mandatory
[CInet::Cube](/doc/CInet%3A%3ACube) instance which provides the ground set of the relation.

The second argument is an optional string that gives the exact CI structure
as a string of coefficients, just like one that the [str](#str) method
would produce. If this string is not provided, the structure starts out
completely undefined, that is consisting of all **\*** coefficients.
The character `_` in the input string is ignored. You can use it to
separate chunks of the data for human readability.

Alternatively, the CI structure can be specified by giving a list of
CI statements which should hold. These are either encoded as arrayrefs
with two elements (denoting an elementary CI statement `ij|K`, or a
2-face of `$cube`) or an arrayref with three elements (denoting a
non-elementary CI statement `A,B|C`).

### clone

    my $B = $A->clone

Creates a deep copy of the relation.

### cube

    my $cube = $A->cube

Retrieve the [CInet::Cube](/doc/CInet%3A%3ACube) domain of this relation.

### cival :lvalue

    say $A->cival($ijK);    # 1 - dependent
    $A->cival($ijK) = '+';  # orient positively

Return or set the "coefficient" of a given square `$ijK`.

This method can also be used with a non-elementary CI statement `(A,B|C)`
in which case it sets all associated elementary CI statements to the given value.
If the value of a non-elementary CI statement is read, then all associated
elementary CI statements are read first. If they all have the same value,
that value is returned. Otherwise the value is `1`. See [CInet::Cube](/doc/CInet%3A%3ACube#squares)
for more information about the encoding of non-elementary CI statements.

### ci

    say $A->ci($ijK) ? "independent" : "dependent";

Given a square `$ijK` or a non-elementary CI statement, return whether
its corresponding CI statement holds in the relation.

The statement holds if and only if its coefficient is **0**. It is not
taken to hold when it is undefined.

### independences

    my @indeps = $A->independences;

Return all independence statements that hold for the relation, as a list
of `$cube->squares` objects. These are all squares for which the
coefficient is **0**.

### dependences

    my @deps = $A->dependences;

Return all dependence statements that hold for the relation, as a list
of `$cube->squares` objects. A statement with coefficient **1**,
**+** or **-** is dependent.

### permute

    my $Ap = $A->permute($p);

Apply a permutation of the ground set to the relation. The resulting
structure exists over the same `$cube` and contains exactly the images
of the invocant's squares under the `$cube->permute` method.

### dual

    my $Ad = $A->dual;

Return the dual relation. The return value exists over the same `$cube`
and contains exactly the images of the invocant's squares under the
`$cube->dual` method.

### swap

    my $AZ = $A->swap($Z);

Apply a swap of the ground set to the relation. The resulting structure
exists over the same `$cube` and contains exactly the images of the
invocant's squares under the `$cube->swap` method.

### act

    my $Ag = $A->act($g);

Apply a permutation `$g` of the array `$cube->squares` to the
relation. All groups in [CInet::Symmetry](/doc/CInet%3A%3ASymmetry) are implemented in this form.
The returned structure exists over the same cube.

### invact

    my $Ag = $A->invact($g);

Like [act](#act) but applies the inverse permutation.

### orbit

    my $seq = $A->orbit(SymmetricGroup);

Return a [CInet::Seq](/doc/CInet%3A%3ASeq) instance which enumerates the orbit of the
invocant under a given symmetric group from [CInet::Symmetry](/doc/CInet%3A%3ASymmetry).
If a `CInet::Symmetry::Type` is passed, it will be instantiated
with `$A->cube`.

### representative

    my $rep = $A->representative(SymmetricGroup);

Return the distinguished representative of the invocant's orbit
under a given symmetric group from [CInet::Symmetry](/doc/CInet%3A%3ASymmetry). If a
`CInet::Symmetry::Type` is passed, it will be instantiated with
`$A->cube`.

This method will always return a distinguished representative of
the symmetry orbit. This is unlike other methods, for examples in
[CInet::Seq::Modulo](/doc/CInet%3A%3ASeq%3A%3AModulo), which return the first element encountered
from every incoming orbit.

The representative is distinguished by having the lexicographically
smallest stringification.

### delete

    my $Ad = $A->delete($K);

Return the minor of `$A` where the elements of `$K` are deleted.

### contract

    my $Ac = $A->contract($K);

Return the minor of `$A` where the elements of `$K` are contracted.

### minor

    my $a = $A->minor($IK);

Return the `I|K`-minor of the invocant. This is the structure
obtained by marginalizing to `I ∪ K` and then conditioning `K`.
Equivalently, it contains all the squares which lie on the
`I|K`-face of the ambient cube. The minor is defined over
the ground set `$I`. The required cube object is obtained from
the `Cube` sub.

The opposite of this method is [embed](#embed).

### embed

    my $A = $a->embed($M, $NL);

When the invocant is a structure over ground set `$N` and given a
larger ground set `$M` and a face `[$N, $L]` of the cube over `$M`,
this method produces a new structure over `$M` which contains the
invocant's squares embedded into the `N|L`-face and nothing else.

The `$NL` argument is optional and defaults to `N|Ø`.

The opposite of this method is [minor](#minor).

### minors

    my $k_minors = $A->minors($k, %opts);
    my $all_minors = $A->minors(%opts);

Return a [CInet::Seq](/doc/CInet%3A%3ASeq) object for iterating over all minors of a structure.
With a given dimension `$k`, only the minors in that dimension are enumerated.

If `$opts{faces}` is truthy, then the elements of the Seq are decorated
arrayrefs of `[ $minor_relation, $face ]`. Otherwise (in particular by
default), the Seq enumerates only the minor `CInet::Relation` objects.

### union

    my $AB = $A->union($B);

Return the union of the two given CI structures. This operation is only
defined for 0/1-valued relations on the same ground set.

### intersect

    my $AB = $A->intersect($B);

Return the intersection of the two given CI structures. This operation is
only defined for 0/1-valued relations on the same ground set.

### ID

    my $ID = $A->ID;

Returns the ID of a 0/1-valued relation. This is a hexadecimal rendering
of the bit string. The ID is of fixed length (depending on the ground set),
printable and preserves the CI structure entirely, except for the labeling
on its ground set.

Each chunk of four bits (most significant bit first) in `$A->str` is
converted (in order) to a hexadecimal digit.

### description

    my $str = $A->description;

Returns a human-readable description of the object.

## Overloaded operators

### Addition

    my $C = $A + $B;
    my $C = $A->join($B);

Addition of two CInet::Relation objects over the same ground set
computes their _join_, which is the element-wise commutative
operation defined by the following table:

TODO: NYI

### Multiplication

    my $C = $A * $B;
    my $C = $A->meet($B);

Multiplication of two CInet::Relation objects over the same ground set
computes their _meet_, which is the element-wise commutative operation
defined by the following table

TODO: NYI

### Stringification and string comparison

    say $A;  # 11101001...
    say $A eq $B; # compare

The string representing the CI structure contains `$cube->squres`-many
symbols from the coefficient alphabet **0**, **1**, **+**, **-**, **\***.
Each symbol corresponds to a CI statement via the proper ordering of squares
documented in [CInet::Cube](/doc/CInet%3A%3ACube).

String comparison functions automatically use the stringification.

## AUTOLOAD

    $A->unknown_method;
    # dies but helpfully

Since CInet::Relation is pieced together from multiple distributions,
it can happen that you call a method on it which is implemented in a
module which you forgot to load. We supply an AUTOLOAD which catches
all unknown methods and displays a reminder about that.

## Exports

### CIR :Export(:DEFAULT)

    my $A = CIR(@args);

This is a shorthand for the `CInet::Relation->new` constructor.

This sub is exported by default.

# AUTHOR

Tobias Boege <tobs@taboege.de>

# COPYRIGHT AND LICENSE

This software is copyright (C) 2020 by Tobias Boege.

This is free software; you can redistribute it and/or
modify it under the terms of the Artistic License 2.0.