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

  • conventions otherwise. (Python) –

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

  • conventions otherwise. (Python) –

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

  • conventions otherwise. (Python) –

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.