vis_tools package

vis_tools.CSVReport module

CVSReport.py

This class is a simple Python wrapper for csv report files.

Usage::
report = CSVReport(path.combine(my_dir, “ReportEventRecorder.csv”)) print report
class vis_tools.CSVReport.CSVReport(file_path='', verbose=False)

Bases: object

Class to hold DTK CSV report data.

The class is constructed with the path to the report file in question. Thereafter the public data members source_file and rows may be used to directly access the resultant Python representation of the file.

Additionally, since CSVReport implements __len__ and __iter__, the report object can be treated like a list, e.g.:

row = report[10]    # Obtain the 11th row
Public members:

The following data members are publicly exposed.

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

rows (array): Array of Python objects made from the input file lines.

header (array): Array of field names read from top of CSV file.

make_series(name, time_field, data_field)

Make a Highcharts-compatible series object from CSV rows.

Returns:
obj: Object for use as a Highcharts data series.
Args:

name (str): The name that is put into the output series structure.

time_field (str): The column name for the column representing time.

data_field (str): The column name for teh data (Y) value.

Raises:
Data access exceptions.
missing_columns(column_list)

Confirms that a given set of columns exists in a CSVReport.

This function can be used to verify the presence of a set of (presumably required) fields in a CSVReport. Typical usage is:

if (rpt.missing_columns(["Time", "Node_ID"]) is None)
    # All require columns present, so carry on
Returns:
List of columns from column_list that are not present, or None if all columns are present.
Args:
column_list (list): Columns to be tested for.
read_partial(file_path, row_count)

Read the first row_count rows off a CSV.

To do a partial read of a CSV report, create a CSVReport with the default constructor, then call read_partial to read as many rows as desired. E.g.:

report = CSVReport()
report.read_partial(my_csv_file_path, 100)
print report.rows[10]
Returns:
None.
Args:

file_path (str): File path of CSV report.

row_count: The number of rows to read.

Raises:
I/O, csv exceptions.

vis_tools.CZMLWriter module

CZMLWriter.py

This class simplifies the writing of Cesium CZML animation output files. It has methods for writing Vis-Tools-specific animations (migration and marker). Note that there are high-level methods on VisSet that implicitly create and use CZMLWriter so in many cases you will not need to directly instantiate/call this class yourself.

Usage:

writer = CZMLWriter()
writer.set_sim_duration(timestep_count)
writer.add_event_markers(my_event_recorder, my_demographics,
    "New_Infection", "Triangle", "red", "Top", 2)
writer.write(path.join(my_dir, "New_Infections.czml"))
class vis_tools.CZMLWriter.CZMLWriter(verbose=False)

Bases: object

Class for creating high-level visualizations in Cesium CZML format.

add_event_markers(event_recorder, demographics, event_name, marker, color, placement, duration_days, with_altitude=False)

Adds event marker animation to a CZML output.

This function looks for a particular event in an event recorder report and emits an animation that puts a marker somewhere around the node and leaves it there for a specified period after the event.

Returns:
Number of event markers in animation layer
Args:

event_recorder (CSVReport): Event recorder report object

demographics (Demographics): Demographics object with node data

event_name (str): Name of event to mark in the animation

marker (str): Name of a marker icon (“Triangle” or “Cross”)

color (str): Any HTML or SVG named color (e.g. “red”) or a CSS color string (e.g. “#ff0000”)

placement (str): Placement about the node point (“Top”, “Left”, “Bottom” or “Right”)

duration_days (int): Number of days for which the symbol should remain about the node after it fires.

with_altitude (bool): True to set the symbol elevations to match the node altitude, or default altitude otherwise.

add_migrations(migrations, demographics, with_altitude=False)

Adds migration animations to a CZML output.

This function, given migrations in a particular format and demographics, adds “comet” animations for migration events.

Returns:
Number of infected human migrations in animation layer
Args:

migrations (obj): An object that describes migrations (see below)

demographics (Demographics): A Demographics object describing nodes

with_altitude: True to respect the altitude in the node coordinates

migrations is a dictionary where the keys are <timestep> and the values are objects with keys <from_node_id>-<to_node_id> and the values are the number of migrations at that timestep from from_node_id to to_node_id. See MigrationHelpers.py for more details.

Todo:
  • Color customization (comet heads, comet tails)
  • Duration customization (comet tails)
add_nodes(demographics, population_as_size=True, with_altitude=False, processor=None, namer=None)

Add demographics node data to the CZMLWriter object. DEPRECATED.

This (DEPRECATED) method allows you to add node representations to a CZML output file, where the node point size is relative to the node’s InitialPopulation. Since the Vis-Tools client does this in a much more flexible way, this method is deprecated, but may be educational for those looking to extend the CZMLWriter class.

Returns:
None
Args:

demographics (Demographics) A Demographics object with node data.

population_as_size (bool): True to scale point size by InitialPopulation, fixed size otherwise

with_altitude: True to emit node coordinates including their altitude, false to just emit them with default altitude

processor: None or a function that processes the node and and the czml wrapper into a new CZML packet.

namer: None or a function that converts a node into a name string

add_simplified_vector_migrations(vector_migrations, demographics, migration_duration_timesteps, arrow_color, arrow_thickness_pixels)

Adds vector cohort migration animations to a CZML output.

This function, given vector migrations in a particular format and a demographics file, adds “comet” animations for migration events.

This function expects the following fields in vector_migrations:

  • Time (int): the timestep of the beginning of the migration event
  • FromNodeID (int): the node ID from which the migration emanates
  • ToNodeID (int): the node ID to which the migration completes
Returns:
Number of vector cohort migrations in animation layer
Args:

vector_migrations (CSVReport): The ReportVectorMigrations.csv report.

demographics (Demographics): The Demographics object describing the nodes.

migration_duration_timesteps (int): The duration of the migration animations in timesteps.

arrow_color (string): A CSS #rrggbb color for the migration arrow.

arrow_thickness_pixels (float): Thickness in pixels of comet tail.

add_vector_migrations(vector_migrations, demographics, migration_duration_timesteps, dot_color, dot_size_pixels, path_color, path_thickness_pixels, path_trail_time_factor)

Adds vector cohort migration animations to a CZML output.

This function, given vector migrations in a particular format and a demographics file, adds “comet” animations for migration events.

This function expects the following fields in vector_migrations:

  • Time (int): the timestep of the beginning of the migration event
  • FromNodeID (int): the node ID from which the migration emanates
  • ToNodeID (int): the node ID to which the migration completes
Returns:
Number of vector cohort migrations in animation layer
Args:

vector_migrations (CSVReport): The ReportVectorMigrations.csv report.

demographics (Demographics): The Demographics object describing the nodes.

migration_duration_timesteps (int): The duration of the migration animations in timesteps.

dot_color (string): A CSS #rrggbb color for the comet dot.

dot_size_pixels (int): Size in pixels of comet dot.

path_color (string): A CSS #rrggbb color for the comet tail.

path_thickness_pixels (float): Thickness in pixels of comet tail.

path_trail_time_factor (float): Length of trail as a multiple of the migration_duration. E.g. if this is 1.0, the trail length will be the full distance from source node to the destination node. If 0.5, the trail length will be half the distance between the nodes.

add_weighted_network(demographics, network, gradient_spec, opacity_func)

Adds a weighted network visualization layer to a CZML output.

This method emits a CZML animation that provides a visual representation of a weighted network between nodes.

Returns:
Number of network segments added
Args:

demographics (Demographics): Demographics object for nodes.

network (array): array of objects:

{
    from: <from-node-id>,
    to: <to-node-id>,
    weight: <float-weight>
}

gradient_spec (str): gradient spec for a gradient with which to color the network lines.

opacity_func (function): function(weight, norm_weight) that returns the desired opacity in range [0,1].

k_default_clock_multiplier = 14400
k_default_migration_duration_days = 2
k_default_migration_duration_seconds = 172800
k_default_migration_trail_duration = 86400
k_default_node_point_size = 8
set_sim_dates(sim_start_date, total_timestep_count)

Set the sim start date and total timesteps.

These are required because all CZML layers are time-synced to the Cesium clock. It is possible to use set_sim_duration in lieu of this function.

Returns:
None
Args:

sim_start_date (date): Start date for timestep 0

total_timestep_count (int): Number of timesteps in simulation data

set_sim_duration(total_timestep_count, timestep_bounds=None, sim_start_date=None, emit_clock=True, anim_step_secs=None)

Set the sim duration and time range.

This function allows you to set the start date and total timesteps, but also allows emitting the CZML over a subrange of timesteps less than the number of timesteps in total_timestep_count. This is effective for trimming migration animations that would otherwise be too big down to a workable subset.

Returns:
None
Args:

total_timestep_count (int): Total timesteps in sim

timestep_bounds: (list (start, end)): Timestep subrange for animation

sim_start_date (date): Start date for timestep 0

emit_clock (bool): Whether to emit a CZML Clock packet

anim_step_secs (int): Clock multiplier for Clock packet

write_czml(file_path)

Write the CZML animation file.

Returns:
None
Args:
file_path (str): The file path to which to write the CZML animation.
Raises:
I/O exceptions.

vis_tools.Color module

Color.py

This file contains a simple RGB color class that uses normalized channel values in the range of 0-1.

Classes:

  • Color - a simple RGB color object.

Usage:

color = Color(1.0, 0.5, 0.0)    # Equivalent to #ff7f00 in CSS
class vis_tools.Color.Color(r=0, g=0, b=0)

Bases: object

Class that encapsulates an RGB color.

Public members:

r (int): Red channel value in range(0, 255)

g int): Green channel value in range(0, 255)

