dsep documentation

uhlerlab · Jan 8, 2021 · f200e37 · f200e37
1 parent 6322cc0
commit f200e37
Show file tree

Hide file tree

Showing 12 changed files with 135 additions and 19 deletions.
diff --git a/causaldag/classes/dag.py b/causaldag/classes/dag.py
@@ -32,6 +32,7 @@ class DAG:
     """
     Base class for causal DAGs.
     """
+
     def __init__(self, nodes: Set = frozenset(), arcs: Set = frozenset(), dag=None):
         if dag is not None:
             self._nodes = set(dag._nodes)
@@ -1331,7 +1332,15 @@ def confusion_matrix(self, other, rates_only=False):
 
         Examples
         --------
-        TODO
+        >>> import causaldag as cd
+        >>> d1 = cd.DAG(arcs={(0, 1), (1, 2)})
+        >>> d2 = cd.DAG(arcs={(0, 1), (2, 1)})
+        >>> cm = d1.confusion_matrix(d2)
+        >>> cm["mistaken_edges_for_arcs"]
+        {frozenset({0, 1}), frozenset({1, 2})},
+        >>> cm = d2.confusion_matrix(d1)
+        >>> cm["mistaken_arcs_for_edges"]
+        {(0, 1), (2, 1)}
         """
         self_cpdag = self.cpdag()
 
@@ -1451,7 +1460,20 @@ def confusion_matrix_skeleton(self, other):
 
         Examples
         --------
-        TODO
+        >>> import causaldag as cd
+        >>> d1 = cd.DAG(arcs={(0, 1), (1, 2)})
+        >>> d2 = cd.DAG(arcs={(0, 1), (2, 1)})
+        >>> cm = d1.confusion_matrix_skeleton(d2)
+        >>> cm["tpr"]
+        1.0
+        >>> d3 = cd.DAG(arcs={(0, 1), (0, 2)})
+        >>> cm = d2.confusion_matrix_skeleton(d3)
+        >>> cm["true_positives"]
+        {frozenset({0, 1})}
+        >>> cm["false_positives"]
+        {frozenset({0, 2})},
+        >>> cm["false_negatives"]
+        {frozenset({1, 2})}
         """
         self_skeleton = self.skeleton
         other_skeleton = other.skeleton
