from typing import Optional, Union
from .types import is_static_graph, is_temporal_graph
from ..typing import StaticGraph, TemporalGraph
[docs]
def temporal_graph(
t: Optional[int] = None,
directed: bool = False,
multigraph: bool = True,
create_using: Optional[Union[TemporalGraph, StaticGraph]] = None,
) -> TemporalGraph:
""" Creates a temporal graph with the desired properties. Similar to
`empty_graph <https://networkx.org/documentation/stable/reference/generated/networkx.generators.classic.empty_graph.html>`__
from NetworkX.
This is a factory function for temporal graphs. It returns a
:class:`~networkx_temporal.classes.TemporalGraph`,
:class:`~networkx_temporal.classes.TemporalDiGraph`,
:class:`~networkx_temporal.classes.TemporalMultiGraph`, or
:class:`~networkx_temporal.classes.TemporalMultiDiGraph`
object, depending on the choice of parameters.
.. hint::
Setting ``t`` as greater than ``1`` initializes a list of NetworkX graph objects, each
representing a snapshot in time. Unless dynamic node attributes are required, it is
recommended to use the :func:`~networkx_temporal.classes.TemporalGraph.slice` method instead,
allowing to create less resource-demanding graph `views
<https://networkx.org/documentation/stable/reference/classes/generated/networkx.classes.graphviews.subgraph_view.html>`__
on the fly.
.. rubric:: Example
Creating a temporal directed multigraph with a single snapshot:
.. code-block:: python
>>> import networkx_temporal as tx
>>>
>>> TG = tx.temporal_graph(directed=True, multigraph=True)
>>> print(TG)
TemporalMultiDiGraph (t=1) with 0 nodes and 0 edges
:param int t: Number of snapshots to initialize. Optional. Default is ``1``.
:param directed: If ``True``, inherits a
`DiGraph <https://networkx.org/documentation/stable/reference/classes/digraph.html>`__.
Defaults to ``False``.
:param multigraph: If ``True``, inherits a
`MultiGraph <https://networkx.org/documentation/stable/reference/classes/multigraph.html>`__.
Defaults to ``True``.
:param object create_using: NetworkX or :class:`~networkx_temporal.classes.TemporalGraph` to use
as template. Optional. Does not allow setting ``directed`` and ``multigraph`` if passed.
"""
if not (directed is None or type(directed) == bool):
raise TypeError(f"Argument `directed` expects a boolean, received: {type(directed)}.")
if not (multigraph is None or type(multigraph) == bool):
raise TypeError(f"Argument `multigraph` expects a boolean, received: {type(multigraph)}.")
if not (create_using is None or is_temporal_graph(create_using) or is_static_graph(create_using)):
raise TypeError(
f"Argument `create_using` expects a NetworkX static or temporal graph, "
f"received: {type(create_using)}."
)
if not (create_using is None or (directed is None and multigraph is None)):
raise ValueError("Arguments `directed` and `multigraph` are exclusive with `create_using`.")
if type(create_using) is type:
create_using = create_using()
if create_using is not None:
directed = create_using.is_directed()
multigraph = create_using.is_multigraph()
if multigraph is None:
multigraph = True
from . import TemporalGraph, TemporalDiGraph, TemporalMultiGraph, TemporalMultiDiGraph
return locals()[f"Temporal{'Multi' if multigraph else ''}{'Di' if directed else ''}Graph"](t=t)
[docs]
def empty_graph(
directed: bool = None,
multigraph: bool = None,
create_using: Optional[Union[TemporalGraph, StaticGraph]] = None,
) -> TemporalGraph:
""" Returns a temporal graph without any initialized snapshots.
This function is a wrapper around :func:`~networkx_temporal.classes.temporal_graph`,
setting ``t=0``.
.. rubric:: Example
Creating an empty temporal directed multigraph, without snapshots:
.. code-block:: python
>>> import networkx_temporal as tx
>>>
>>> TG = tx.empty_graph(directed=True, multigraph=True)
>>> print(TG)
TemporalMultiDiGraph (t=0) with 0 nodes and 0 edges
:param directed: If ``True``, inherits a
`DiGraph <https://networkx.org/documentation/stable/reference/classes/digraph.html>`__.
Defaults to ``False``.
:param multigraph: If ``True``, inherits a
`MultiGraph <https://networkx.org/documentation/stable/reference/classes/multigraph.html>`__.
Defaults to ``True``.
:param object create_using: NetworkX or :class:`~networkx_temporal.classes.TemporalGraph` to use
as template. Optional. Does not allow setting ``directed`` and ``multigraph`` if passed.
"""
return temporal_graph(t=0, directed=directed, multigraph=multigraph, create_using=create_using)