b (int): Blue channel value in range(0, 255)

static from_html_hash(html_color)

Returns an RGB from an HTML/CSS #rrggbb-format string.

Returns:
obj: an RGB initialized with the colors from html_color
Args:
html_color: A string in the format “#rrggbb” where rr, gg, and bb are the channel values in hex.
static lerp(a, b, factor0to1)

Returns an interpolated color.

This function calculates a color that is between colors a and b using the factor0to1 argument to calculate the mix. If factor0to1 is zero, the resulting color is a. If factor0to1 is 1, the resulting color is b. For values of factor0to1 between 0 and 1, the resulting color is a linearly interpolated mix of colors a and b.

Returns:
obj: An RGB initialized with the interpolated color.
Args:

a (obj): An RGB representing the start color.

b (obj): An RGB representing the end color.

factor0to1 (float): A value in range(0,1) specifying the desired mix between colors a and b.

to_rgba_array()

Returns the color as an RGBA array.

Returns:
array: [r, g, b, 255] where r, g, and b are the channel values.
to_rgba_array_str()

Returns the color as a string representation of an RGBA array.

This is used by CZMLWriter and other classes that need to emit colors into Javascript formats.

Returns:
str: “[r, g, b, 255]” where r, g, and b are the channel values.

vis_tools.Config module

Config.py

This class is a simple Python wrapper for the config.json file used to configure the DTK.

Usage::
config = Config(path.join(my_dir, “config.json”)) print config
class vis_tools.Config.Config(file_path='', verbose=False)

Bases: object

Class to hold DTK config.json data.

The class is constructed with the path to the config.json file. Thereafter the public data members source_file, timestamp_count, and parameters may be used to directly access the resultant Python object. There are also accessor methods for the most commonly needed parameters.

Public members:

The following data members are publicly exposed.

source_file (str): A copy of the file_path used to construct the Config object.

timestep_count (int): The Simulation_Duration parameter.

parameters (obj): The entire config.json as a Python object.

get_demographics_filename_or_list()

Returns a string or list of demographics filenames, or None.

This function understands the presence of Demographics_Filename with a single path, Demographics_Filename with multiple paths delimited by ‘;’, and Demographics_Filenames as an array of paths.

Returns:
str|list: if a single demographics file is specified in the config, returns it as a string. If an array is specified, returns an array of filenames. Otherwise returns None.
Args:
None.
get_demographics_filenames()

Return the value of Parameters > Demographics_Filenames.

Returns:
list(str): List of demographics filenames.
Args:
None.
get_first_demographics_filename()

Returns the first (or only) demographics file from the config.

This function understands the presence of Demographics_Filename with a single path, Demographics_Filename with multiple paths delimited by ‘;’, and Demographics_Filenames as an array of paths.

Returns:
str: Demographics file name from Demographics_Filenames or
Demographics_Filename, or None.
Args:
None.
get_timestep_count()

Return the value of Parameters > Simulation_Duration.

Returns:
int: Timestep count.
Args:
None.

vis_tools.Demographics module

Demographics.py

This class is a Python wrapper for the DTK’s demographics JSON files.

Usage::
demographics = Demographics(path.join(my_dir, “Demographics.json”)) print demographics
class vis_tools.Demographics.Demographics(file_path_or_list=None, verbose=False)

Bases: object

Class to hold DTK demographics data.

The class is constructed with the path to the demographics JSON file. Thereafter the public data members described below may be used to directly access (and modify, if desired) the resultant Python object. There are also accessor methods for commonly needed or calculated values.

Additionally, since Demographics implements __len__, __iter__, __getitem__, and __contains__, the object can be be treated like a dictionary, e.g.:

node = demographics[my_node_id]    # Obtain a particular node
Public members:

source_file (str): The path to the demographics JSON file. If the object is initialized from a list of overlays, source_file is the path of the base demographics file.

latitude_min (float): Minimum latitude for all nodes

latitude_max (float): Maximum latitude for all nodes

longitude_min (float): Minimum longitude for all nodes

longitude_max (float): Maximum longitude for all nodes

latitude_delta_min (float): smallest non-zero difference between node latitude coordinates. Used to calculate the size of a bitmap that has sufficient resolution to discern between nodes in the vertical axis.

longitude_delta_min (float): smallest non-zero difference between node longitude coordinates. Used to calculate the size of a bitmap that has sufficient resolution to discern between nodes in the horizontal axis.

population_min (float): Minimum InitialPopulation for all nodes

population_max (float): Maximum InitialPopulation for all nodes

nodes_by_id (obj): dictionary keyed on nodeId containing node objects

adjusted_pop_max (float): population_max but with the highest value removed. (DEPRECATED)

Defaults (obj): The raw Defaults portion of the demographics file

MetaData (obj): The raw Metadata portion of the demographics file

NodeProperties (array): The raw NodeProperties portion of the demographics file

Nodes (array): The raw Nodes portion of the demographics file

bounding_box(for_json=True)

Returns a geospatial bounding box for the nodes.

Returns:
obj: bounding box in either Python or Javascript style.
Args:
for_json (bool): If true, emits Javascript naming conventions, or Python conventions otherwise.
calc_adjusted_pop_max()

Removes the largest Initial Population value. (DEPRECATED)

