contents

Created by Gitanjali Bhattacharjee
10 November 2020


Contents of gbhattacharjee/sobol repository. If you have questions, please email me at gxbhattacharjee@gmail.com.

This repository includes all files (both scripts and results) necessary to reproduce the figures in the paper 'Using global variance-based sensitivity analysis to prioritise bridge retrofits in a regional road network subject to seismic hazard' by G. Bhattacharjee and J. W. Baker. Many of these figures have already been reproduced and stored in the directory figs. The scripts can be modified to estimate the Sobol' indices of bridges in other regional road networks, too. 

The traffic simulation portion of this code is modified from the simulator written by Mahalia Miller; for more detail than is provided in the paper, see her thesis at: https://stacks.stanford.edu/file/druid:hx023kk0983/Mahalia_Miller_PhD-augmented.pdf. Miller also collected much of the bridge information used in this work and created the original version of the road network graph used.

To get an estimate of bridges' total-order Sobol' indices, simply run main() in process_results_sf.py. 

Note that estimating total-order Sobol' indices and creating various plots based on those estimates or the existing retrofit results is doable on a local machine. 

Running new samples (or re-running existing samples) using run_sobol.py will likely take significantly longer. The results in this repository were obtained using a high-performance cluster, not a local machine. 

To profile performance, either

(1) Run a batch containing a single sample of the fragility function parameter vector F using run_sobol.py.
(2) Get the runtime of a single function evaluation. Run mahmodel_road_only.py on a single damage map (i.e., run a single traffic assignment). It will take (N x B x S x D) times the runtime of that single function evaluation to estimate the total-order Sobol' indices of a set of B bridges based on N samples with S scenarios and D damage maps per scenario.

The files necessary to run retrofit testing for different retrofit strategies are also included in this repository.


*** INPUT ***
- input -- contains a variety of files necessary to run traffic simulations of the damaged road network, including
- input/sf_fullr_dict.pkl -- subset of master_bridge_dict_GB_omegas.pkl containing 71 bridges of interest in San Francisco; modified from '20140114_master_bridge_dict.pkl' in https://github.com/bakerjw/bayAreaTransportation. This is a nested dictionary with the first key being bridge (original) ID and nested keys being:
	 - 'a_b_pairs_direct' -- list of (a,b) tuples that would be directly affected by bridge damage -- the bridge is carrying these roads (edges).
	 - 'a_b_pairs_indirect' -- list of (a,b) tuples that would be indirectly affected indirectly (e.g., underpasses) by damage to the bridge.
	 - 'age' -- age of the bridge in years.
	 - 'area' -- area of bridge deck in [square feet], used for repair and retrofit cost estimation. Computed as the product of the bridge length and deck width.
	 - 'com_lnSa' -- fragility function parameter (median lnSa) for the complete (collapsed) damage state of the bridge, in [g]. See Miller's thesis or the HAZUS/MCEER method for more detail.
	 - 'county' -- county in which the bridge is located.
	 - 'edge_ids_direct' -- edge object IDs for edges that would be directly affected by bridge damage; another way to describe the (a,b) tuples.
	 - 'edge_ids_indirect' --edge object IDs for edges that would be indirectly affected by bridge damage (e.g., underpasses); another way to describe the (a,b) tuples.
	 - 'ext_lnSa' -- fragility function parameter (median lnSa) for the extensive damage state of the bridge, in [g]. See Miller's thesis or the HAZUS/MCEER method for more detail.
	 - 'jessica_id' -- artefact of previous modeling; not used.
	 - 'loren_row_number' -- artefact of previous modeling; not used.
	 - 'mod_lnSa' -- fragility function parameter (median lnSa) for the moderate damage state of the bridge, in [g]. See Miller's thesis or the HAZUS/MCEER method for more detail.
	 - 'new_id' -- the new ID that excludes filtered-out bridges; ranges from [1-1743]. Per Mahalia Miller.
	 - 'omega' -- factor by which we multiply the bridge's ext_lnSa to model seismic retrofit.
	 - 'original_id' -- original ID of the bridge; ranges from [1-1889]. Per Mahalia Miller.
	 - 'repair' -- estimated bridge repair cost, in [USD]. NOT USED.
	 - 'traffic' -- daily average traffic volume that passes over the bridge, as of 2010.

- input/sf_fullr_bridge_ids.pkl -- list of bridge (original) IDs, used to ensure consistency in the order in which we iterate over bridges in the case study
- input/master_bridge_dict_GB_omegas.pkl -- nested dictionary with first key being bridge (original)ID and nested keys being the same as in sf_fullr_dict.pkl; contains all 1743 bridges owned by Caltrans in the SF Bay Area
- input/graphMTC_GB.gpickle -- graph of the road network, including bridges. This is a modified version of graphMTC.gpickle created by Mahalia Miller -- see her thesis at https://stacks.stanford.edu/file/druid:hx023kk0983/Mahalia_Miller_PhD-augmented.pdf for further details.
- input/sample_ground_motion_intensity_maps_road_only_filtered.txt -- 1992 ground-motion intensity maps (Sa at T = 1s) for the 1743 bridges owned by Caltrans in the SF Bay Area. Each row is a map. Per Mahalia Miller, creator of this dataset, the columns refer to:  first column is simulation number, second is fault id, third is magnitude, fourth is the annual occurrence rate (SUPER USEFUL), fifth is Sa (NOT logSa) in site new ID 1, sixth is Sa in site new ID 2, ...site ID n. This is a full hazard-consistent set of events. See her thesis at https://stacks.stanford.edu/file/druid:hx023kk0983/Mahalia_Miller_PhD-augmented.pdf for further details.

