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

k_default_node_altitude = 1

bounding_box(for_json=True)

Returns a geospatial bounding box for the nodes.

Returns:

bounding box in either Python or Javascript style.

Return type:

obj

Parameters:

• for_json (bool) – If true, emits Javascript naming conventions, or

• otherwise. (Python conventions) –

population_range(for_json=True)

Returns the range of InitialPopulation for all nodes.

Returns:

range of population in either Python or Javascript style.

Return type:

obj

Parameters:

• for_json (bool) – If true, emits Javascript naming conventions, or

• otherwise. (Python conventions) –

minimum_deltas(for_json=True)

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

Returns:

minimum non-zero lat/long deltas in either Python or Javascript style.

Return type:

obj

Parameters:

• for_json (bool) – If true, emits Javascript naming conventions, or

• otherwise. (Python conventions) –

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:

The adjusted maximum InitialPopulation.

Return type:

int

Parameters:

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:

number of nodes updated.

Return type:

int

Parameters:

alt_csv (str) – The file path of the CSV file with altitudes.

Raises:

I/O and CSV exceptions. –

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:

An array of objects representing the nodes.

Return type:

array

Parameters:

None. –

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:

index

Return type:

dict<value, array<node_id>>

Parameters:

node_attribute_field (str) – field name within NodeAttributes.