This function can be used to obtain the next-to-highest InitialPopulation value. This would be used for removing the “elsewhere” node in some simulations. A better way is to use the method VisSet.exclude_nodes_from_stats(), which allows multiple nodes and ensures the updated min/max are in the VisSet where they are needed.

Returns:
int: The adjusted maximum InitialPopulation.
Args:
None.
emit_nodes()

Returns an array of node objects suitable for use in the VisSet.

You can use this function to get a trimmed-down nodes data structure from the Demographics object. Normally the VisSet will do this encapsulation for you, but this method is present if needed.

Note that InitialPopulation, if present, is initial-capped. This is because users can choose to pull in extra data from NodeAttributes into the nodes that are cached in the VisSet, and use those for static visual mappings on the client side. Any fields outside of [nodeId|latitude|longitude|altitude] are exposed by the client as sources. This way the user can use the initial-capped fieldnames they’re used to.

Returns:
array: An array of objects representing the nodes.
Args:
None.
incorporate_altitudes(alt_csv)

Retroactively apply altitudes to the nodes.

This function updates the nodes’ altitude attribute using data from a CSV file. The file may have other fields, but it needs one column called “NodeID” and one column called “Altitude”.

Returns:
int: number of nodes updated.
Args:
alt_csv (str): The file path of the CSV file with altitudes.
Raises:
I/O and CSV exceptions.
k_default_node_altitude = 1
make_index(node_attribute_field)

Returns an index from node_attribute_field to node id(s).

This function creates an index on any field within NodeAttributes that maps that allows you to look up the nodes that have that node attribute. For example, if you nodes have a FacilityName field in NodeAttributes, you could do:

index = demo.make_index("FacilityName")

then later, to look up the node ids for a given FacilityName:

node_ids = index["3628"]
for id in node_ids
    print id
Returns:
dict<value, array<node_id>>: index
Args:
node_attribute_field (str): field name within NodeAttributes.
minimum_deltas(for_json=True)

Returns the minimum non-zero deltas for latitude and longitude.

Returns:
obj: minimum non-zero lat/long deltas in either Python or Javascript style.
Args:
for_json (bool): If true, emits Javascript naming conventions, or Python conventions otherwise.
population_range(for_json=True)

Returns the range of InitialPopulation for all nodes.

Returns:
obj: range of population in either Python or Javascript style.
Args:
for_json (bool): If true, emits Javascript naming conventions, or Python conventions otherwise.

vis_tools.Gradient module

Gradient.py

This file contains a class for doing Python-side color gradients. The Gradient class is a gradient with an arbitrary number of color stops. Since Gradient is derived from the Vis-Tools gradient.js, the same style text representations of gradients can be used.

Classes:

  • Gradient - a sampleable color gradient.

Usage:

gradient = Gradient("green@0,orange@0.33,yellow@.66,red@1")
color = gradient.sample(0.5)
class vis_tools.Gradient.Gradient(spec='')

Bases: object

Class for sampleable color gradients.

This class lets you create a color gradient with an arbitrary number of color stops on a normalized range from 0 to 1. You then sample the gradient with a normalized value from 0 to 1 to get a color out of the gradient.

This class is based on the Vis-Tools gradient.js. However it does not support the “,r” or “,q<steps>” suffixes supported by gradient.js.

The spec format is:
<color>@0,[<color>@<loc>,…]<color>@1
Where:
  • color - Color objects representing the stop colors
  • loc - Ordered values in range(0, 1) representing the normalized locations of the gradient stops.
Raises:
ValueError: if spec is invalid.
sample(loc0to1)

Sample the gradient to get a color at a particular location.

Returns:
obj: A Color object for the color at the sample point.
Args:
loc0to1 (float): A normalized value in the range(0, 1) at which point to sample the gradient color.

vis_tools.MigrationHelpers module

MigrationHelpers.py

This class contains static methods that are useful in the composition of infected migration animations. Namely collate_infected_human_migrations(), which trawls through a ReportHumanMigrationTracking report and combines that with a ReportEventRecorder report to find and create a data structure of the migrations of only infected individuals.

While there is currently only one method in this class, as other forms of migration culling are developed more methods will be added here as needed.

class vis_tools.MigrationHelpers.MigrationHelpers

Bases: object

Helper functions for processing migrations.

static collate_infected_human_migrations(rpt_human_migs, rpt_evt_rec)

Glean infected human migrations from two source files.

This function combines a ReportHumanMigrationTracking.csv and a ReportEventRecorder.csv to generate a set of infected human migrations.

Returns:

obj:

{
  infected_migrations: { ... },
  aggregate_migrations_max: n
}

where:

  • infected_migrations in the result is an dictionary where the keys are <timestep> and the values are objects with keys <from_node_id>-<to_node_id> and the values are the number of migrations at that timestep from from_node_id to to_node_id.
  • aggregate_migrations_max in the result is the most simultaneous migrations between any two nodes. This could be used for visualization, for example using a thicker line for more migrations.
Args:

rpt_human_migs (obj): CSVReport of a ReportHumanMigrationTracking.

rpt_evt_rec (obj): CSVReport of a ReportEventRecorder.

vis_tools.NamedColors module

NamedColors.py

This file contains a class that provides all the SVG color names as Color objects.

Classes:

  • NamedColors - the SVG named colors as Color objects.

Usage:

color = NamedColors.coral
class vis_tools.NamedColors.NamedColors

Bases: object

Named SVG colors as Color objects.

This class is a reference data class that contains Color objects for all the SVG named colors. These can be used in Gradient stops for better readability.