*** SOBOL_INPUT ***
- sobol_input -- contains files necessary to implement the Sobol' index method, including:
- sobol_input/F_samples_sf_fullr_*.pkl -- batches of samples of the fragility function parameter vector, sampled assuming each bridge has equal probabilities of being retrofitted and of being unretrofitted
- sobol_input/F_prime_samples_sf_fullr_*.pkl -- batches of samples of the fragility function parameter vector, sampled assuming each bridge has equal probabilities of being retrofitted and of being unretrofitted; same dimensions as associated F_samples_sf_fullr_*.pkl file, with which it is interleaved to create hybrid points
- sobol_input/sf_fullr_training_map_indices.pkl -- indices (row numbers in sample_ground_motion_intensity_maps_road_only_filtered.txt) of the 30 ground-motion maps that make up the training set
- sobol_input/sf_fullr_training_map_weights.pkl -- weights (annual rates of occurrence) of the ground-motion maps in the training set
- sobol_input/sf_fullr_testing_map_indices.pkl -- indices (row numbers in sample_ground_motion_intensity_maps_road_only_filtered.txt) of the 45 ground-motion maps that make up the testing set
- sobol_input/sf_fullr_testing_map_weights.pkl -- weights (annual rates of occurrence) of the ground-motion maps in the testing set
- sobol_input/U_good_sf_fullr.pkl -- a set of common random numbers used to sample damage maps in compute_bridge_sobol_sf_full.py
- sobol_input/sf_fullr_2020 - *_rets.csv -- a list of bridges, in order of decreasing retrofit priority according to the strategy (denoted by *) in the title of the file

*** SOBOL_OUTPUT ***
- sobol_output/run_sf_fullr_total_all -- contains the results of evaluations of points and hybrid points (F and F'). The results are batched; each batch includes 5 samples.
- sobol_output/retrofits -- contains the results of retrofit strategies based on bridge characteristics (age, fragility, traffic volume, and the composite thereof), one-at-a-time (OAT) analysis, and the Sobol' index-based strategy. Also contains the results of Sobol' index-based retrofit strategies computed with respect to different numbers of samples used to estimate Sobol' indices.


*** SCRIPTS *** 
mahmodel_road_only.py -- function main() performs traffic simulation for a particular sample of the fragility function parameter vector; for each sample, it simulates D damage maps for each of S scenarios in the specified set of ground-motions and returns the expected cost of the road network performance, among other outputs. This is a modified version of the file of the same name created by Mahalia Miller and available at https://github.com/bakerjw/bayAreaTransportation. 

compute_bridge_sobol_sf_full.py -- contains the function run_sobol_computation(), which processes batches of samples of the fragility function parameter vector and stores the expected costs (as well as other outputs of interest) in sobol_output.

process_retrofit_results.py -- processes the reduction in the expected cost of network performance that results from each retrofit strategy at each number of retrofits tested, then plots the results.

run_sobol.py -- wrapper function in which we specify the settings of a Sobol' index computation, run a limited number of samples, and time itul

retrofit_testing.py -- tests the six retrofit strategies of interest on a set of S = 45 ground-motion maps.

run_retrofit_testing_sf_fullr.py -- wrapper function in which we specify the settings for retrofit_testing.py.

make_retrofit_samples.py -- creates fragility function parameter vectors that correspond to user-specified retrofits. Use to make F_samples_*.pkl and F_prime_samples_*.pkl.

network_effects.py -- computes and plots network effects of retrofits for each strategy.

mahmodel_road_only.py -- modified version of mahmodel_road_only.py in https://github.com/bakerjw/bayAreaTransportation. Used to compute the expected cost of the road network performance for a given fragility function parameter vector (sample) in the Sobol' index method.

make_inputs.py -- creates samples of fragility function parameter vector in which each bridge has equal probabilities of being retrofitted and being unretrofitted.

ita_cost.py -- iterative traffic assignment module described in more detail in Mahalia Miller's thesis. Modified version of ita.py in repository at https://github.com/bakerjw/bayAreaTransportation that implements the changes specified in travel_model_notes.

travel_model_notes.pdf -- documents changes made to a previous version of ita.py written by Mahalia Miller.

bd_test.py -- contains a function to build the origin-destination matrix required to run traffic simulations. Modification of bd.py written by Mahalia Miller and available at https://github.com/bakerjw/bayAreaTransportation.

util.py -- various helper functions used in mahmodel_road_only.py; written by Mahalia Miller and also available at https://github.com/bakerjw/bayAreaTransportation.

make_convergence_plots_total.py -- check the convergence of bridges' estimated total-order Sobol' indices as sample size changes.

make_ranking_convergence_plots.py -- check the convergence of bridge rankings based on estimated Sobol' indices as sample size changes.

process_results_sf.py -- prints estimates of the total-order Sobol' indices of all 71 bridges in the case study to the screen.

ret_cost_test.py -- test different ways to account for the cost of retrofits in the Sobol' index method. Note that 'ret_ratio_reverse' is the ratio of the expected cost of road network performance to the cumulative retrofit cost; running plot_retrofit_results_vs_cumulative_retrofit_cost('ret_ratio_reverse') will reproduce the figure in the paper.