Package: compressnets
compressnetsCompressnets is a Python package designed to compress high-resolution temporal network data (eg. contact networks)
to lower resolution, while maintaining important temporal structural features.Compressnets is designed for taking sequences of static networks (represented as adjacency matrices)
and compressing them to a user-specified reduced number of adjacency matrices. For example, say you
have contact data at the resolution of 20 seconds, over the course of 24 hours, which can be represented
as 4,320 adjacency matrices.
You might wish to compress the data from the original 4,320 adjacency matrices into the best 20 adjacency matrices
that best represent the temporal dynamics. Thecompressnetspackage can help you to progressively aggregate the data into the best 20 representative "snapshots"
(single static network valid for a duration of time).Pre-print with further details on the compression algorithm and theoretical framework is availableon the arXiv.Most basic usageThis example is just to show how to use the package. In practice, 3 starting snapshots is unrealistic as there wouldn't
be a need to use an algorithm for compressing 3 snapshots into 2, so this example just demonstrates package usage in a simple way.
See below for a usage demo using a built-in sample network.To usecompressnets, install the package via the PyPi index viapip install compressnets.The core elements ofcompressnetsare the objects,network.TemporalNetworkandnetwork.Snapshot,
and the algorithmcompression.Compressor.compress(...).Follow along the following example in your own Python workspace withfrom compressnets import compression, networkAs an example, create NumPy arrays to represent your adjacency matrices (or load them from data via your own code):matrix_1 = np.array([[0, 0, 1],[0, 0, 1],[1, 1, 0]])
matrix_2 = np.array([[0, 1, 1],[1, 0, 1],[1, 1, 0]])
matrix_3 = np.array([[0, 1, 0],[1, 0, 1],[0, 1, 0]])Next, you will be creatingSnapshotobjects out of your arrays. A snapshot is simply an adjacency matrix
coupled with a start time, end time, andbetavalue, which will be used in the computation process for the
compression algorithm.Note: While the durations of each snapshot may vary in length from one another, theend_timeof one snapshot should be thestart_timeof the next one. In other words, there should not be gaps in your snapshots.Note: It's also best practice to set the very firststart_timeas 0. Theto_snapshot_list()helper function will do this automatically, but if you configure snapshots by hand, be sure to standardize to start at 0.If the duration of all of your snapshots is uniform, you can use theTemporalDataobject
as a helper object to quickly make a series of snapshots using your list of adjacency matrices, like this:infect_rate = 0.5
your_temporal_data = network.TemporalData([matrix_1, matrix_2, matrix_3], interval=1, beta=infect_rate)
snapshots = your_temporal_data.to_snapshot_list()See section below on choosingbeta, but for this example, it can be any value between 0 and 1.Note:betashould be the same for all snapshots in the list.If your snapshots have custom durations and are not all equal to the same interval, you can instead
create your own list ofSnapshotobjects from your arrays, equipped with a consecutive start and end time for each,
(instead of using theTemporalDatahelper):snapshots = [network.Snapshot(start_time=0, end_time=1, beta=infect_rate, A=matrix_1),
             network.Snapshot(start_time=1, end_time=2, beta=infect_rate, A=matrix_2),
             network.Snapshot(start_time=2, end_time=3, beta=infect_rate, A=matrix_3)]Either way, once you have a list ofSnapshotobjects,
then create aTemporalNetworkobject to contain all of your ordered snapshots:your_temporal_network = network.TemporalNetwork(snapshots)Using the algorithmic compression from our paper [link], you can compress
the temporal network into a desired number of compressed snapshots (in this example, 2), by calling on an instance of
the staticCompressorclassyour_compressed_network_result = compression.Compressor.compress(your_temporal_network,
                                                          compress_to=2,
                                                          how='optimal')which will return the newTemporalNetworkobject, and also the total induced error from the snapshots that
were selected for compression. The elements can be accessed via a dictionary asyour_compressed_network = your_compressed_network_result["compressed_network"]
total_induced_error = your_compressed_network_result["error"]To compress your original network into an even division and aggregation of snapshots,
not using our algorithm, you can callcompressand changing thehowargument toeven:your_even_compressed_network_result = compression.Compressor.compress(your_temporal_network,
                                                          compress_to=2,
                                                          how='even')
even_compressed_network = your_even_compressed_network_result["compressed_network"]From the resulting compressedTemporalNetworkobjects, you can now access your snapshots as you
would with your original temporal network, by accessing thesnapshotsmember viayour_new_snapshots = your_compressed_network.snapshotsfrom which you can access each snapshot's new duration, adjacency matrix, start and end times.Usage using demo networkFor a more involved demo, make use of thecompressnets.demosmodule to access a more complex
temporal network without having to create one yourself. Follow the code below in your
own workspace to use a sample temporal network to compress it, and visualize a system of ODEs over
the compressed network vs. the original temporal solution.from compressnets import compression, network, demos, solvers