@@ -1826,7 +1848,7 @@ def dsep(self, A: Union[Set[Node], Node], B: Union[Set[Node], Node], C: Union[Se
 
         return True
 
-    def dsep_from_given(self, A, C=set()) -> Set[Node]:
+    def dsep_from_given(self, A, C: NodeSet = frozenset()) -> Set[Node]:
         """
         Find all nodes d-separated from ``A`` given ``C``.
 
@@ -1835,15 +1857,22 @@ def dsep_from_given(self, A, C=set()) -> Set[Node]:
 
         Parameters
         ----------
-        TODO
+        A:
+            set of nodes.
+        C:
+            set of conditioned nodes.
 
         Returns
         -------
-        TODO
+        set
+            Nodes which are d-separated from ``A`` given ``C``.
 
         Examples
         --------
-        TODO
+        >>> import causaldag as cd
+        >>> d = cd.DAG(arcs={(0, 1), (1, 2), (2, 3), (3, 4)})
+        >>> d.dsep_from_given(0, 1)
+        {2, 3, 4]
         """
         warn_untested()  # TODO: ADD TEST
 
@@ -2328,7 +2357,7 @@ def apply_edge_operation(self, imap, seed_sink=None, verbose=False):
         # STEP 5: PICK A SPECIFIC CHILD OF Y IN G
         d = list(imap_subgraph.upstream_most(self_subgraph.descendants_of(sink)))[0]
         valid_children = self_subgraph.upstream_most(self_subgraph._children[sink]) & (
-                    self_subgraph.ancestors_of(d) | {d})
+                self_subgraph.ancestors_of(d) | {d})
         z = random.choice(list(valid_children))
         if verbose: print(f"Step 5: Picked z={z}")
 

diff --git a/sphinx_docs/_build/doctrees/classes/DAG.doctree b/sphinx_docs/_build/doctrees/classes/DAG.doctree
diff --git a/...docs/_build/doctrees/classes/generated/causaldag.classes.dag.DAG.confusion_matrix.doctree b/...docs/_build/doctrees/classes/generated/causaldag.classes.dag.DAG.confusion_matrix.doctree
diff --git a/...ld/doctrees/classes/generated/causaldag.classes.dag.DAG.confusion_matrix_skeleton.doctree b/...ld/doctrees/classes/generated/causaldag.classes.dag.DAG.confusion_matrix_skeleton.doctree
diff --git a/..._docs/_build/doctrees/classes/generated/causaldag.classes.dag.DAG.dsep_from_given.doctree b/..._docs/_build/doctrees/classes/generated/causaldag.classes.dag.DAG.dsep_from_given.doctree
diff --git a/sphinx_docs/_build/doctrees/environment.pickle b/sphinx_docs/_build/doctrees/environment.pickle
diff --git a/sphinx_docs/_build/html/_modules/causaldag/classes/dag.html b/sphinx_docs/_build/html/_modules/causaldag/classes/dag.html
@@ -188,6 +188,7 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
     <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Base class for causal DAGs.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
+
     <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">nodes</span><span class="p">:</span> <span class="n">Set</span> <span class="o">=</span> <span class="nb">frozenset</span><span class="p">(),</span> <span class="n">arcs</span><span class="p">:</span> <span class="n">Set</span> <span class="o">=</span> <span class="nb">frozenset</span><span class="p">(),</span> <span class="n">dag</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
         <span class="k">if</span> <span class="n">dag</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">_nodes</span> <span class="o">=</span> <span class="nb">set</span><span class="p">(</span><span class="n">dag</span><span class="o">.</span><span class="n">_nodes</span><span class="p">)</span>
@@ -1484,6 +1485,18 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
 <span class="sd">            * precision:</span>
 <span class="sd">                the precision, i.e., num_true_positives/(num_true_positives+num_false_positives). If ``other`` is</span>
 <span class="sd">                empty, defaults to 1.</span>
+
+<span class="sd">        Examples</span>
+<span class="sd">        --------</span>
+<span class="sd">        &gt;&gt;&gt; import causaldag as cd</span>
+<span class="sd">        &gt;&gt;&gt; d1 = cd.DAG(arcs={(0, 1), (1, 2)})</span>
+<span class="sd">        &gt;&gt;&gt; d2 = cd.DAG(arcs={(0, 1), (2, 1)})</span>
+<span class="sd">        &gt;&gt;&gt; cm = d1.confusion_matrix(d2)</span>
+<span class="sd">        &gt;&gt;&gt; cm[&quot;mistaken_edges_for_arcs&quot;]</span>
+<span class="sd">        {frozenset({0, 1}), frozenset({1, 2})},</span>
+<span class="sd">        &gt;&gt;&gt; cm = d2.confusion_matrix(d1)</span>
+<span class="sd">        &gt;&gt;&gt; cm[&quot;mistaken_arcs_for_edges&quot;]</span>
+<span class="sd">        {(0, 1), (2, 1)}</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">self_cpdag</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">cpdag</span><span class="p">()</span>
 
@@ -1600,6 +1613,23 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
 <span class="sd">            * precision:</span>
 <span class="sd">                the precision, i.e., num_true_positives/(num_true_positives+num_false_positives). If ``other`` is</span>
 <span class="sd">                empty, defaults to 1.</span>
+
+<span class="sd">        Examples</span>
+<span class="sd">        --------</span>
+<span class="sd">        &gt;&gt;&gt; import causaldag as cd</span>
+<span class="sd">        &gt;&gt;&gt; d1 = cd.DAG(arcs={(0, 1), (1, 2)})</span>
+<span class="sd">        &gt;&gt;&gt; d2 = cd.DAG(arcs={(0, 1), (2, 1)})</span>
+<span class="sd">        &gt;&gt;&gt; cm = d1.confusion_matrix_skeleton(d2)</span>
+<span class="sd">        &gt;&gt;&gt; cm[&quot;tpr&quot;]</span>
+<span class="sd">        1.0</span>
+<span class="sd">        &gt;&gt;&gt; d3 = cd.DAG(arcs={(0, 1), (0, 2)})</span>
+<span class="sd">        &gt;&gt;&gt; cm = d2.confusion_matrix_skeleton(d3)</span>
+<span class="sd">        &gt;&gt;&gt; cm[&quot;true_positives&quot;]</span>
+<span class="sd">        {frozenset({0, 1})}</span>
+<span class="sd">        &gt;&gt;&gt; cm[&quot;false_positives&quot;]</span>
+<span class="sd">        {frozenset({0, 2})},</span>
+<span class="sd">        &gt;&gt;&gt; cm[&quot;false_negatives&quot;]</span>
+<span class="sd">        {frozenset({1, 2})}</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">self_skeleton</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">skeleton</span>
         <span class="n">other_skeleton</span> <span class="o">=</span> <span class="n">other</span><span class="o">.</span><span class="n">skeleton</span>
@@ -1634,10 +1664,19 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
         <span class="k">return</span> <span class="n">res</span></div>
 
     <span class="c1"># === WRITING TO FILES</span>
+    <span class="nd">@classmethod</span>
+    <span class="k">def</span> <span class="nf">from_gml</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
+        <span class="k">raise</span> <span class="ne">NotImplementedError</span>
+
+    <span class="nd">@classmethod</span>
+    <span class="k">def</span> <span class="nf">from_csv</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
+        <span class="k">raise</span> <span class="ne">NotImplementedError</span>
+
     <span class="k">def</span> <span class="nf">save_gml</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        TODO</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">raise</span> <span class="ne">NotImplementedError</span>
         <span class="n">warn_untested</span><span class="p">()</span>  <span class="c1"># TODO: ADD TEST</span>
 
         <span class="n">tab</span> <span class="o">=</span> <span class="s1">&#39;  &#39;</span>
@@ -1678,6 +1717,7 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
         <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        TODO</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">raise</span> <span class="ne">NotImplementedError</span>
         <span class="n">warn_untested</span><span class="p">()</span>  <span class="c1"># TODO: ADD TEST</span>
 
         <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">file</span><span class="p">:</span>
@@ -1964,7 +2004,7 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
 
         <span class="k">return</span> <span class="kc">True</span></div>
 
-<div class="viewcode-block" id="DAG.dsep_from_given"><a class="viewcode-back" href="../../../classes/generated/causaldag.classes.dag.DAG.dsep_from_given.html#causaldag.classes.dag.DAG.dsep_from_given">[docs]</a>    <span class="k">def</span> <span class="nf">dsep_from_given</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">A</span><span class="p">,</span> <span class="n">C</span><span class="o">=</span><span class="nb">set</span><span class="p">())</span> <span class="o">-&gt;</span> <span class="n">Set</span><span class="p">[</span><span class="n">Node</span><span class="p">]:</span>
+<div class="viewcode-block" id="DAG.dsep_from_given"><a class="viewcode-back" href="../../../classes/generated/causaldag.classes.dag.DAG.dsep_from_given.html#causaldag.classes.dag.DAG.dsep_from_given">[docs]</a>    <span class="k">def</span> <span class="nf">dsep_from_given</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">A</span><span class="p">,</span> <span class="n">C</span><span class="p">:</span> <span class="n">NodeSet</span> <span class="o">=</span> <span class="nb">frozenset</span><span class="p">())</span> <span class="o">-&gt;</span> <span class="n">Set</span><span class="p">[</span><span class="n">Node</span><span class="p">]:</span>
         <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Find all nodes d-separated from ``A`` given ``C``.</span>
 
@@ -1973,15 +2013,22 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
 
 <span class="sd">        Parameters</span>
 <span class="sd">        ----------</span>
-<span class="sd">        TODO</span>
+<span class="sd">        A:</span>
+<span class="sd">            set of nodes.</span>
+<span class="sd">        C:</span>
+<span class="sd">            set of conditioned nodes.</span>
 
 <span class="sd">        Returns</span>
 <span class="sd">        -------</span>
-<span class="sd">        TODO</span>
+<span class="sd">        set</span>
+<span class="sd">            Nodes which are d-separated from ``A`` given ``C``.</span>
 
 <span class="sd">        Examples</span>
 <span class="sd">        --------</span>
-<span class="sd">        TODO</span>
+<span class="sd">        &gt;&gt;&gt; import causaldag as cd</span>
+<span class="sd">        &gt;&gt;&gt; d = cd.DAG(arcs={(0, 1), (1, 2), (2, 3), (3, 4)})</span>
+<span class="sd">        &gt;&gt;&gt; d.dsep_from_given(0, 1)</span>
+<span class="sd">        {2, 3, 4]</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">warn_untested</span><span class="p">()</span>  <span class="c1"># TODO: ADD TEST</span>
 
@@ -2466,7 +2513,7 @@ <h1>Source code for causaldag.classes.dag</h1><div class="highlight"><pre>
         <span class="c1"># STEP 5: PICK A SPECIFIC CHILD OF Y IN G</span>
         <span class="n">d</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">imap_subgraph</span><span class="o">.</span><span class="n">upstream_most</span><span class="p">(</span><span class="n">self_subgraph</span><span class="o">.</span><span class="n">descendants_of</span><span class="p">(</span><span class="n">sink</span><span class="p">)))[</span><span class="mi">0</span><span class="p">]</span>
         <span class="n">valid_children</span> <span class="o">=</span> <span class="n">self_subgraph</span><span class="o">.</span><span class="n">upstream_most</span><span class="p">(</span><span class="n">self_subgraph</span><span class="o">.</span><span class="n">_children</span><span class="p">[</span><span class="n">sink</span><span class="p">])</span> <span class="o">&amp;</span> <span class="p">(</span>
-                    <span class="n">self_subgraph</span><span class="o">.</span><span class="n">ancestors_of</span><span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="o">|</span> <span class="p">{</span><span class="n">d</span><span class="p">})</span>
+                <span class="n">self_subgraph</span><span class="o">.</span><span class="n">ancestors_of</span><span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="o">|</span> <span class="p">{</span><span class="n">d</span><span class="p">})</span>
         <span class="n">z</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="n">valid_children</span><span class="p">))</span>
         <span class="k">if</span> <span class="n">verbose</span><span class="p">:</span> <span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="s2">&quot;Step 5: Picked z=</span><span class="si">{z}</span><span class="s2">&quot;</span><span class="p">)</span>
 