aliceblue = <vis_tools.Color.Color object>
antiquewhite = <vis_tools.Color.Color object>
aqua = <vis_tools.Color.Color object>
aquamarine = <vis_tools.Color.Color object>
azure = <vis_tools.Color.Color object>
beige = <vis_tools.Color.Color object>
bisque = <vis_tools.Color.Color object>
black = <vis_tools.Color.Color object>
blanchedalmond = <vis_tools.Color.Color object>
blue = <vis_tools.Color.Color object>
blueviolet = <vis_tools.Color.Color object>
brown = <vis_tools.Color.Color object>
burlywood = <vis_tools.Color.Color object>
cadetblue = <vis_tools.Color.Color object>
chartreuse = <vis_tools.Color.Color object>
chocolate = <vis_tools.Color.Color object>
coral = <vis_tools.Color.Color object>
cornflowerblue = <vis_tools.Color.Color object>
cornsilk = <vis_tools.Color.Color object>
crimson = <vis_tools.Color.Color object>
cyan = <vis_tools.Color.Color object>
darkblue = <vis_tools.Color.Color object>
darkcyan = <vis_tools.Color.Color object>
darkgoldenrod = <vis_tools.Color.Color object>
darkgray = <vis_tools.Color.Color object>
darkgreen = <vis_tools.Color.Color object>
darkgrey = <vis_tools.Color.Color object>
darkkhaki = <vis_tools.Color.Color object>
darkmagenta = <vis_tools.Color.Color object>
darkolivegreen = <vis_tools.Color.Color object>
darkorange = <vis_tools.Color.Color object>
darkorchid = <vis_tools.Color.Color object>
darkred = <vis_tools.Color.Color object>
darksalmon = <vis_tools.Color.Color object>
darkseagreen = <vis_tools.Color.Color object>
darkslateblue = <vis_tools.Color.Color object>
darkslategray = <vis_tools.Color.Color object>
darkslategrey = <vis_tools.Color.Color object>
darkturquoise = <vis_tools.Color.Color object>
darkviolet = <vis_tools.Color.Color object>
deeppink = <vis_tools.Color.Color object>
deepskyblue = <vis_tools.Color.Color object>
dimgray = <vis_tools.Color.Color object>
dimgrey = <vis_tools.Color.Color object>
dodgerblue = <vis_tools.Color.Color object>
firebrick = <vis_tools.Color.Color object>
floralwhite = <vis_tools.Color.Color object>
forestgreen = <vis_tools.Color.Color object>
fuchsia = <vis_tools.Color.Color object>
gainsboro = <vis_tools.Color.Color object>
ghostwhite = <vis_tools.Color.Color object>
gold = <vis_tools.Color.Color object>
goldenrod = <vis_tools.Color.Color object>
gray = <vis_tools.Color.Color object>
green = <vis_tools.Color.Color object>
greenyellow = <vis_tools.Color.Color object>
grey = <vis_tools.Color.Color object>
honeydew = <vis_tools.Color.Color object>
hotpink = <vis_tools.Color.Color object>
indianred = <vis_tools.Color.Color object>
indigo = <vis_tools.Color.Color object>
ivory = <vis_tools.Color.Color object>
khaki = <vis_tools.Color.Color object>
lavender = <vis_tools.Color.Color object>
lavenderblush = <vis_tools.Color.Color object>
lawngreen = <vis_tools.Color.Color object>
lemonchiffon = <vis_tools.Color.Color object>
lightblue = <vis_tools.Color.Color object>
lightcoral = <vis_tools.Color.Color object>
lightcyan = <vis_tools.Color.Color object>
lightgoldenrodyellow = <vis_tools.Color.Color object>
lightgray = <vis_tools.Color.Color object>
lightgreen = <vis_tools.Color.Color object>
lightgrey = <vis_tools.Color.Color object>
lightpink = <vis_tools.Color.Color object>
lightsalmon = <vis_tools.Color.Color object>
lightseagreen = <vis_tools.Color.Color object>
lightskyblue = <vis_tools.Color.Color object>
lightslategray = <vis_tools.Color.Color object>
lightslategrey = <vis_tools.Color.Color object>
lightsteelblue = <vis_tools.Color.Color object>
lightyellow = <vis_tools.Color.Color object>
lime = <vis_tools.Color.Color object>
limegreen = <vis_tools.Color.Color object>
linen = <vis_tools.Color.Color object>
magenta = <vis_tools.Color.Color object>
maroon = <vis_tools.Color.Color object>
mediumaquamarine = <vis_tools.Color.Color object>
mediumblue = <vis_tools.Color.Color object>
mediumorchid = <vis_tools.Color.Color object>
mediumpurple = <vis_tools.Color.Color object>
mediumseagreen = <vis_tools.Color.Color object>
mediumslateblue = <vis_tools.Color.Color object>
mediumspringgreen = <vis_tools.Color.Color object>
mediumturquoise = <vis_tools.Color.Color object>
mediumvioletred = <vis_tools.Color.Color object>
midnightblue = <vis_tools.Color.Color object>
mintcream = <vis_tools.Color.Color object>
mistyrose = <vis_tools.Color.Color object>
moccasin = <vis_tools.Color.Color object>
navajowhite = <vis_tools.Color.Color object>
navy = <vis_tools.Color.Color object>
oldlace = <vis_tools.Color.Color object>
olive = <vis_tools.Color.Color object>
olivedrab = <vis_tools.Color.Color object>
orange = <vis_tools.Color.Color object>
orangered = <vis_tools.Color.Color object>
orchid = <vis_tools.Color.Color object>
palegoldenrod = <vis_tools.Color.Color object>
palegreen = <vis_tools.Color.Color object>
paleturquoise = <vis_tools.Color.Color object>
palevioletred = <vis_tools.Color.Color object>
papayawhip = <vis_tools.Color.Color object>
peachpuff = <vis_tools.Color.Color object>
peru = <vis_tools.Color.Color object>
pink = <vis_tools.Color.Color object>
plum = <vis_tools.Color.Color object>
powderblue = <vis_tools.Color.Color object>
purple = <vis_tools.Color.Color object>
red = <vis_tools.Color.Color object>
rosybrown = <vis_tools.Color.Color object>
royalblue = <vis_tools.Color.Color object>
saddlebrown = <vis_tools.Color.Color object>
salmon = <vis_tools.Color.Color object>
sandybrown = <vis_tools.Color.Color object>
seagreen = <vis_tools.Color.Color object>
seashell = <vis_tools.Color.Color object>
sienna = <vis_tools.Color.Color object>
silver = <vis_tools.Color.Color object>
skyblue = <vis_tools.Color.Color object>
slateblue = <vis_tools.Color.Color object>
slategray = <vis_tools.Color.Color object>
slategrey = <vis_tools.Color.Color object>
snow = <vis_tools.Color.Color object>
springgreen = <vis_tools.Color.Color object>
steelblue = <vis_tools.Color.Color object>
tan = <vis_tools.Color.Color object>
teal = <vis_tools.Color.Color object>
thistle = <vis_tools.Color.Color object>
tomato = <vis_tools.Color.Color object>
turquoise = <vis_tools.Color.Color object>
violet = <vis_tools.Color.Color object>
wheat = <vis_tools.Color.Color object>
white = <vis_tools.Color.Color object>
whitesmoke = <vis_tools.Color.Color object>
yellow = <vis_tools.Color.Color object>
yellowgreen = <vis_tools.Color.Color object>

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.

static add_combiner(value1, value2)

Combiner function that adds channel values.

Returns:
float: new value.
Args:

value1 (float): Value from input file 1.

value2 (float): Value from input file 2.

clone()

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

Returns:
obj: A new SpatialBinary object populated from self.
Args:
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:
obj: A new SpatialBinary object combining sources 1 and 2
Args:

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 divide_combiner(value1, value2)

Combiner function that divides channel values.

Returns:
float: new value.
Args:

value1 (float): Value from input file 1.

value2 (float): Value from input file 2.

static multiply_combiner(value1, value2)

Combiner function that multiplies channel values.

Returns:
float: new value.
Args:

value1 (float): Value from input file 1.

value2 (float): Value from input file 2.

print()

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

Returns:
None.
Args:
None.
static subtract_combiner(value1, value2)

Combiner function that subtracts channel values.

Returns:
float: new value.
Args:

value1 (float): Value from input file 1.

value2 (float): Value from input file 2.

value_range(for_json=False)

Returns an object with the value range of the data.

Returns:
obj: An object with the min/max values of the data, with either Python or Javascript naming conventions.
Args:
for_json (bool): If true, emit an object using Javascript naming conventions, otherwise use Python naming conventions.
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.
Args:
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.

vis_tools.SpatialBinaryHeader module

SpatialBinaryHeader.py

This file contains:

  • SpatialBinaryHeader - a class for extracting just the header from SpatialReport files.

SpatialBinaryHeader is a class that allows access to the dimensions of a spatial report without actually reading the entire file.

class vis_tools.SpatialBinaryHeader.SpatialBinaryHeader(file_path='', verbose=False)

Bases: object

Class to read header off a spatial binary without reading the contents.

Usage:

bin_header = SpatialBinaryHeader("output/SpatialReport_Prevalence")
print bin_header

vis_tools.SpatialReports module

SpatialReports.py