demo_network = demos.Sample.get_sample_temporal_network()
compressed_optimal = compression.Compressor.compress(demo_network, compress_to=4, how='optimal')["compressed_network"]
compressed_even = compression.Compressor.compress(demo_network, compress_to=4, how='even')["compressed_network"]Now you have the resulting compressed temporal networks for the optimal (algorithmic) method and from an even
aggregation method.To visualize the new time boundaries of each aggregated snapshot, and compare a full
Susceptible-Infected disease spread process against the fully temporal network, you can
utilize thecompressnets.solversmodule to solve a system of ODEs and plot the resulting figure:## Creating and solving a model with the original temporal network

N = demo_network.snapshots[0].N
beta = demo_network.snapshots[0].beta
model = solvers.TemporalSIModel({'beta': beta}, np.array([1/N for _ in range(N)]),
                                demo_network.snapshots[demo_network.length-1].end_time,
                                demo_network)
soln = model.solve_model()
smooth_soln = model.smooth_solution(soln)
plt.plot(smooth_soln[0], smooth_soln[1], color='k', label='Temporal solution')
plt.vlines(list(demo_network.get_time_network_map().keys()), ymin=0, ymax=N/3, ls='-',
          lw=0.5, alpha=1.0, color='k')


## Creating and solving a model with the algorithmically compressed temporal network

N = compressed_optimal.snapshots[0].N
beta = compressed_optimal.snapshots[0].beta
model = solvers.TemporalSIModel({'beta': beta}, np.array([1/N for _ in range(N)]),
                                compressed_optimal.snapshots[compressed_optimal.length-1].end_time,
                                compressed_optimal)
soln = model.solve_model()
smooth_soln = model.smooth_solution(soln)
plt.plot(smooth_soln[0], smooth_soln[1], color='b', label='Optimal compressed')
plt.vlines(list(compressed_optimal.get_time_network_map().keys()), ymin=N/3, ymax=2*N/3, ls='-',
          lw=0.5, alpha=1.0, color='b')


## Creating and solving a model with the evenly compressed temporal network

N = compressed_even.snapshots[0].N
beta = compressed_even.snapshots[0].beta
model = solvers.TemporalSIModel({'beta': beta}, np.array([1/N for _ in range(N)]),
                                compressed_even.snapshots[compressed_even.length-1].end_time,
                                compressed_even)
soln = model.solve_model()
smooth_soln = model.smooth_solution(soln)
plt.plot(smooth_soln[0], smooth_soln[1], color='r', label='Even compressed')
plt.vlines(list(compressed_even.get_time_network_map().keys()), ymin=2*N/3, ymax=N, ls='-',
          lw=0.5, alpha=1.0, color='r')

plt.ylabel('Number infected')
plt.xlabel('Time')
plt.legend()
plt.show()Output figure from the sample code above using the provided demo temporal network.
The original temporal network has 50 snapshots and is compressed down to 4 snapshots.
In blue, you see the resulting temporal boundaries of the 4 snapshots compressed using our
algorithm. In red, you see the resulting temporal boundaries of the 4 snapshots compressed
into even-size aggregate matrices. The time series represent an SI epidemic process over the
3 versions of the network.Choosing the infect ratebetaThe bestbetavalue to choose for your series of networks is one that,
given an SI process over the full sequence of temporal networks,
won't saturate (infect the entire network) too quickly, but that also provides
rich enough dynamics that can be observed.One way to test if a givenbetavalue is appropriate is to use thesolversmodule.
The same module that is shown in the demo to assess how your compression
performed is also just as useful for a pre-analysis of your system.For example, running just the top block of the demo above will give you a time series solution
on your full temporal network:N = demo_network.snapshots[0].N
beta = YOUR_CHOSEN_VALUE
model = solvers.TemporalSIModel({'beta': beta}, np.array([1/N for _ in range(N)]),
                                demo_network.snapshots[demo_network.length-1].end_time,
                                demo_network)
soln = model.solve_model()
smooth_soln = model.smooth_solution(soln)
plt.plot(smooth_soln[0], smooth_soln[1], color='k', label='Temporal solution')You can try out a range of differentbetavalues until you see a time series
solution that doesn't saturate too quickly and also doesn't die off.
The compression algorithm is robust to a range of values around your specified value,
so no need to worry about a precise value ofbeta, just one that's in the appropriate range
for the epidemic dynamics to be observed.CitationIf you use this package, please name your use of this package as well as the original
paper on the framework, asAllen, Andrea J. and Moore, Cristopher and Hébert-Dufresne, Laurent.
A network compression approach for quantifying the importance of temporal contact chronology.
Preprint athttps://arxiv.org/abs/2205.11566(2022).Code written and maintained by Andrea Allen.