diff --git a/sphinx_docs/_build/html/classes/DAG.html b/sphinx_docs/_build/html/classes/DAG.html
@@ -470,7 +470,7 @@ <h2>Separation statements<a class="headerlink" href="#separation-statements" tit
 <tr class="row-odd"><td><a class="reference internal" href="generated/causaldag.classes.dag.DAG.dsep.html#causaldag.classes.dag.DAG.dsep" title="causaldag.classes.dag.DAG.dsep"><code class="xref py py-obj docutils literal notranslate"><span class="pre">DAG.dsep</span></code></a>(A,&nbsp;Hashable],&nbsp;B,&nbsp;Hashable],&nbsp;C,&nbsp;…)</td>
 <td>Check if <code class="docutils literal notranslate"><span class="pre">A</span></code> and <code class="docutils literal notranslate"><span class="pre">B</span></code> are d-separated given <code class="docutils literal notranslate"><span class="pre">C</span></code>, using the Bayes ball algorithm.</td>
 </tr>
-<tr class="row-even"><td><a class="reference internal" href="generated/causaldag.classes.dag.DAG.dsep_from_given.html#causaldag.classes.dag.DAG.dsep_from_given" title="causaldag.classes.dag.DAG.dsep_from_given"><code class="xref py py-obj docutils literal notranslate"><span class="pre">DAG.dsep_from_given</span></code></a>(A[,&nbsp;C])</td>
+<tr class="row-even"><td><a class="reference internal" href="generated/causaldag.classes.dag.DAG.dsep_from_given.html#causaldag.classes.dag.DAG.dsep_from_given" title="causaldag.classes.dag.DAG.dsep_from_given"><code class="xref py py-obj docutils literal notranslate"><span class="pre">DAG.dsep_from_given</span></code></a>(A,&nbsp;C,&nbsp;…)</td>
 <td>Find all nodes d-separated from <code class="docutils literal notranslate"><span class="pre">A</span></code> given <code class="docutils literal notranslate"><span class="pre">C</span></code>.</td>
 </tr>
 <tr class="row-odd"><td><a class="reference internal" href="generated/causaldag.classes.dag.DAG.is_invariant.html#causaldag.classes.dag.DAG.is_invariant" title="causaldag.classes.dag.DAG.is_invariant"><code class="xref py py-obj docutils literal notranslate"><span class="pre">DAG.is_invariant</span></code></a>(A,&nbsp;intervened_nodes[,&nbsp;…])</td>