This class is a collection class that keeps track of all the SpatialReport_* files in a given directory. It is used by VisSet.

Usage:

reports = SpatialReports("output/")
print reports
class vis_tools.SpatialReports.SpatialReports(spatial_dir='', verbose=False)

Bases: object

Collection class for a set of spatial reports.

The class is constructed with the directory in which SpatialReport_* files reside. Thereafter the public data members described below, and the various accessor functions, can be used to get access to the list.

Additionally, since SpatialReports implements __len__, __iter__, and

__getitem__, the SpatialReports object can be treated as a list:, e.g.:

spatial_reports = SpatialReports("/output")
path = spatial_reports[0]

Public members:

source_dir (str): The source directory used to construct the SpatialReports object.

paths (array): Array of strings with paths to the SpatialReport_* files.

properties (dict): Dictionary<friendlyName, dict<key,value>> of additional properties to associate with each SpatialBinary file path. Currently these are unused, but will be used in an upcoming version.

add(report_path)

Manually add a spatial binary to the list.

This method can be used to manually add a spatial binary to the list even if it is not in the source_dir where spatial_binaries normally live. This is useful for adding a programmatically-generated spatial binary to the list. Such generated spatial binaries are generally located in the preprocessing script’s products directory.

Example:

reports = SpatialReports("output/")
reports.add(path.join(k_products_dir,
    'SpatialReport_Infectious_Vector_Count'))
Returns:
None.
Args:
report_path (str): The path to the spatial binary. Note that this path need not be within source_dir.
emit_object()

Emits an object used by VisSet to represent spatial binary channels.

Result:
object: A Dictionary<friendly_name, file_path> for the spatial binaries found in the target directory.
Args:
None.
emit_object_json()

Emits the JSON for the object from emit_object.

Result:
str: JSON representation of the emit_object() result.
Args:
None.
get(index)

Returns detailed information on spatial binary by index.

Returns:
obj: An object containing the name, friendly name, and path (url) to the spatial binary at the provided index.
Args:
index (int): Index, 0-based, into path list.
k_spatial_filename_prefix = 'SpatialReport_'
remove(friendly_name)

Removes a spatial binary from the list by friendly name.

Returns:
None.
Args:
friendly_name (str): The friendly name of the spatial binary path to remove. E.g., for SpatialReport_Adult_Vectors, the friendly name is “Adult Vectors”.

vis_tools.Survey module

Survey.py

Survey is a Python program that surveys a sim folder and generates a default Vis-Tools preprocessing program for that sim. Run the output .py file and it will generate a working (if rather plain) visset.json for the sim as a starting point for customizations.

Note that both Survey and its generated preprocessing script is meant to be run from the simulation directory.

Typical Usage:

cd <my_sim_directory>
survey -t [Points|Shapes]

Where:

This usage defaults the simulation directory (-i) to . (the current directory). It defaults the products directory (-p) to ./Vis-Tools/<md5_of_script>/

Points|Shapes (str): Optional. The type of nodes visualization desired. Defaults to Points if not specified.

The resulting preprocessing script will be written to <my_sim_directory>/Vis-Tools/<md5_of_script>/preprocess_sim.py

To run the preprocessing script you’d do cd <my_sim_directory> # if not already there ./Vis-Tools/<md5_of_script>/preprocess_sim.py

class vis_tools.Survey.PrepMaker

Bases: object

Class to emit a preprocessor script given a Surveyor object.

This class generates a default text python preprocessing script that includes sections various sections based on the surveyed contents of a simulation directory.

static emit(survey, nodes_type, out_file_path)

Emits a default text python preprocessing script.

This method generates a default text python preprocessing script that includes sections various sections based on the surveyed contents of a simulation directory.

Returns:
None.
Args:

survey (obj): A Surveyor object for sim directory.

nodes_type (str): “Points” or “Shapes” - nodes type to emit.

out_file_path (str): Output python script file path.

Raises:
I/O exceptions.
class vis_tools.Survey.Surveyor(dir_path='', specific_demo_path=None, sim_id=None)

Bases: object

Class to survey a sim directory for inputs and outputs.

This class looks at a given directory that includes simulation inputs and outputs and collects file paths and in some cases reads the files there to determine key parameters such as number of timesteps and demographics.

Public members:

sim_dir (str): dir_path if len(dir_path) > 0 else None

sim_id (str): simulation id if given in constructor else None

out_dir (str): simulation output directory if found or None

assets_dir (str): Assets directory if found or None

asset_map_path (str): Path to VtAssetMap.json file if found or None

config_path (str): Config path if found or None

config (obj): Config object read from config_path if found or None

demographics_path_or_list (str|list): If a string, the single demographics file path. If a list, the array of demographics files referenced in the config.json.

demographics (obj): Demographics object read from demographics_path_or list if found or None. If there are overlays, they are already applied here.

inset_path (str): InsetChart.json path if found or None

malaria_filtered_path (str): ReportMalariaFiltered.json path if found or None

human_mig_tracking_path (str): ReportHumanMigrationTracking.csv path if found or None

event_recorder_path (str): ReportEventRecorder.csv path if found or None

spatial_reports (obj): SpatialReports object if out_dir is found or None

timestep_count (int): Timestep count read from config.json if found or None

get_event_names()

Gets a sample set of event names from the ReportEventRecorder.csv.

This method reads the first 100 lines off the ReportEventRecorder.csv and returns a list of the unique event names therein. This is not a comprehensive list of all the event types in the file.

Returns:
set: a set of event names, or None.
Args:
None.
Raises:
I/O and csv exceptions.
get_inset_channels()

Returns a list of channel names for inset/malaria filtered files.

This method looks opens the InsetChart.json (if present) or the ReportMalariaFiltered.json (if present) and returns a list of the channel names that are available in the file.

Returns:
list: Channel names read from one of the inset-format files, sorted into alphabetical order, or None.
Args:
None.
Raises:
I/O and json exceptions.
get_node_attributes_simple_fields()

Gets the set of non-object field names from NodeAttributes,

This method looks at the first node in the demographics file and collects all the field names that are simple key-value pairs. So it gets fields like InitialPopulation and BirthRate, but doesn’t get InitialVectorsPerSpecies, since its value is an object. Only looks at the first node, so it is not technically comprehensive. It also removes the “known” fields of Latitude, Longitude, and Altitude.

Returns:
set: a set of simple field names from NodeAttributes or None.
Args:
None.
summary()

Print a text summary of the Surveyor object.

This method prints a summary of the Surveyor object that includes the source directory, number of timesteps (if found), and number of nodes (if found).

Returns:
None. Prints to stdout.
Args:
None.
survey(dir_path)

Survey the given simulation directory for input and output files.

If a Surveyor object is passed a dir_path at construction, this method is called automatically. If you construct a Surveyor with no dir_path, you can use this method to later associate a dir_path with the Surveyor and cause that directory to be surveyed.

Returns:
None.
Args:
dir_path (str): Directory path to survey.
Raises:
I/O, csv, JSON, and custom exceptions.
vis_tools.Survey.main()

Main program

Overview:
  • Parse arguments
  • Fixup sim_dir if needed
  • Make a Surveyor to survey the sim directory
  • Ensure we got node information
  • Use PrepMaker to emit the preprocessing Python program.
vis_tools.Survey.update_visset(visset_path, asset_map_path)

Updates a visset with COMPS Asset Manager URLs from an asset map.

