TempNet_02_utilities.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Temporal Networks v2.0 #"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Utilities ##\n",
    "The `utils` module of the library contains utility functions for the temporal networks:\n",
    "- data reading and writing;\n",
    "- conversion between representations;\n",
    "- aggregation of the temporal network;\n",
    "- various measures on the temporal network;\n",
    "- quick plot of a network with graph-tools."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import RandTempNet.utils as tnu"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data reading & writing ##\n",
    "\n",
    "All four representations for temporal networks can be used as input and output in text files. The formatting for each is the following:\n",
    "\n",
    "File type             | Format\n",
    "--------------------- | ---------------------------\n",
    "tij.dat               | `t \\t i \\t j \\n`\n",
    "tijtau.dat            | `t \\t i \\t j \\t tau \\n`\n",
    "snapshot_sequence.dat | `t \\t i,j \\t ... \\t y,z \\n`\n",
    "link_stream.dat       | `i,j \\t t_1,tau_1 \\t ... \\t t_n,tau_n \\n`\n",
    "\n",
    "**Description:**\n",
    "- The `tij` format is the most common way to store a temporal network: it simply lists each event `(t,i,j)` of duration one unit time `dt`.\n",
    "- The `tijtau` format is an extension of the previous, where contacts with their duration `tau` are listed instead of events.\n",
    "- The `snapshot_sequence` format lists all time steps, with for each the list of links active during this time step.\n",
    "- The `link_stream` format lists all links in the network aggregated over time, with for each the list of contacts.\n",
    "\n",
    "### `read_tij(filename)` ###\n",
    "This function reads a file indicated by the `filename` string formatted like a tij.dat file, and returns a `tij()` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "tij_data = tnu.read_tij(\"./data/tij.dat\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `read_tijtau(filename)` ###\n",
    "This function reads a file indicated by the `filename` string formatted like a tijtau.dat file, and returns a `tijtau()` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "tijtau_data = tnu.read_tijtau(\"./data/tijtau.dat\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `read_snapshot_sequence(filename,t_i=0,t_f=0,dt=0)` ###\n",
    "This function reads a file indicated by the `filename` string formatted like a snapshot_sequence.dat, and returns a `snapshot_sequence()` object. The initial time `t_i`, the final time `t_f` and the time step duration `dt` can be specified when the function is called. If not, they are automatically extracted from the data to construct the `snapshot_sequence()` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "seq_data = tnu.read_snapshot_sequence(\"./data/timeset.dat\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "seq_data = tnu.read_snapshot_sequence(\"./data/timeset.dat\", 0, 60480, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `read_link_stream()` ###\n",
    "This function reads a file indicated by the `filename` string formatted like a link_stream.dat, and returns a `link_stream()` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "lks_data = tnu.read_link_timeline(\"./data/lks.dat\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `write_tij(filename,tij_data)` ###\n",
    "This function writes a `tij()` object `tij_data` in a file indicated by the `filename` string, with the proper tij.dat format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "tnu.write_tij(\"tij.dat\", tij_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `write_tijtau(filename,tijtau_data)` ###\n",
    "This function writes a `tijtau()` object `tijtau_data` in a file indicated by the `filename` string, with the proper tijtau.dat format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "tnu.write_tijtau(\"tijtau.dat\", tijtau_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `write_snapshot_sequence(filename,seq_data)` ###\n",
    "This function writes a `snapshot_sequence()` object `seq_data` in a file indicated by the `filename` string, with the proper snapshot_sequence.dat format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "tnu.write_snapshot_sequence(\"timeset.dat\", seq_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `write_link_timeline(lks_data)` ###\n",
    "This function writes a `link_timeline()` object `lks_data` in a file indicated by the `filename` string, with the link_timeline.dat format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "tnu.write_link_timeline(\"lks.dat\", lks_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data conversion ##\n",
    "The main conversion is from event-based data to contact-based data, with the assumption that contiguous events are joined to form contacts. Two functions perform this conversion, one based on the simple `tij` and `tijtau` formats, the other based on the high level `snapshot_sequence` and `link_timeline` formats. Along these conversions, we have two natural conversions, namely between `tij` and `snapshot_sequence`, and between `tijtau` and `link_timeline`. The pathways of conversion are thus the following:\n",
    "\n",
    "**True conversions**\n",
    "- tij $\\leftrightarrow$ tijtau\n",
    "- snapshot_sequence $\\leftrightarrow$ link_timeline\n",
    "\n",
    "**Natural conversions**\n",
    "- tij $\\leftrightarrow$ snapshot_sequence\n",
    "- tijtau $\\leftrightarrow$ link_timeline\n",
    "\n",
    "For conversions towards a `snapshot_sequence()`, one can always specify the first and last time stamp, for cases where the first (respectively last) time stamp is different from the first (respectively last) event.\n",
    "\n",
    "### `tij_to_snapshot_sequence(tij_data,dt,t_i=-1,t_f=0)` ###\n",
    "This function takes a `tij()` object `tij_data` and returns its conversion to a `snapshot_sequence()` object. Specifying the time step duration `dt` is mandatory. The initial time `t_i` and the final time `t_f` are optional, and are by default set to the first step and last time step + 1 of the `tij()` object. If `t_f` is set at a certain value, the last step will be at time step `t_f-1`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "seq_data = tnu.tij_to_snapshot_sequence(tij_data, 1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "seq_data = tnu.tij_to_snapshot_sequence(tij_data, 1, 0, 60480)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `snapshot_sequence_to_tij(seq_data)` ###\n",
    "This function takes a `snapshot_sequence()` object `seq_data` and returns its conversion to a `tij()` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "tij_data = tnu.snapshot_sequence_to_tij(seq_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `tijtau_to_link_timeline(tijtau_data)` ###\n",
    "This function takes a `tijtau()` object `tijtau_data` and returns its conversion to a `link_timeline()` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "lks_data = tnu.tijtau_to_link_timeline(tijtau_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `link_timeline_to_tijtau(lks_data)` ###\n",
    "This function takes a `link_timeline()` object `lks_data` and returns its conversion to a `tijtau()` object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "tijtau_data = tnu.link_timeline_to_tijtau(lks_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `tij_to_tijtau(tij_data,dt,join=True)` ###\n",
    "This function takes a `tij()` object `tij_data` and returns its conversion to a `tijtau()` object. It necessitates the value of the time step `dt`. The optional argument `join` indicates whether consecutive instant-events should be joined or not to define events with durations. Its default value is `True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "tijtau_data = tnu.tij_to_tijtau(tij_data, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `tijtau_to_tij(tijtau_data,dt)` ###\n",
    "This function takes a `tij()` object `tij_data` and returns its conversion to a `tijtau()` object. It necessitates the value of the time step `dt`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "tij_data = tnu.tijtau_to_tij(tijtau_data, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `snapshot_sequence_to_link_timeline(seq_data,dt,join=True)` ###\n",
    "This function takes a `snapshot_sequence()` object `seq_data` and returns its conversion to a `link_timeline()` object.  It necessitates the value of the time step `dt`. The optional argument `join` indicates whether consecutive instant-events should be joined or not to define events with durations. Its default value is `True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "lks_data = tnu.snapshot_sequence_to_link_timeline(seq_data, 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `link_timeline_to_snapshot_sequence(lks_data,dt,t_i=-1,t_f=0)` ###\n",
    "This function takes a `link_timeline()` object `lks_data` and returns its conversion to a `snapshot_sequence()` object. Specifying the time step duration `dt` is mandatory. The initial time `t_i` and the final time `t_f` are optional, and are by default set to the first step and list time step + 1 of the `link_timeline()` object. If `t_f` is set at a certain value, the last step will be at time step `t_f-1`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "seq_data = tnu.link_timeline_to_snapshot_sequence(lks_data, 1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "seq_data = tnu.link_timeline_to_snapshot_sequence(lks_data, 1, 0, 60480)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Aggregation ##\n",
    "In this section we present functions that aggregate a temporal networks along the time. A function is available for each data representation. All functions return a `networkx` `Graph()` object where links have an attribute `w` which gives the total contact duration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "tij_data = tnu.read_tij(\"./data/tij.dat\")\n",
    "tijtau_data = tnu.read_tijtau(\"./data/tijtau.dat\")\n",
    "seq_data = tnu.read_snapshot_sequence(\"./data/timeset.dat\")\n",
    "lks_data = tnu.read_link_timeline(\"./data/lks.dat\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `aggregate_tij(tij_data)` ###\n",
    "This function takes a `tij()` object as input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "G = tnu.aggregate_tij(tij_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `aggregate_tijtau(tijtau_data)` ###\n",
    "This function takes a `tijtau()` object as input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "G = tnu.aggregate_tijtau(tijtau_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `aggregate_snapshot_sequence(seq_data)` ###\n",
    "This function takes a `snapshot_sequence()` object as input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "G = tnu.aggregate_snapshot_sequence(seq_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `aggregate_link_timeline(lks_data)` ###\n",
    "This function takes a `link_timeline()` object as input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "G = tnu.aggregate_link_timeline(lks_data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}