add optional unobserved_links param to some mrrms

Author: arashbm

CMakeLists.txt

@@ -9,7 +9,7 @@ include(FetchContent)
 FetchContent_Declare(
   reticula
   GIT_REPOSITORY https://github.com/reticula-network/reticula.git
-  GIT_TAG a349e8771342ac689ce38d64d3936b80b46c75ce)
+  GIT_TAG 5152713c036c9801c8e309d784cf19dadb589b98)
 
 FetchContent_Declare(
   fmt

docs/shuffling/link.rst

@@ -40,6 +40,10 @@ Connected link shuffling
 
     .. py:function:: microcanonical_reference_models.connected_link_shuffling(\
           temporal_network, random_state)
+       :no-index:
+
+    .. py:function:: microcanonical_reference_models.connected_link_shuffling(\
+          temporal_network, random_state, unobserved_links: list)
 
   .. tab-item:: C++
     :sync: cpp
@@ -51,6 +55,15 @@ Connected link shuffling
           microcanonical_reference_models::connected_link_shuffling(\
             const network<EdgeT>& temp, Gen& generator)
 
+    .. cpp:function:: template <temporal_network_edge EdgeT, \
+        std::uniform_random_bit_generator Gen> \
+        requires is_dyadic_v<EdgeT> \
+        network<EdgeT> \
+        microcanonical_reference_models::connected_link_shuffling(\
+          const network<EdgeT>& temp, Gen& generator, \
+          const std::vector<typename EdgeT::StaticProjectionType>& \
+          unobserved_links)
+
 Produces a random shuffling of the temporal network where all events between two
 vertices are attributed to two randomly selected vertices from the original
 network. As opposed to `Link shuffling`, this model preserves the pattern of
@@ -60,6 +73,13 @@ components as the input. Generalisation of the micocanonical reference model
 with the canonical name :math:`P[I_\lambda, p_{\mathcal{L}}(\Theta)]` to
 temporal networks with directed and/or multi-component static projections.
 
+The observed static projection links in the network are complemented by the set
+of links passed through the parameter `unobserved_links`. This is used in case
+links are omitted in the static projection of the observed temporal network
+that are known to exist from other sources. Essentially, it is assumed that the
+links in `unobserved_links` would be present in the static projection of the
+temporal network had we had a long enough observation window.
+
 In addition to the set of components of the static projection, the set of
 vertices, timestamps, the number of events and the multiset of timelines
 of the temporal network are conserved.
@@ -75,6 +95,11 @@ Topology-constrained link shuffling
     .. py:function:: \
           microcanonical_reference_models.topology_constrained_link_shuffling(\
             temporal_network, random_state)
+       :no-index:
+
+    .. py:function:: \
+        microcanonical_reference_models.topology_constrained_link_shuffling(\
+          temporal_network, random_state, unobserved_links: list)
 
   .. tab-item:: C++
     :sync: cpp
@@ -86,11 +111,27 @@ Topology-constrained link shuffling
           microcanonical_reference_models::topology_constrained_link_shuffling(\
             const network<EdgeT>& temp, Gen& generator)
 
+    .. cpp:function:: template <temporal_network_edge EdgeT, \
+        std::uniform_random_bit_generator Gen> \
+        requires is_dyadic_v<EdgeT> \
+        network<EdgeT> \
+        microcanonical_reference_models::topology_constrained_link_shuffling(\
+          const network<EdgeT>& temp, Gen& generator, \
+          const std::vector<typename EdgeT::StaticProjectionType>& \
+          unobserved_links)
+
 
 Produces a random shuffling of the temporal network where the events are
 shuffled by assigning new, uniformly random timetamps and moving it to a
 randomly selected link with a non-empty timeline. Equivalent to micocanonical
 reference model with the canonical name :math:`P[\mathcal{L}, E]`.
 
+The observed static projection links in the network are complemented by the set
+of links passed through the parameter `unobserved_links`. This is used in case
+links are omitted in the static projection of the observed temporal network
+that are known to exist from other sources. Essentially, it is assumed that the
+links in `unobserved_links` would be present in the static projection of the
+temporal network had we had a long enough observation window.
+
 The set of vertices, total number of events and the static projection of the
 temporal network are conserved.

docs/shuffling/timeline.rst

@@ -11,9 +11,19 @@ Timeline shuffling
 
     .. py:function:: microcanonical_reference_models.timeline_shuffling(\
           temporal_network, random_state)
+       :no-index:
 
     .. py:function:: microcanonical_reference_models.timeline_shuffling(\
           temporal_network, random_state, t_start, t_end)
+       :no-index:
+
+    .. py:function:: microcanonical_reference_models.timeline_shuffling(\
+          temporal_network, random_state, unobserved_links: list)
+       :no-index:
+
+    .. py:function:: microcanonical_reference_models.timeline_shuffling(\
+          temporal_network, random_state, t_start, t_end, unobserved_links: list)
+       :no-index:
 
   .. tab-item:: C++
     :sync: cpp
@@ -33,6 +43,26 @@ Timeline shuffling
              const network<EdgeT>& temp, Gen& generator, \
              typename EdgeT::TimeType t_start, typename EdgeT::TimeType t_end);
 