Returns:
None.
Args:
visset_path (str): Path to visset.json file asset_map_path (str): Path to VtAssetMap.json file

vis_tools.VisSet module

VisSet.py

This class generates the visset.json file that is the input for the Vis-Tools HTML client component. It reads defaults from a file called “defaultvisset.json” and extends itself with that. The caller fills in some vital information and then can overrides defaults the object with various method calls, then finally emits the visset.json file.

Note:

This file will eternally appear to have PEP errors in it because it makes reference to members that are not initially created in the constructor. Those members are acquired when then defaultvisset.json is read in and used to extend self. So these PEP errors are not actually errors.

Minimal usage:

vis_set = VisSet("MySim")
vis_set.set_target_client("Geospatial")
vis_set.set_node_vis_type("Points")
vis_set.set_products_directory("my_sim/output/")
vis_set.set_demographics("my_sim/demographics.json")
vis_set.add_spatial_reports(SpatialReports("my_sim/output/"))
vis_set.validate()
vis_set.write()
class vis_tools.VisSet.VisSet(name='Untitled', verbose=True)

Bases: object

Class that generates visset.json files.

This class provides a friendly way to generate a customized visset.json for Vis-Tools various HTML clients.

Rather than incorporating its defaults directly in code, it instead reads its defaults from defaultvisset.json. This important, because that same file is used by the HTML clients, so that the defaults for both remain in sync.

VisSet extends itself from defaultvisset.json, which is to say, all of the fields from defaultvisset.json become part of the VisSet Python object itself.

There are methods to allow easy access to some aspects of the VisSet, such as adding bindings, showing/hiding sections, and adding various types of visual layers. But the visset data structure is a public part of this object and it is allowable for a preprocessing script to directly poke into it whatever customizations are required. E.g.:

vis_set.options["defaultBaseLayer"] = "ESRI National Geographic"
vis_set.options["insetCharts"]["defaultChannelName"] = "Prevalence"
Public members:

name (str): The name (given in the constructor).

options (obj): The options section based on the targetClient

all keys found in defaultvisset.json

add_binding(vis_section, sink_name, source_name, func)

Add a binding between a data source and a visualization sink.

This method lets you add a binding between a visualization sink (e.g. point node color) and a data source (e.g. a spatial report) through a binding function (e.g. “scale(3, 20)”). Such bindings will be preset in the client page when it is first presented from the visset.

Note:
The available sinks vary depending on target client, and within a target client, on other factors. For example, there is one set of sinks for “Points” node representation, and a different set of sinks for “Shapes” node representation. You can see the list of sinks by inspecting the defaultvisset.json file.
Note:
The correctness of the functions provided in the func argument is not validated here. If the caller makes an error in the syntax of the function string, the errant string will still end up in the output visset.json. When the client loads the visset, the binding will throw an exception and the client will show an error message.
Returns:
bool: True if the binding was set, or False if the sink could not be found.
Args:

vis_section (str): The visualization section of the visset.json file. For the Geospatial client, valid values for vis_section are “nodeVis” or “heatmapVis”. Other clients will have other visualization sections. See defaultvisset.json.

sink_name (str): The name of the sink to which to bind. E.g. “shapeExtrusion”.

source_name (str): The name of the data source to which to bind. E.g. “SpatialReport_Prevalence” or “BirthRate”

func (str): The function to use on the binding. The details of function syntax are documented elsewhere, but in general this may be “none()”, some built-in function e.g. “scale(3, 20)”, or a custom Javascript function body, e.g.:

"{ return 1.0 - binding.value; }"
add_infected_human_migrations(human_migration_file_path)

Adds an infected human migrations layer to the output visset.

Note:
Call set_products_directory, set_demographics, set_event_recorder, and (add_spatial_channels or set_config) before calling this method.
For:
Geospatial visualization.
Returns:
None. Creates a CZML file in the VisSet’s products directory.
Args:
human_migration_file_path (str): The file path to the simulation’s ReportHumanMigrationTracking.csv file.
To do:
  • Add arg for comet head start color
  • Add arg for comet head end color
  • Add arg for comet tail start color
  • Add arg for comet tail end color
  • Add arg for tail duration in timesteps
add_marker_layer(event_name, marker=None, color=None, placement=None, duration=None, show=True)

Adds a marker animation layer to the output visset.

This method generates a CZML animation layer that provides visual indication of event recorder events.

Note:
Call set_products_directory, set_demographics, set_event_recorder, and (add_spatial_channels or set_config) before calling this method.
For:
Geospatial visualization.
Returns:
None. Creates a CZML file in the VisSet’s products directory.
Args:

event_name (str): The name of the event for which a marker layer is desired. It must exactly match the event name in the event recorder. E.g. “Received_Treatment”.

marker (str): The name of the marker image to use. “Triangle” or “Cross” are allowable (see constants at top of class).

color (str): An HTML/CSS or SVG named color for the marker. E.g. “red” or “#ccff00”

placement (str): The location, with respect to the node lat/log center, for the marker. “Top”, “Left”, “Bottom”, or “Right” are allowable (see constants at top of class).

duration (int): The duration, in timesteps for which the marker will remain visible after the event occurs. E.g. 2 will cause the marker to appear above the node on the timestep of the event, and remain there for two timesteps before disappearing.

show (bool): Whether this layer will be visible by default when the Geospatial client loads this visset. If show is False, the layer CZML is still generated and loaded by the client, but the layer will have its checkbox unchecked (and therefore not be visible) in the client when the page is first loaded.

add_node_field(field_name)

Allows the caller to pull in additional fields from NodeAttributes.

The output visset.json contains a summarized version of the nodes that are read from the demographics file. By default that summary includes latitude, longitude, and altitude if present. This method allows the caller to pull in any additional desired fields from NodeAttributes into the node summaries in the output visset.json. E.g.:

vis_set.add_node_field("BirthRate")
Note:
Automatically calls update_nodes(). Caller does not need to do that.
Returns:
None.
Args:
field_name (str): The NodeAttributes field name to pull in.
add_simplified_vector_migrations(vector_migration_path, migration_duration_timesteps=2, arrow_color='#ffffff', arrow_thickness_pixels=2)

Adds a simplified vector cohort migration layer to the output visset.

Note:
Call set_products_directory, set_demographics, and either set_config or add_spatial_reports before calling this method.
For:
Geospatial visualization.
Returns:
None. Creates a CZML file in the VisSet’s products directory.
Args:

vector_migration_path (str): The path to the ReportVectorMigration.csv file.

migration_duration_timesteps (int): Number of timesteps that the migration animation spans.

arrow_color (string): CSS #rrggbb color for migration arrow.

arrow_thickness_pixels (float): Thickness in pixels of arrow.

add_spatial_reports(spatial_reports)

Adds all the spatial reports in the given SpatialReports object.

This method adds as sources all the spatial report files referenced in the given SpatialReports object. Note that the current Geospatial client HTML loads all the spatial binaries it knows about into memory, so it may make sense to edit down the set of reports that are included. That can be done (subsequent to calling this method) using exclude_spatial_channels().

Note:
This method also, as a side effect, determines the number of timesteps in the simulation by inspecting the first spatial binary. As a result, if spatial binaries are provided, a config.json need not be added to the VisSet object.
Returns:
None.
Args:
spatial_reports (obj): the SpatialReports object to add.
add_vector_migrations(vector_migration_path, migration_duration_timesteps=2, dot_color='#ba7fb7', dot_size_pixels=10, path_color='#ffffff', path_thickness_pixels=2.5, path_trail_time_factor=0.75)

