vis_tools.SpatialBinary module

SpatialBinary.py

This file contains:

• SpatialBinary - a wrapper for SpatialReport DTK output files.

SpatialBinary is a Python wrapper for DTK SpatialReport_* files. It can both read and write them, and can combine them using combiner functions to make new SpatialReports.

Usage:

spatial_binary = SpatialBinary(path.combine(my_dir,
    "SpatialReport_Prevalence.bin"))
print spatial_binary

class vis_tools.SpatialBinary.SpatialBinary(file_path='', drop_zeros=False, excluded_node_ids=None, verbose=False)

Bases: object

Class to hold DTK spatial binary report data.

The class is constructed with the path to the report file in question. Thereafter the public data members described below may be used to directly access (or change) the data.

Additionally, since SpatialBinary implements __len__, __iter__, and __getitem__, the object can be treated like an array on timestep, e.g.:

timestep_rec = spatial_binary[timestep]     # Obtain one timestep

The resulting timestep_rec is a dictionary<node_id, channel_value>.

Public members:

drop_zeros (bool): True: drop zero values from in-memory representation.

source_file (str): A copy of the file_path that was used to construct the SpatialBinary object.

channel_name (str): The channel name, pulled from source_file.

node_count (int): The number of nodes in the SpatialBinary’s node table.

value_min (float): The minimum value for all nodes * timesteps.

value_max (float): The maximum value for all nodes * timesteps.

timesteps (array): Array of dictionaries containing the spatial report’s data.

value_range(for_json=False)

Returns an object with the value range of the data.

Returns:

An object with the min/max values of the data, with either Python or Javascript naming conventions.

Return type:

obj

Parameters:

• for_json (bool) – If true, emit an object using Javascript naming

• conventions –

• conventions. (otherwise use Python naming) –

write_binary(bin_file_path)

Writes the SpatialBinary to a given file path.

This function write out the spatial data in the object to a SpatialReport-format binary file. Typically this is used when the caller has modified the data in a SpatialBinary object or used combine() to create a new one. Note that if zeros were dropped, write_binary will throw an exception.

Returns:

None.

Parameters:

bin_file_path (str) – The file path to which to write.

Raises:

ValueError – if the SpatialBinary used drop_zeros on construction.

To do:

• Make it work even for sparse spatial binaries. The zero values are implied in by missing keys in the timestep records, so no actual data is missing.

clone()

Returns a copy of this SpatialBinary in a new SpatialBinary object.

Returns:

A new SpatialBinary object populated from self.

Return type:

obj

Parameters:

None. –

print()

Prints the entire contents of the spatial binary. Can be lengthy.

Returns:

None.

Parameters:

None. –

static combine(bin_file_path_1, bin_file_path_2, channel_name, combine_func)

Combine two SpatialBinary objects into a new SpatialBinary object.

This function takes two SpatialBinary objects (of the same exact dimensions in both timesteps and nodes) and combines them through a “combine function” to make an entirely new in-memory SpatialBinary. That resulting SpatialBinary would then typically be written out using write_binary().

There are four simple arithmetic static combine functions built into SpatialBinary, but the user may pass in any valid combine function that has a compatible signature. (See Usage below.) For operations that are not commutative such as division, let it be known that argument value1 in the combine function comes from bin_file_path1, and value2 comes from bin_file_path2.

Beware: temporarily has all three SpatialBinaries in memory.

Usage:

def rounded_multiply_combiner(value1, value2):
    return round(value1 * value2)
inf_vec_count = SpatialBinary.combine(
    "output/SpatialReport_Adult_Vectors",
    "output/SpatialReport_Infected_Vectors",
    "Infected Vector Count", rounded_multiply_combiner)
inf_vec_count.write_binary("SpatialReport_Infected_Vector_Count")

Returns:

A new SpatialBinary object combining sources 1 and 2

Return type:

obj

Parameters:

• bin_file_path_1 (str) – File path of first spatial binary file.

• bin_file_path_2 (str) – File path of second spatial binary file.

• channel_name (str) – Channel name to assign to the result binary.

• combine_func (function) –

  A function that combines the values from the two spatial binary inputs, one at a time. The signature of the combine_func is:

  combine_func(value1, value2)
      return value1 + value2      # for example
  

Raises:

• ValueError – if SpatialBinary ofbjects don’t have same dimensions or

• nodes –

static multiply_combiner(value1, value2)

Combiner function that multiplies channel values.

Returns:

new value.

Return type:

float

Parameters:

• value1 (float) – Value from input file 1.

• value2 (float) – Value from input file 2.

static add_combiner(value1, value2)

Combiner function that adds channel values.

Returns:

new value.

Return type:

float

Parameters:

• value1 (float) – Value from input file 1.

• value2 (float) – Value from input file 2.

static subtract_combiner(value1, value2)

Combiner function that subtracts channel values.

Returns:

new value.

Return type:

float

Parameters:

• value1 (float) – Value from input file 1.

• value2 (float) – Value from input file 2.

static divide_combiner(value1, value2)

Combiner function that divides channel values.

Returns:

new value.

Return type:

float

Parameters:

• value1 (float) – Value from input file 1.

• value2 (float) – Value from input file 2.