+    .. cpp:function:: template <temporal_network_edge EdgeT, \
+          std::uniform_random_bit_generator Gen> \
+          requires is_dyadic_v<EdgeT> \
+          network<EdgeT> \
+          microcanonical_reference_models::timeline_shuffling(\
+             const network<EdgeT>& temp, Gen& generator, \
+             const std::vector<typename EdgeT::StaticProjectionType>& \
+             unobserved_links);
+
+    .. cpp:function:: template <temporal_network_edge EdgeT, \
+          std::uniform_random_bit_generator Gen> \
+          requires is_dyadic_v<EdgeT> \
+          network<EdgeT> \
+          microcanonical_reference_models::timeline_shuffling(\
+             const network<EdgeT>& temp, Gen& generator, \
+             typename EdgeT::TimeType t_start, typename EdgeT::TimeType t_end, \
+             const std::vector<typename EdgeT::StaticProjectionType>& \
+             unobserved_links);
+
+
 Produces a random shuffling of the temporal network where the events are
 shuffled by assigning new, uniformly random timetamps and moving it to a
 randomly selected link with a non-empty timeline. Equivalent to the
@@ -46,6 +76,13 @@ maximum cause time of all the events to automatically set values for parameters
 :cpp:`t_start` and :cpp:`t_end`, for cases where information about observation
 window is not available.
 
+The observed static projection links in the network are complemented by the set
+of links passed through the parameter `unobserved_links`. This is used in case
+links are omitted in the static projection of the observed temporal network
+that are known to exist from other sources. Essentially, it is assumed that the
+links in `unobserved_links` would be present in the static projection of the
+temporal network had we had a long enough observation window.
+
 The set of vertices, total number of events and the static projection of
 the temporal network are conserved.
 

src/temporal_microcanonical_reference_models.cpp

@@ -16,19 +16,53 @@ struct declare_temporal_mrrm_algorithms {
         &reticula::mrrms::instant_event_shuffling<EdgeT, Gen>,
         "temporal_network"_a, "random_state"_a,
         nb::call_guard<nb::gil_scoped_release>());
+
     m.def("link_shuffling",
         &reticula::mrrms::link_shuffling<EdgeT, Gen>,
         "temporal_network"_a, "random_state"_a,
         nb::call_guard<nb::gil_scoped_release>());
+
     m.def("connected_link_shuffling",
-        &reticula::mrrms::connected_link_shuffling<EdgeT, Gen>,
+        nb::overload_cast<const reticula::network<EdgeT>&, Gen&>(
+            &reticula::mrrms::connected_link_shuffling<EdgeT, Gen>),
         "temporal_network"_a, "random_state"_a,
         nb::call_guard<nb::gil_scoped_release>());
+    m.def("connected_link_shuffling",
+        nb::overload_cast<const reticula::network<EdgeT>&, Gen&,
+              const std::vector<typename EdgeT::StaticProjectionType>&>(
+            &reticula::mrrms::connected_link_shuffling<EdgeT, Gen >),
+        "temporal_network"_a, "random_state"_a, "unobserved_links"_a,
+        nb::call_guard<nb::gil_scoped_release>());
+
     m.def("topology_constrained_link_shuffling",
-        &reticula::mrrms::topology_constrained_link_shuffling<EdgeT, Gen>,
+        nb::overload_cast<const reticula::network<EdgeT>&, Gen&>(
+            &reticula::mrrms::topology_constrained_link_shuffling<EdgeT, Gen>),
         "temporal_network"_a, "random_state"_a,
         nb::call_guard<nb::gil_scoped_release>());
+    m.def("topology_constrained_link_shuffling",
+        nb::overload_cast<const reticula::network<EdgeT>&, Gen&,
+              const std::vector<typename EdgeT::StaticProjectionType>&>(
+            &reticula::mrrms::topology_constrained_link_shuffling<EdgeT, Gen>),
+        "temporal_network"_a, "random_state"_a, "unordered_links"_a,
+        nb::call_guard<nb::gil_scoped_release>());
 
+
+    m.def("timeline_shuffling",
+        nb::overload_cast<
+                const reticula::network<EdgeT>&, Gen&,
+                typename EdgeT::TimeType, typename EdgeT::TimeType,
+                const std::vector<typename EdgeT::StaticProjectionType>&>(
+            &reticula::mrrms::timeline_shuffling<EdgeT, Gen>),
+        "temporal_network"_a, "random_state"_a,
+        "t_start"_a, "t_end"_a, "unobserved_links"_a,
+        nb::call_guard<nb::gil_scoped_release>());
+    m.def("timeline_shuffling",
+        nb::overload_cast<
+                const reticula::network<EdgeT>&, Gen&,
+                const std::vector<typename EdgeT::StaticProjectionType>&>(
+            &reticula::mrrms::timeline_shuffling<EdgeT, Gen>),
+        "temporal_network"_a, "random_state"_a, "unobserved_links"_a,
+        nb::call_guard<nb::gil_scoped_release>());
     m.def("timeline_shuffling",
         nb::overload_cast<
                 const reticula::network<EdgeT>&, Gen&,
@@ -41,6 +75,7 @@ struct declare_temporal_mrrm_algorithms {
             &reticula::mrrms::timeline_shuffling<EdgeT, Gen>),
         "temporal_network"_a, "random_state"_a,
         nb::call_guard<nb::gil_scoped_release>());
+
     m.def("weight_constrained_timeline_shuffling",
         nb::overload_cast<
             const reticula::network<EdgeT>&, Gen&,
@@ -53,10 +88,12 @@ struct declare_temporal_mrrm_algorithms {
           &reticula::mrrms::weight_constrained_timeline_shuffling<EdgeT, Gen>),
         "temporal_network"_a, "random_state"_a,
         nb::call_guard<nb::gil_scoped_release>());
+
     m.def("activity_constrained_timeline_shuffling",
         &reticula::mrrms::activity_constrained_timeline_shuffling<EdgeT, Gen>,
         "temporal_network"_a, "random_state"_a,
         nb::call_guard<nb::gil_scoped_release>());
+
     m.def("inter_event_shuffling",
         &reticula::mrrms::inter_event_shuffling<EdgeT, Gen>,
         "temporal_network"_a, "random_state"_a,