Adds a vector cohort migration layer to the output visset.

Note:
Call set_products_directory, set_demographics, and either set_config or add_spatial_reports before calling this method.
For:
Geospatial visualization.
Returns:
None. Creates a CZML file in the VisSet’s products directory.
Args:

vector_migration_path (str): The path to the ReportVectorMigration.csv file.

migration_duration_timesteps (int): Number of timesteps that the migration animation spans.

dot_color (string): CSS #rrggbb color for migration comet dot.

dot_size_pixels (int): Size in pixels of comet dot.

path_color (string): CSS #rrggbb color for migration comet tail.

path_thickness_pixels (float): Thickness in pixels of comet tail.

path_trail_time_factor (float): Length of trail as a multiple of the migration_duration. E.g. if this is 1.0, the trail length will be the full distance from source node to the destination node. If 0.5, the trail length will be half the distance between the nodes.

add_weighted_network_layer(network, gradient_spec, layer_name='Network', layer_file_name='Network', opacity_func=None)

Adds a weighted network visualization layer to the output visset.

This method generates a CZML layer that provides a visual representation of a weighted network between nodes.

Note:
Call set_products_directory and set_demographics before calling this method.
For:
Geospatial visualization.
Returns:
None. Creates a CZML file in the VisSet’s products directory.
Args:

network (array): array of objects:

{
    from: <from-node-id>,
    to: <to-node-id>,
    weight: <float-weight>
}

gradient_spec (str): gradient spec for a gradient with which to color the network lines.

layer_name (str): Layer name (to be displayed in the client UI).l

layer_file_name (str): The layer base name for the output file. For example, “Network” results in an output file called “Network.czml”.

opacity_func (function): function(weight, norm_weight) that returns the desired opacity in range [0,1].

exclude_node_from_stats(node_id)

Exclude a node from node min/max statistics.

This method is exactly exclude_nodes_from_stats but for a single node id. See that method for details.

Returns:
None.
Args:
node_id (int): Node id to exclude from stats.
exclude_nodes_from_stats(node_id_array)

Excludes a set of nodes from node min/max statistics.

This method lets the caller specify a list of node ids that should be excluded from the min/max calculations data channels. This includes both static sources (e.g. NodeAttributes.InitialPopulation) and spatial reports (e.g. SpatialReport_Population). This is typically used to drop an outlier from the data set to avoid visually skewing the output visualization. For example, one might exclude the “elsewhere” node, which typically has extraordinary population, prevalence, etc. in a simulation that incorporates external migration.

Note:
The node itself is not eliminated - it will still be visually represented, but it will have a value that may lie outside the min/ max range calculated for a given source. The client will clamp the value at visualization time.
Note:
This method calls update_nodes…the caller need not do that.
Returns:
None.
Args:

node_id_array (list): a list or array of node id’s to be excluded. If only a single node is to be excluded, enclose it in parens or [] so that it is iterable, e.g.:

exclude_nodes_from_stats([10001])

or just call exclude_node_from_stats()

exclude_spatial_channels(spatial_channel_names)

Exclude named channels from the list of binding sources.

Allows caller to exclude a set of spatial channels from showing up as sources for visualization bindings. This would primarily be done to reduce the memory pressure (or load time) of the client page, since all the source spatial binaries have to be loaded into memory on the client side. All this really does is set show=False in the link, which excludes the source on the client side.

Note:
Call add_spatial_reports() before calling this method.
Returns:
None.
Args:

spatial_channel_names (list): a list or array of spatial channel names. If only one channel is to be excluded, enclose it in parens or [] so that it is iterable. E.g.:

exclude_spatial_channels(["SpatialReport_Adult_Vectors"])
get_config()

Getter for the config object.

Returns:
obj: Currently set Config object or None.
Args:
None.
get_demographics()

Getter for the demographics object.

Returns:
obj: Currently set Demographics object or None.
Args:
None.
get_event_recorder()

Getter for the event recorder object.

Returns:
obj: Currently set CSVReport object for event recorder, or None.
Args:
None.
get_output_directory()

Getter for the output directory, where visset.json will be written. THIS METHOD IS DEPRECATED. Use get_products_dir instead.

Returns:
str: Currently set output directory or None.
Args:
None.
get_products_directory()

Getter for the products directory, where the visset.json and other artifact files are written.

This function replaces get_output_directory, which had a name that could lead to confusion with the simulation’s output/ directory.

Returns:
str: Currently set products directory or None.
Args:
None.
hide_layer(vis_section)

Sets a layer to be hidden by default in the output visset.json.

This method lets the caller set that the particular visualization section is hidden by default when the visset is loaded by the client. Note that all the data and bindings for that visualization section are still created and emitted to the visset…only their default visibility is affected.

Returns:
None.
Args:
vis_section (str): The visualization section of the visset.json file. For the Geospatial client, valid values for vis_section are “nodeVis” or “heatmapVis”. Other clients will have other visualization sections. See defaultvisset.json.
include_spatial_channels(spatial_channel_names)

Include (only) named channels in the list of binding sources.

Allows caller to include a subset of the available spatial channels as the list of possible sources for visualization bindings. This would primarily be done to reduce the memory pressure (or load time) of the client page, since all the source spatial binaries have to be loaded into memory on the client side. All this really does is set the specified channels to show=True and all the rest to show=False.

Note:
Call add_spatial_reports() before calling this method.
Returns:
None.
Args:

spatial_channel_names (list): a list or array of spatial channel names. If only one channel is to be excluded, enclose it in parens or [] so that it is iterable e. E.g.:

include_spatial_channels(["SpatialReport_Adult_Vectors"])
k_default_marker_duration_days = 2
k_default_visset = 'defaultvisset.json'
k_errno_permission_denied = 13
k_geospatial = 'Geospatial'
k_infected_migrations_file_name = 'InfectedMigrations.czml'
k_marker_placement_bottom = 'Bottom'
k_marker_placement_left = 'Left'
k_marker_placement_right = 'Right'
k_marker_placement_top = 'Top'
k_marker_shape_cross = 'Cross'
k_marker_shape_triangle = 'Triangle'
k_network_layer_file_name = 'Network.czml'
k_node_shape_square = 'Square'
k_nodes_as_points = 'Points'
k_nodes_as_shapes = 'Shapes'
k_vector_migrations_file_name = 'VectorMigrations.czml'
k_visset_file_name = 'visset.json'
static opacity_one(weight, norm_weight)
set_asset_map_path(asset_map_path)

Set the path to the optional asset map.

Returns:
None.
Args:
asset_map_path (str): Path to a VtAssetMap.json file containing the mapping between local asset paths and COMPS asset manager URLs. If this map is present, then the output visset.json will contain both local paths and asset manager URLs.
set_config(config_file_path)

Setter for config file path.

The VisSet needs to know how many timesteps are in the simulation. This can be obtained from any spatial binary, or from the config. This method allows you to specify the path to the config.json, and the VisSet will read the Simulation_Duration from there. Use this method if your simulation does not have any spatial binaries, and you just want to look at the nodes.

Note:
If you call add_spatial_reports() and there is at least one spatial binary, the VisSet will obtain the timestep count from that, and you do not need to call set_config at all.
Returns:
None.
Args:
config_file_path (str): Path to config.json file.
Raises:
I/O and JSON exceptions.
set_custom_base_layer(base_layer_path, friendlyName=None)