diff --git a/sphinx_docs/_build/html/classes/generated/causaldag.classes.dag.DAG.confusion_matrix.html b/sphinx_docs/_build/html/classes/generated/causaldag.classes.dag.DAG.confusion_matrix.html
@@ -301,6 +301,18 @@ <h1>causaldag.classes.dag.DAG.confusion_matrix<a class="headerlink" href="#causa
 </tr>
 </tbody>
 </table>
+<p class="rubric">Examples</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">causaldag</span> <span class="k">as</span> <span class="nn">cd</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">d1</span> <span class="o">=</span> <span class="n">cd</span><span class="o">.</span><span class="n">DAG</span><span class="p">(</span><span class="n">arcs</span><span class="o">=</span><span class="p">{(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)})</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">d2</span> <span class="o">=</span> <span class="n">cd</span><span class="o">.</span><span class="n">DAG</span><span class="p">(</span><span class="n">arcs</span><span class="o">=</span><span class="p">{(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">)})</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">cm</span> <span class="o">=</span> <span class="n">d1</span><span class="o">.</span><span class="n">confusion_matrix</span><span class="p">(</span><span class="n">d2</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">cm</span><span class="p">[</span><span class="s2">&quot;mistaken_edges_for_arcs&quot;</span><span class="p">]</span>
+<span class="go">{frozenset({0, 1}), frozenset({1, 2})},</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">cm</span> <span class="o">=</span> <span class="n">d2</span><span class="o">.</span><span class="n">confusion_matrix</span><span class="p">(</span><span class="n">d1</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">cm</span><span class="p">[</span><span class="s2">&quot;mistaken_arcs_for_edges&quot;</span><span class="p">]</span>
+<span class="go">{(0, 1), (2, 1)}</span>
+</pre></div>
+</div>
 </dd></dl>
 
 </div>