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.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

k_default_cesium_view_margin_fraction = 0.28

k_min_shape_px = 2.0

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.

Parameters:

dir_path (str) – Directory path to survey.

Raises:

I/O, csv, JSON, and custom exceptions. –

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.

Parameters:

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:

a set of event names, or None.

Return type:

set

Parameters:

None. –

Raises:

I/O and csv 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:

a set of simple field names from NodeAttributes or None.

Return type:

set

Parameters:

None. –

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:

Channel names read from one of the inset-format files, sorted into alphabetical order, or None.

Return type:

list

Parameters:

None. –

Raises:

I/O and json exceptions. –

calc_default_shape_size()

Returns a default size for shape-based visualizations.

For shape-based geospatial visualizations, this method calculates a default size in meters that will hopefully make the nodes visible at the default zoom in the geospatial client.

Returns:

size in meters

Return type:

float

Parameters:

None. –

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.

Parameters:

• 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. –

vis_tools.Survey.update_visset(visset_path, asset_map_path)

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

Returns:

None.

Parameters:

• visset_path (str) – Path to visset.json file

• asset_map_path (str) – Path to VtAssetMap.json file

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.