Setter for custom base layer source file.

The Geospatial Vis-Tools client allows the use of a single-tile globe image as its base layer. Such an image needs to be a high-resolution JPEG or PNG image that is an equirectangular projection.

Returns:
None.
Args:
base_layer_path (str): File path to a JPEG or PNG base layer image.
set_demographics(demographics_file_path)

Setter for the demographics file path.

This setter must be called before write(). The Geospatial client requires node locations for visualization. An internal Demographics object is created using the given path. If it is useful to access that object directly it can be obtained using the corresponding getter method. Note that if you have multiple demographics files (i.e. overlays) you can call set_demographics_files() instead.

For:
Geospatial visualization.
Returns:
None.
Args:
demographics_file_path (str): Path to demographics file.
Raises:
I/O and JSON exceptions.
set_demographics_files(demographics_file_list)

Setter for demographics from multiple overlay files.

This setter must be called before write(). The Geospatial client requires node locations for visualization. An internal Demographics object is created using the given path. If it is useful to access that object directly it can be obtained using the corresponding getter method. Note that if you have just a single demographics file you can call set_demographics() instead.

For:
Geospatial visualization.
Returns:
None.
Args:
demographics_file_list (list): Paths to demographics files.
Raises:
I/O and JSON exceptions.
set_event_recorder(event_recorder_file_path)

Setter for event recorder file path for marker layers.

This setter must be called before any calls to add_marker_layer(). An internal CSVReport object will be created with the data at the given path.

For:
Geospatial visualization.
Returns:
None.
Args:
event_recorder_file_path (str): Path to an ReportEventRecorder.csv.
Raises:
I/O and csv exceptions.
set_inset_chart(inset_chart_file_path)

Setter for inset chart data source file.

The Geospatial Vis-Tools client has an Inset Panel which shows inset chart data. Typically that data is sourced from an InsetChart.json file, but any file with the same format is allowable, such as ReportMalariaFiltered.json. This method allows the user to specify the source file for Insets.

Note:
If this method is not called with some json file path, the Inset Panel will not appear at all in the Geospatial client.
Returns:
None.
Args:
inset_chart_file_path (str): File path to InsetChart.json or other compatible file.
set_node_vis_type(node_vis_type)

Setter for the node visualization type.

For the Geospatial visualization client, there are two fundamental ways nodes may be represented: Points and Shapes. The former are 2D dots, measured in pixels and always perpendicular to the eye vector, which can be sized and styled variously. The latter uses 3D boxes, measured in meters, which can be styled as well but differently from Points. This setter is where the caller chooses which representation they want for their nodes. Each node visualization type has its own suite of settings.

The allowable node_vis_type values are provided as class constants.

For:
Geospatial visualization.
Returns:
None.
Args:
node_vis_type (str): “Points” or “Shapes”. See constants section.
set_output_directory(output_directory)

Setter for the output directory. THIS METHOD IS DEPRECATED. Use set_products_directory instead.”

This setter must be called before write().

Returns:
None.
Args:
output_directory (str): the directory in which to write the output visset.json file.
set_products_directory(products_directory)

Setter for products dir, where preprocessing products are written.

This setter must be called before write() or other methods that write preprocessing artifacts. This method replaces the now-deprecated set_output_directory method, which was replaced because of possible confusion with the simulation output/ directory.

Returns:
None.
Args:
products_directory (str): the directory into which to write the output visset.json and other preprocessing artifact files.
set_sim_id(sim_id)

Set a sim_id to be associated with this VisSet.

Returns:
None.
Args:
sim_id (str): Simulation ID as a GUID.
set_start_date(yyyy_mm_dd)

Setter for simulation start date.

If this is not given, the start date (that shows in the timeline in Vis-Tools visualizations) will be back-calculated from the number of timesteps such that the simulation ends on the date on which the preprocessing script was run. This setter allows you to set an arbitrary start date, and the timeline will start there instead.

Returns:
None.
Args:
yyyy_mm_dd (str): a date in the form “yyyy-dd-mm”, e.g. “1970-01-01”
set_target_client(client_name)

Setter for the selected target client.

This method sets the target client for the output visset. This causes the public member options to get overwritten with the defaults for the new client name. The allowable client names are provided as class constants.

Returns:
None.
Args:
client_name (str): “Geospatial” is the only target right now.
set_verbose(verbose)

Set whether the class emits verbose messages.

Returns:
None.
Args:
verbose (bool): True for verbose output, False for relative silence.
show_layer(vis_section)

Sets a layer to be shown by default in the output visset.json.

This method lets the caller set that the particular visualization section is shown by default when the visset is loaded by the client.

Returns:
None.
Args:
vis_section (str): The visualization section of the visset.json file. For the Geospatial client, valid values for vis_section are “nodeVis” or “heatmapVis”. Other clients will have other visualization sections. See defaultvisset.json.
update_nodes()

Updates the local summarized nodes from the Demographics source.

This method forces the VisSet object to refresh its summarized copy of the node data that it will later include in the written visset.json. Use this method if you change the data in the Demographics object and want those changes reflected in the output visset.json.

Returns:
None.
Args:
None.
update_ranges()

Updates the local min/max values for extra node fields.

This method updates the local min/max values that are calculated and later emitted into the visset.json file. Use this method if you change the values in the Demographics object.

Returns:
None.
Args:
None.
static update_urls(visset, asset_map_or_url_root)

Integrate COMPS Asset Manager URLs or update url roots.

This function does two different things, but they are encapsulated into this one function because this function is the only spot in VisSet that knows where all the URLs are in visset[links].

If passed an asset map, it adds “url_asset” entries next to “url” entries to allow the visset to be used in a hosted environment.

If passed a string, the “url” entries are updated to replace “./” with the given root. This makes the local paths suitable for use with a locally-hosted Vis-Tools.

Returns:
None.
Args:

visset (obj): A visset read with json.load or a VisSet __dict__.

asset_map (obj|str): Either an asset map read with json.load, or a string to be the new root for urls.

validate()

Validate the settings in the visset to ensure their validity.

This function validates the visset to increase the chances of it working correctly when brought into the client.

Returns:
None.
Args:
None.
To do:
  • Validate targetClient
  • Validate nodeVis.visType
  • Validate that self.nodes is populated
  • Validate that self.timestepCount and startDate are populated
  • Try to guess whether the list of spatial binaries is too big to be loaded on the client side
  • Validate binding sources have show=true
  • Validate binding functions to the extent possible
  • Validate that the inset chart file is a JSON and contains the expected keys
write(sim_url_root=None)

Write the customized VisSet object to a visset.json file in the products directory.

This method is called after the caller has made all their additions and modifications to the default visset to write a visset.json file to the products directory.

Returns:
None. Writes a “visset.json” file to the VisSet’s products directory.
Args:
sim_url_root (str): Optional. Url root substitution if desired. If not provided, URLs in the output visset will begin with “./”.
Raises:
I/O and JSON exceptions.
write_as(file_name, sim_url_root=None)

Write the customized VisSet object to a specified JSON file.

This method is called after the caller has made all their additions and modifications to the default visset to write a JSON file with the given name to the products directory.

Returns:
None. Writes a JSON file to the VisSet’s products directory.
Args:

file_name (str): The file name to use for the output visset JSON file.

sim_url_root (str): Optional. Url root substitution if desired. If not provided, URLs in the output visset will begin with “./”.

Raises:
I/O and JSON exceptions.