ShakeCast Manual 

By Kuo-Wan Lin and David J. Wald 

Open-File Report 2008–1158 

U.S. Department of the Interior 

U.S. Geological Survey 
U.S. Department of the Interior 

DIRK KEMPTHORNE, Secretary 

U.S. Geological Survey 

Mark D. Myers, Director 

U.S. Geological Survey, Reston, Virginia: 2008 

For product and ordering information: 

World Wide Web: http://www.usgs.gov/pubprod 

Telephone: 1-888-ASK-USGS 

For more information on the USGS—the Federal source for science about the Earth, 

its natural and living resources, natural hazards, and the environment: 

World Wide Web: http://www.usgs.gov 

Telephone: 1-888-ASK-USGS 

Suggested citation: 

Lin, K.W., and Wald, D.J., 2008, ShakeCast manual: U.S. Geological Survey Open-File Report 2008-1158, 90 p. 

Any use of trade, product, or firm names is for descriptive purposes only and does not imply 

endorsement by the U.S. Government. 

Although this report is in the public domain, permission must be secured from the individual 

copyright owners to reproduce any copyrighted material contained within this report. 

ii
Contents 

Contents ..............................................................................................................................................................................iii

1. Introduction .....................................................................................................................................................................1

1.1 What is ShakeCast? .................................................................................................................................................1

1.2 ShakeCast Technology............................................................................................................................................2

1.3 Where Can ShakeCast Be Used? ..........................................................................................................................3

1.4 ShakeCast Availability .............................................................................................................................................4

1.5 Acknowledgments....................................................................................................................................................4

2. Installation .......................................................................................................................................................................5

2.1 Hardware/Software Requirements .......................................................................................................................6

2.2 Initial Installation ......................................................................................................................................................6

2.3 Finalize Installation.................................................................................................................................................12

2.4 Uninstalling ShakeCast..........................................................................................................................................13

2.5 Setup .........................................................................................................................................................................14

3. ShakeCast User Web Interface .................................................................................................................................15

3.1 System Requirements............................................................................................................................................16

3.2 Log in Procedure.....................................................................................................................................................16

3.3 Log out Procedure ..................................................................................................................................................16

3.4 Front Page of ShakeCast Portal ...........................................................................................................................16

3.5 Primary Navigation Link Tabs...............................................................................................................................17

3.6 Listing of the ShakeCast Summary for Earthquakes........................................................................................17

3.7 ShakeCast Facility Damage Assessment...........................................................................................................18

3.8 Search Facilities .....................................................................................................................................................20

3.9 Frequently Asked Questions (FAQ)......................................................................................................................21

3.10 User Profile Management...................................................................................................................................21

3.11 User Registration ..................................................................................................................................................24

4. ShakeCast Administrator Web Interface.................................................................................................................26

4.1 General Administration..........................................................................................................................................27

4.1.1 Backup Database ............................................................................................................................................27

4.1.2 General Configuration.....................................................................................................................................27

4.1.3 Log Viewer ........................................................................................................................................................29

4.1.4 Mass Email........................................................................................................................................................30

4.1.5 Restore Database ............................................................................................................................................31

4.1.6 ShakeMap Server............................................................................................................................................31

4.1.7 System Service.................................................................................................................................................33

4.1.8 Task Repeater...................................................................................................................................................38

4.1.9 Template............................................................................................................................................................39

4.2 Event Administration ..............................................................................................................................................42

4.2.1 Processed Event ..............................................................................................................................................42

4.2.2 Test Event..........................................................................................................................................................44

4.2.3 USGS ShakeMap .............................................................................................................................................45

4.3 Facility Administration ...........................................................................................................................................46

4.3.1 Damage Level ...................................................................................................................................................46

iii
4.3.2 Facility Type ......................................................................................................................................................47

4.3.3 Management.....................................................................................................................................................48

4.3.4 Supplemental Attribute...................................................................................................................................50

4.3.5 Upload................................................................................................................................................................50

4.4 Profile Administration ............................................................................................................................................51

4.4.1 Management.....................................................................................................................................................52

4.4.2 Notification Request........................................................................................................................................52

4.4.3 Upload................................................................................................................................................................55

4.5 User Administration................................................................................................................................................56

4.5.1 Management.....................................................................................................................................................56

4.5.2 Notification Request........................................................................................................................................57

4.5.3 Replication ........................................................................................................................................................57

4.5.4 Upload................................................................................................................................................................58

4.6 Miscellaneous Administration .............................................................................................................................59

4.6.1 Web Access to ShakeCast System Version 1 ............................................................................................59

4.6.2 PMA Access .....................................................................................................................................................59

4.6.3 Database Configuration..................................................................................................................................59

4.6.4 Default Center Location..................................................................................................................................59

5. XML Documents ...........................................................................................................................................................60

5.1 ShakeMap RSS Feed XML ....................................................................................................................................60

5.2 Event XML ................................................................................................................................................................61

5.3 Product XML............................................................................................................................................................61

5.4 ShakeMap XML.......................................................................................................................................................61

5.5 Exposure XML .........................................................................................................................................................61

6. ShakeCast Utilities .......................................................................................................................................................63

6.1 heartbeat..................................................................................................................................................................63

6.1.1 Name..................................................................................................................................................................63

6.1.2 Synopsis ............................................................................................................................................................63

6.1.3 Description........................................................................................................................................................63

6.2 logrotate ...................................................................................................................................................................64

6.2.1 Name..................................................................................................................................................................64

6.2.2 Synopsis ............................................................................................................................................................64

6.2.3 Description........................................................................................................................................................64

6.2.4 Options...............................................................................................................................................................64

6.3 logstats .....................................................................................................................................................................65

6.3.1 Name..................................................................................................................................................................65

6.3.2 Synopsis ............................................................................................................................................................65

6.3.3 Description........................................................................................................................................................65

6.3.4 Options...............................................................................................................................................................65

6.4 manage_event.........................................................................................................................................................66

6.4.1 Name..................................................................................................................................................................66

6.4.2 Synopsis ............................................................................................................................................................66

6.4.3 Description........................................................................................................................................................66

6.4.4 Options...............................................................................................................................................................66

6.5 manage_facility.......................................................................................................................................................67

iv
6.5.1 Name..................................................................................................................................................................67

6.5.2 Synopsis ............................................................................................................................................................67

6.5.3 Description........................................................................................................................................................67

6.5.4 Options...............................................................................................................................................................67

6.5.5 File Format.........................................................................................................................................................68

6.5.6 Example .............................................................................................................................................................69

6.6 manage_profile .......................................................................................................................................................72

6.6.1 Name..................................................................................................................................................................72

6.6.2 Synopsis ............................................................................................................................................................72

6.6.3 Description........................................................................................................................................................72

6.6.4 Options...............................................................................................................................................................72

6.6.5 File Format.........................................................................................................................................................72

6.7 manage_user...........................................................................................................................................................75

6.7.1 Name..................................................................................................................................................................75

6.7.2 Synopsis ............................................................................................................................................................75

6.7.3 Description........................................................................................................................................................75

6.7.4 Options...............................................................................................................................................................75

6.7.5 File Format.........................................................................................................................................................76

6.8 scfeed_local ............................................................................................................................................................78

6.8.1 Name..................................................................................................................................................................78

6.8.2 Synopsis ............................................................................................................................................................78

6.8.3 Description........................................................................................................................................................78

6.8.4 Options...............................................................................................................................................................78

6.9 shake_fetch .............................................................................................................................................................79

6.9.1 Name..................................................................................................................................................................79

6.9.2 Synopsis ............................................................................................................................................................79

6.9.3 Description........................................................................................................................................................79

6.9.4 Options...............................................................................................................................................................79

6.10 template..................................................................................................................................................................80

6.10.1 Name................................................................................................................................................................80

6.10.2 Synopsis ..........................................................................................................................................................80

6.10.3 Description......................................................................................................................................................80

6.10.4 Options.............................................................................................................................................................80

6.10.5 File Format.......................................................................................................................................................80

6.11 tester.......................................................................................................................................................................85

6.11.1 Name................................................................................................................................................................85

6.11.2 Synopsis ..........................................................................................................................................................85

6.11.3 Description......................................................................................................................................................85

6.11.4 Options.............................................................................................................................................................85

References.........................................................................................................................................................................86

A.1 Selecting Model Building Type and Code Era ..................................................................................................87

A.2 Describing Damage ...............................................................................................................................................88

A.3 Relating Seismic Excitation to Structural Damage..........................................................................................88

A.4 Tabular Lookup Data .............................................................................................................................................88

v
Figures 

Figure 1.1 ShakeCast flow chart indicating flow of USGS ShakeMap data, users’ ShakeCast inventory and 

user databases, and notifications. ..................................................................................................................................2

Figure 1.2 The ShakeCast users’ interface summary page in mapping mode..........................................................3

Figure 2.1 ShakeCast overview from the users’ perspective. .....................................................................................5

Figure 3.1 Default Web page of the ShakeCast Portal................................................................................................15

Figure 3.2 The Earthquake page listing the events processed by the ShakeCast system and the number of 

evaluated facilities in reverse chronological order. ..................................................................................................18

Figure 3.3 The Event page displaying in table mode.. .................................................................................................19

Figure 3.4 The Event page displaying in map mode.....................................................................................................20

Figure 3.5 The search result of a facility displaying parameters for the facility and the history of damage 

estimates from previous earthquakes. .........................................................................................................................21

Figure 3.6 The General Settings page displaying editable information for a registered ShakeCast user.........23

Figure 3.7 The Delivery Methods page displaying user defined email addresses for receiving ShakeCast 

notification... ......................................................................................................................................................................24

Figure 3.8 The Notification Profiles page displaying a list of predefined notification profiles to the user.. .....24

Figure 3.9 The Registration page displaying a form in which the prospective user submits contact 

information for review.. ...................................................................................................................................................25

Figure 4.1 Default Web page of the ShakeCast administration interface. ..............................................................26

Figure 4.2 The database backup page has three backup options: full, structure-only, or data-only.................27

Figure 4.3 The general configuration page handleing system-wide options regarding system identity and 

policy settings. ..................................................................................................................................................................28

Figure 4.4 The cookie settings determining the time window for persistent log-in and system identification 

on the remote system. .....................................................................................................................................................28

Figure 4.5 The Email Settings Block holding information of the email server for all email messages sent from 

the administrative interface............................................................................................................................................29

Figure 4.6 The ShakeCast Log File Viewer page listing available log files for viewing.........................................29

Figure 4.7 The ShakeCast Log File Viewer page for a selected log file.. .................................................................30

Figure 4.8 The email form page for composing an email message. .........................................................................31

Figure 4.9 The Database Restore page..........................................................................................................................31

Figure 4.10 The ShakeCast Server Administration page listing available servers and their current status.....32

Figure 4.11 The Server Settings page for adding and editing servers to the ShakeCast database. ..................32

Figure 4.12 The Server Password Configuration page................................................................................................33

Figure 4.13 The General System Service Settings page handling system-wide options regarding all 

ShakeCast system services and command line utilities. ..........................................................................................34

Figure 4.14 The Local Injection Server Settings determining the destination server and authentication 

information on the remote system.................................................................................................................................34

Figure 4.15 The Web Server Access Control holding information of the Apache Web server for access 

control.................................................................................................................................................................................35

Figure 4.16 The Dispatcher Service holding information of the ShakeCast Dispatcher process. ......................35

Figure 4.17 The Polling Service holding information of the ShakeCast Polling process. .....................................36

Figure 4.18 The Notification Queuing Service holding information of the ShakeCast Notification Queuing 

process...............................................................................................................................................................................36

Figure 4.19 The Notification Service holding information of the ShakeCast Notification process.....................37

vi
Figure 4.20 The RSS Service holding information of the ShakeCast RSS process................................................37

Figure 4.21 The Notification SMTP Settings Service holding information of the email server for all email 

messages sent by the ShakeCast system services. ..................................................................................................38

Figure 4.22 The Logrotate and Logstats Settings holding information of both the logrotate and logstats 

ShakeCast utilities............................................................................................................................................................38

Figure 4.23 The ShakeCast Task Repeater page listing scheduled tasks on the local system and their runtime information................................................................................................................................................................39

Figure 4.24 The Task Repeater Add page......................................................................................................................40

Figure 4.26 The ShakeCast Template Preview page.. .................................................................................................41

Figure 4.27 The ShakeCast Template Edit page.. .........................................................................................................42

Figure 4.28 The Processed Event List page listing all previously processed ShakeMaps for the local 

system.................................................................................................................................................................................43

Figure 4.29 The Event Comment page allowing the administrator to add additional information for the 

specified event for ShakeCast users whom are the recipients of notifications and/or on the ShakeCast 

portal page for the event.................................................................................................................................................44

Figure 4.30 The ShakeCast Test Event List page listing available test events residing on the local system. 

From this interface, an administrator can trigger a local test event or convert a processed ShakeMap 

into a test event. ...............................................................................................................................................................45

Figure 4.31 The USGS ShakeMap page listing available ShakeMaps on the USGS Web server for both 

actual and scenario events.. ..........................................................................................................................................46

Figure 4.32 The Damage Level Administration page listing defined damage levels on the local server...........47

Figure 4.33 The Facility Type Administration page of the ShakeCast administration interface..........................48

Figure 4.34 The Facility Type Editing page.. ..................................................................................................................48

Figure 4.35 The Facility Administration page displaying a list of user-defined facilities on the local system..49

Figure 4.36 The Facility Editing page displaying a form containing facility-specific information and 

optional fragility-setting information, either default or custom values. .................................................................50

Figure 4.37 The Facility Upload page..............................................................................................................................51

Figure 4.38 The Profile Administration page listing defined profiles on the local system that are available 

to the ShakeCast users for subscription. .....................................................................................................................52

Figure 4.39 The profile polygon page displaying a Google Maps-based GIS interface of a defined 

polygon for the profile......................................................................................................................................................52

Figure 4.40 The Profile Notification Request Administration summary page listing available profiles and 

their notification request settings.. ...............................................................................................................................53

Figure 4.41 The Notification Request summary page listing defined notification request settings for a 

profile..................................................................................................................................................................................53

Figure 4.42 The Notification Request editing page displaying a configurable form for the specified 

request type.......................................................................................................................................................................54

Figure 4.43 The profile-facility association page displaying a list of facilities included in the profile...............55

Figure 4.44 The Profile Upload page...............................................................................................................................55

Figure 4.45 The User Administration Summary page displaying a list of ShakeCast users including their 

privileges and status........................................................................................................................................................56

Figure 4.46 The User Administration Data Editing page displaying a form of editable fields containing contact 

information, notification preferences, and user status for the specified user. ....................................................57

Figure 4.47 The User/Profile Replication Administration page displaying two panels for both source and 

destination of the replication process..........................................................................................................................58

vii
viii

Figure 4.48 The User Upload page..................................................................................................................................58

Figure A.1 Seismic zone map of the United States (fig. 16-2, ICBO, 1997)...............................................................87

Tables 

Table 2.1.ShakeMap region code and description ....................................................................................................13

Table A.1.HAZUS-MH earthquake model building types (NIBS and FEMA 2003 Table 3.1)...............................89

Table A.2. HAZUS-MH Guidelines for Selection of Damage Functions for Typical Buildings Based on 

UBC Seismic Zone and Building Age (NIBS and FEMA 2003 Table 5.20)...............................................................90

Table A.3.Layout of damage lookup tables..................................................................................................................90
ShakeCast Manual 

By Kuo-Wan Lin and David J. Wald 

1. Introduction 

ShakeCast is a freely available, post-earthquake situational awareness application that 

automatically retrieves earthquake shaking data from ShakeMap, compares intensity measures 

against users’ facilities, and generates potential damage assessment notifications, facility damage 

maps, and other Web-based products for emergency managers and responders. 

1.1 What is ShakeCast? 

ShakeCast, short for ShakeMap Broadcast, is a fully automated system for delivering 

specific ShakeMap products to critical users and for triggering established post-earthquake 

response protocols. ShakeMap is a well-established tool used to portray the extent of potentially 

damaging shaking following an earthquake. It is available and can be found on the Internet at 

http://earthquake.usgs.gov/shakemap. It was developed for and is used primarily for emergency 

response, loss estimation, and public information. However, for an informed response to a serious 

earthquake, critical users must go beyond just looking at ShakeMap, and understand the likely 

extent and severity of impact on the facilities for which they are responsible. To this end the U.S. 

Geological Survey (USGS) has developed ShakeCast. 

ShakeCast allows utilities, transportation agencies, businesses, and other large organizations 

to control and optimize the earthquake information they receive. With ShakeCast, they can 

automatically determine the shaking value at their facilities, set thresholds for notification of 

damage states for each facility, and then automatically notify (via pager, cell phone, or email) 

specified operators and inspectors within their organizations who are responsible for those 

particular facilities so that they can set priorities for response. A schematic diagram showing the 

ShakeMap/ShakeCast flow of data and information is shown in figure 1.1. 

In addition to real-time notification, ShakeCast also can generate and deliver scenario 

earthquakes for facility response plans (fig. 1.2). This application includes routine testing of the 

system, earthquake scenario exercises, and evaluating performance and response under potential 

earthquake conditions. ShakeMap is now used routinely to generate earthquake scenarios for many 

regions; ShakeCast will further allow planning exercises to be performed using the same 

notification tools that will be available and in place for responding to a real earthquake. 

1
Figure 1.1 ShakeCast flow chart indicating flow of USGS ShakeMap data, users’ 

ShakeCast inventory and user databases, and notifications. 

1.2 ShakeCast Technology 

Individuals, companies, utilities, and agencies could develop their own strategies and tools for 

utilization of ShakeMap given their unique facilities and communication paths. However, such 

efforts are costly and complex. Instead, USGS is facilitating this process with ShakeCast, building 

a more general-use tool for most of the critical user needs. The ShakeCast software is customizable 

for facilities, fragilities, and notifications, and we anticipate additional adaptations will be made 

because the open-source code is provided. Such innovations then can be provided into the tool kit 

included with updates of the ShakeCast system. 

Information Technology (IT) security is a primary concern for users requiring automatic 

electronic delivery of information. By taking advantage of standard Internet protocols, ShakeCast 

users avoid most typical corporate and government concerns and firewall limitations. By using 

Really Simple Syndication (RSS) and interval polling, users initiate all communications with the 

USGS Web servers that host ShakeMap and retrieve selected products as a request rather than a 

“push.” This RSS approach allows users to update software automatically under conditions of their 

own choosing. 

ShakeCast software is built upon open-source tools, providing standard, freely available 

software for all users, encouraging user improvements, and simplifying interfacing with existing 

users’ response tools. ShakeCast uses the Apache Web server and PHP (Hypertext Preprocessor) 

for dynamic Web content, MySQL for facility and notification databases, and is wrapped in 

2
Practical Extraction and Report Language (PERL) scripting. Exchange files are in Extensible 

Markup Language (XML) for standardized interfacing with Web, geographic information systems 

(GIS), spreadsheets, databases, and other applications. 

Figure 1.2 The ShakeCast users’ interface summary page in mapping mode. The unique 

features in the mapping mode include variable image size, selectable facility type, 

customizable facility icons, and color-coding to show possible damage. 

1.3 Where Can ShakeCast Be Used? 

ShakeMap is now produced for all earthquakes around the globe of magnitude 5.5 or larger. 

Globally, these ShakeMaps are primarily predictive and thus lack the resolution and certainty of 

shaking estimates for maps made in regions of dense seismic instrumentation for which it was 

principally developed. Regions in the United States that have ShakeMap operating with reasonable 

(but variable) seismic station coverage include major parts of California, Washington, Oregon, 

Nevada, Utah, Hawaii, and Alaska. Other regions are improving station coverage. Hence, since 

ShakeMaps are produced for any region of the world, ShakeCast can be deployed for any exposure 

of facilities worldwide, again with more uncertainty for the results in regions not specifically listed 

above. 

3
We use the term “facilities” loosely; at the USGS National Earthquake Information Center 

(NEIC) in Golden, Colo., we assign cities as “facilities” and run ShakeCast to determine shaking 

levels at cities within the United States and around the globe any time a ShakeMap is produced. 

The list of cities, their populations, and the intensity estimated at each city becomes a Hypertext 

Markup Language (HTML) email notification that proves useful for NEIC analysts and for other 

response purposes. Ultimately, these city-based notifications will be integrated as an option in the 

USGS Earthquake Notification Service (ENS), but it does not reduce the need for critical users to 

put their own inventories in an in-house ShakeCast system. 

1.4 ShakeCast Availability 

ShakeCast is available in two levels, full and “Lite.” We describe in detail the full 

ShakeCast system that allows users to estimate impact to numerous facilities, each potentially with 

different vulnerabilities and notification recipients. We expect this system to be deployed by critical 

users in an earthquake-hardened, operational environment. We have also made available ShakeCast 

Lite, a subset of the system that allows users to automatically receive ShakeMap products on their 

laptop or desktop computers, and launch predefined applications using those maps or data. For 

example, many users employ ShakeCast Lite to automatically open a Web browser showing the 

latest ShakeMap in their region, launch Google Earth® with the ShakeMap KML file, download 

ShakeMap grid files and initiate loss-estimation applications, or deliver ShakeMap GIS files to 

their corporate GIS department for further analyses. ShakeCast Lite is simple to install and use. 

1.5 Acknowledgments 

USGS contracted with Gatekeeper Systems, Inc., Pasadena, Cali., to help develop the prototype 

ShakeCast system (Version 1.0). Earlier funding for ShakeCast was provided by the American 

Lifelines Alliance (ALA), and it is now supported by the U.S. Geological Survey under the 

Advanced National Seismic System (ANSS). Motivation and support for the development of 

Version 2 of ShakeCast was provided by the California Department of Transportation (Caltrans) 

under the coordination efforts of Loren Turner. 

4
2. Installation 

An overview of ShakeCast from the users’ perspective is provided in figure 2.1. 

Organizations using ShakeMap/ShakeCast first download and install the ShakeCast (Version 2) 

software package on a hardened in-house computer system. The software is installed with an 

interactive installation script. Facility, vulnerability, and notification data are input using import 

tools and simple, comma separated (CSV) users’ files. ShakeCast comes preconfigured, but custom 

configuration is simplified via ShakeCast tools and the Web interface. The Web interface allows an 

administrator to access all functions of the local ShakeCast system, and end users are able to 

manage their own personal information and notification preferences. 

Figure 2.1 ShakeCast overview from the users’ perspective. 

5
2.1 Hardware/Software Requirements 

Version 2 of ShakeCast has been tested on a Microsoft Windows PC computer running the 

XP Professional operating system. Although the installation package is currently only available for 

Microsoft Windows, we plan to provide support for UNIX, Mac, and LINUX operating systems in 

the future. 

2.2 Initial Installation 

To start the ShakeCast installation process: 

1. The installer unpacks the files needed for the installation, which takes less than a minute. After 

unpacking the installation files, the installer presents an option to view the license agreement. 

You may choose to Accept the license agreement and continue the installation process. 

2. The installer displays a Choose Components screen that allows you to choose programs to 

install. We recommend that you keep the default settings, unless you are an advanced user who 

wants more precise control over the components that will be installed. 

6
3. After ensuring that the desired program features are selected, click the Next button to continue 

with the installation. Now that you have given the installer all of the information it needs to 

proceed, progress boxes track the installation process. 

After installing the core ShakeCast script, the installer will download and start the ActivePerl setup 

dialog. Click the Next button to continue with the installation. 

4. After installing the ActivePerl software, the installer will download and start the Apache Web 

server setup dialog. Click the Next button to continue with the installation. 

7
5. After installing the Apache software, the installer will download and start the MySQL database 

setup dialog. Click the Next button to continue with the installation. 

6. After installing the MySQL software, configure the database and create a root password. 

8
7. After completing the MySQL software configuration, the installer will download and start the 

PHP setup dialog. Click the Next button to continue with the installation. 

8. After completing the core PHP installation, the installer will start the PHP configuration dialog. 

Select Apache 2.0.x Module then click the Next button to locate the installation directory for 

Apache Web server. 

9
9. In the last step of PHP setup configuration, select to install the Extensions GD2, Multi-byte 

String, Mcrypt, Mysql, Mysqli, and SMTP. Click the Next button to continue with the 

installation. 

10. After completing the PHP installation, the installer will start the Perl module installation. A 

DOS Window will appear showing the progress of module installation. 

10
11. After completing the Perl module installation, the installer will start the ShakeCast database 

configuration. A new DOS Window will appear with a prompt for the password to access the 

database. Type in the root password entered during the MySQL installation and hit Enter to 

continue with the installation. 

12. After completing the ShakeCast database creation and data population, a brief dialog confirms 

the last steps of the installation process. 

11
2.3 Finalize Installation 

A few final configuration steps are required. 

1. Notification. The file "c:\shakecast\sc\conf\sc.conf" contains a Notification section that looks 

like: 

# Notification Configuration 

<Notification> 

From shakemaster@example.com 

EnvelopeFrom shakemaster@example.com 

SmtpServer smtp.example.com 

DefaultEmailTemplate default.txt 

DefaultScriptTemplate default.pl 

#Username username 

#Password password 

</Notification> 

Modify the From (what an email recipient sees), EnvelopeFrom (what the SMTP server uses in 

the protocol) and the SmtpServer fields to define how email notifications will be sent. 

Uncomment and edit the Username and Password fields if authentication is required for your 

SMTP server. 

2. RSS Daemon. The file “c:\shakecast\sc\conf\sc.conf” contains an RSS daemon section that 

looks like: 

# RSS Daemon configuration 

<rss> 

AUTOSTART 1 

# the LOG & LOGGING setting only applies to messages logged out of 

# GenericDaemon; other messages from polld itself are controlled by the 

# settings of LogLevel and LogFile in the system-wide configuration above 

LOG c:/shakecast/sc/logs/sc.log 

LOGGING 1 

MSGLEVEL 2 

POLL 60 

PORT 53458 

12
PROMPT rssd> 

SERVICE_NAME rssd 

SERVICE_TITLE ShakeCast RSS Daemon 

SPOLL 10 

REGION SC CI NC NN 

#TIME_WINDOW 30 

</rss> 

Modify the REGION (to download ShakeMaps only from selected regions), the POLL (polling 

interval in seconds), and the TIME_WINDOW (in days for triggering ShakeCast processing). 

Available ShakeMap regions are listed in table 2.1. 

Table 2.1. ShakeMap region code and description 

Region Code Description 

SC Southern California 

CI Southern California 

NC Northern California 

NN Nevada 

UT Utah 

PN Pacific Northwest 

HV Hawaii 

AK Alaska 

GLOBAL Global and U.S. regions not covered by the above networks (NEIC ShakeMap) 

ALL All the above 

3. Restart the ShakeCast Services. To restart the actual services that perform the various 

ShakeCast functions: 

cd c:\shakecast\admin 

stop_sc_services 

start_sc_services 

4. Customize the ShakeCast server for facilities, profiles, users, and notification templates. 

Consult ShakeCast documentation and tutorial videos on the ShakeCast download page in 

configuring ShakeCast server. 

2.4 Uninstalling ShakeCast 

You may uninstall the ShakeCast Server Software by: 

1. Stop and uninstall the services: 

cd c:\shakecast\admin 

stop_sc_services 

remove_sc_services 

13
2. Remove ShakeCast: 

c:\shakecast\Uninstall 

or use Add/Remove Programs in the Control Panel. 

3. If desired, uninstall Perl, PHP, MySQL, and Apache by using Add/Remove Programs in the 

Control Panel. 

2.5 Setup 

Initial setup involves the following steps: (1) populating a database of facility locations and 

types; (2) assigning fragilities using specific ShakeMap metrics (for example, intensity, peak or 

spectral acceleration) and the corresponding likely “green,” “yellow,” and “red” damage states 

(“damage unlikely,” “damage possible,” and “damage likely” thresholds, for example); (3) 

specifying who receives notifications by contact information for facility managers and response 

personnel (email, cell phone); and (4) selecting under which circumstances the alerts are sent (for 

example, “damage possible” at specific facilities). In addition, the user can customize the content of 

the summary report that is delivered internally; for example, a list of facilities based on their likely 

damage state, and organization-specific links and images. 

Example user and earthquake data, tutorials, and documentation are provided with the 

installation package. 

14
3. ShakeCast User Web Interface 

This section describes the User Web Interface of ShakeCast. The User Web Interface is 

called the “ShakeCast Portal” (fig. 3.1) and is used for all interaction with the ShakeCast system, 

such as reviewing ShakeCast damage assessment summary for facilities affected by earthquakes, 

applying for a ShakeCast user account, or signing up for automatic ShakeCast notifications on 

facilities likely affected after earthquakes. 

 The ShakeCast Portal runs on any of the popular Web browsers connected to the Internet, 

 Accesses all processed ShakeMaps for both actual and scenario earthquakes, 

 Displays all pertinent information associated with facilities including facility parameters, 

intensity measures, and damage estimates, 

 Allows management of automatic ShakeCast notifications for both message formats and 

facilities of interest, and 

 Provides access to ShakeCast Web GIS interface. 

 Further, for users with administrative privileges, an additional Administration Panel link 

will also become available. 

Figure 3.1 Default Web page of the ShakeCast Portal. 

15
3.1 System Requirements

The ShakeCast Portal is implemented with common Web technologies, (PHP, Javascript, 

and AJAX, etc.), and is compliant with the HTML 4 specifications. The Portal runs on any 

browser with HTML Strict DTD support, which includes Microsoft’s Internet Explorer 7 and up, as 

well as Firefox. If you do not have one of these browsers, they are available for free download 

from the Microsoft and Mozilla websites. The ShakeCast Portal is supported for Windows 98, 

Windows 2000, Windows XP, Mac OS X, Linux, Sun Solaris, and other UNIX-based operating 

systems. 

If operated from behind a firewall or proxy server, the ShakeCast Portal will operate 

properly only if the firewall allows HTTP requests to Port 80. If the Portal is repeatedly unable to 

connect to the ShakeCast and Google Map GIS servers, then you should contact your system 

administrator for assistance. The firewall opening request should specify the source IP addresses 

(default earthquake.usgs.gov) allowed to connect to the Portal interface. 

3.2 Log in Procedure 

In order to log in, you must be a registered ShakeCast user. Registering can be 

accomplished by clicking on the Register tab on the ShakeCast Portal front page. See Section 3.11 

for further information on registration. Note that only registered users can modify their personal 

preferences for receiving ShakeCast notifications. 

Logging in requires you to provide a user-id and password. Both user-id and password are 

case sensitive. If you forget your password, click on the “I forgot my password” link and fill in the 

information requested; your new password will be then be emailed to you. 

If the user-id and password are entered correctly, both the Register and Log in links at the 

Portal will be replaced with the Log out link with the user-id indicated. 

3.3 Log out Procedure 

To log out of ShakeCast Portal, you must either click on the Log out link from the Portal, 

which will close your active session with the server but leave the Portal browser open, or close the 

browser window/quit the application, which also will close the active session. 

3.4 Front Page of ShakeCast Portal 

The ShakeCast Portal front page is shown in figure 3.1. The Portal window is partitioned 

into a number of components, each serving a different purpose: 

 Primary navigation links: a horizontal panel located beneath the organization’s logo and 

ShakeCast banner contains several primary navigation links that allow a user to perform 

operations or access additional information. 

 System message: an area between the primary navigation links and the ShakeCast summary 

panel that displays event specific information. A typical system message is a banner 

indicating a scenario earthquake and crucial comments manually entered by an 

administrator. 

 Recently processed earthquake selector: a pull-down menu that allows a user to view the 

ShakeCast summary for recently processed earthquakes. 

 ShakeCast facility/ShakeMap overview: an area in the middle left of the ShakeCast 

summary panel that displays an overview map with both the ShakeMap and facility layers. 

16
 ShakeCast facility summary: an area in the upper right of the ShakeCast summary panel that 

displays the number of facilities evaluated, facility potential damage estimates, and the units 

and the range of ground shaking intensity measures extracted from ShakeMap. 

 ShakeCast event summary: an area in the lower right of the ShakeCast summary panel that 

displays the key source parameters of the earthquake evaluated. The list of parameters 

includes the event ID, ShakeMap version number, magnitude, location, and origin time. 

3.5 Primary Navigation Link Tabs 

The Primary navigation link tabs currently have the following links in a panel on top of the 

ShakeCast Portal. Clicking one will invoke the described operation: 

 Home: directs the browser window back to the default page of the ShakeCast portal. 

 Earthquakes: directs the browser window to the ShakeCast listing of processed ShakeMaps. 

 Search: directs the browser window to the ShakeCast search function for information 

regarding facility inventories and processed ShakeMaps. 

 FAQ: directs the browser window to a list of answers to common problems ShakeCast users 

have encountered. 

 Profile: directs the browser window to allow ShakeCast users to manage personal 

information and notification preferences. 

 Register: directs the browser window to the user registration page that allows a non-user to 

sign-up for an account. 

 Administration Panel: directs the browser window to the restricted section for system 

maintenance and management. This feature is only visible and available to ShakeCast users 

with administrative privileges. 

 Log In/Log Out: the Log In link appears when a user first accesses the page without signing 

in. It directs the browser window to allow a user to enter information of username and 

password or to retrieve a lost password. The Log Out link terminates the current Log In 

session and redirects the browser window to the default portal page. 

3.6 Listing of the ShakeCast Summary for Earthquakes 

The ShakeCast summary of affected facilities for earthquakes is accessed via the 

Earthquake link (fig. 3.2). This feature allows a ShakeCast user to view facility damage assessment 

for past earthquakes. The list of processed earthquakes is divided into three categories: (1) Latest 

Earthquake, (2) Earthquake Archive, and (3) Scenario earthquakes. 

17
Figure 3.2 The Earthquake page listing the events processed by the ShakeCast system and 

the number of evaluated facilities in reverse chronological order. 

 Latest Earthquake: displays a table listing all versions of published ShakeMaps for the most 

recently processed earthquake. As a common earthquake refining process, the source 

parameters for a significant earthquake and associated ground motion estimates are 

constantly updated as more information becomes available. The ShakeCast system tracks 

version changes of ShakeMap for an earthquake and re-evaluates facility damage 

assessments accordingly. 

 Earthquake Archive: displays a table listing previously processed ShakeMaps for actual 

earthquakes and their facility damage assessment. 

 Scenarios: displays a table listing previously processed scenario ShakeMaps and their 

facility damage assessment. ShakeCast scenarios also include converted actual ShakeMaps 

for the purpose of local testing. 

 All columns can be sorted by selecting their respective headers. 

3.7 ShakeCast Facility Damage Assessment 

The ShakeCast facility damage assessment view is the center piece of the Web portal. 

ShakeCast users interact with the view in either table or map mode. 

18
 Table mode: displays facility damage assessment in a number of paged tables connected 

with navigation links (fig. 3.3). Each row of the table represents a ShakeCast damage 

assessment for one facility. It consists of facility information, damage state estimate, and 

ground motion estimates at the location of the facility. To view the facility on a map, click 

the facility row to enable the mapping inset. The mapping inset is a floating pane that can 

be dragged on top of the earthquake table page. To disable the inset, click on the “Close” 

button on the upper-right corner of the mapping inset. 

Figure 3.3 The Event page displaying in table mode. Facilities with damage estimates are 

listed in paged tables with navigation links. Each row of the table represents one facility 

and contains information regarding facility description, damage estimate, and ground 

shaking estimates for the site for all available metrics. 

 Map mode: displays facility damage assessment via a Web based mapping interface (fig. 

3.4), currently the Google Maps interface. Facilities are presented in both images and list 

items with facility-type filtering. The facility markers within the mapping area become 

visible at proper zoom level and are color-coded corresponding to damage estimates. To 

view the ground motion measures of a facility, click the facility marker in the mapping area 

to display the parametric values. 

19
Figure 3.4 The Event page displaying in map mode. The map display is divided into three regions: 

(1) facility type selector located on top of the display and used to turn on/off facilities of certain type; 

(2) facility list panel to the right of the display showing a list of facilities located within the mapping 

area with color-coded damage estimates; and (3) the interactive mapping area displaying the facility 

locations with the ShakeMap image overlay. The facility markers are in color-coded damage levels 

and users can pan, zoom, and click on the facilities to reveal shaking parameters. 

3.8 Search Facilities 

The search function shown in figure 3.5 is designed to retrieve facility information inside 

the ShakeCast database. The search result contains facility information, fragility settings including 

metrics and ranges of threshold, and damage estimates from all previously processed ShakeMaps. 

20
Figure 3.5 The search result of a facility displaying parameters for the facility and the 

history of damage estimates from previous earthquakes. 

3.9 Frequently Asked Questions (FAQ)

The FAQ page is intended to answer some of the more commonly asked questions. Users 

should contact the ShakeCast administrator for further questions and bug reports. 

3.10 User Profile Management 

ShakeCast users manage their registered information, delivery methods for notifications, 

and notification profiles from the Profile page. This page view consists of three editing panels: (1) 

General Settings; (2) Email List; and (3) Notification Profiles. 

 General Settings: displays the password and contact information editable by the user (fig. 

3.6). The new password will take effect after the current active session is closed, either by 

closing the browser window or by logging out of the ShakeCast system. 

 

21
Figure 3.6 The General Settings page displaying editable information for a registered 

ShakeCast user. The user can use this form to update his/her password and contact 

information. 

 Email List: displays an editable list of addresses that the ShakeCast user registered with the 

system (fig. 3.7). A user can register up to three different addresses for receiving contentrich HTML notification messages, plain text email notifications, or short text paging 

messages. The default email address will be used for receiving ShakeCast notifications if 

no custom addresses are specified in this panel. All newly registered delivery addresses are 

activated by either the user or system administrator. User activation is completed by 

clicking on an activation link in the confirmation message sent to the new delivery address. 

Before a delivery address is activated, a lock symbol will appear in the panel and no 

ShakeCast notifications will be delivered to that address. 

 

22
Figure 3.7 The Delivery Methods page displaying user defined email addresses for 

receiving ShakeCast notification. All new delivery addresses require activation before they 

can be used to receive notifications. 

 Notification Profiles: displays a list of selectable notification profiles that are available to 

the user (fig. 3.8). To add a profile to a user’s notification preference, click on the profile to 

highlight the selection. The coverage area will be shown in the map area. Uncheck a 

profile from the list to remove it from a user’s preference. At the end of profile selections, 

the user will need to click on the button “Update Notification Profiles” to submit the 

changes to the ShakeCast database. 

 

23
Figure 3.8 The Notification Profiles page displaying a list of predefined notification profiles 

to the user. A user can subscribe or unsubscribe a profile by checking and unchecking the 

profile in the table. Changes will take effect after the user submits the form. 

3.11 User Registration 

By default, a ShakeCast system is preconfigured with restricted access to registered users. 

The registration process is typically a two step process. In the first step a new user submits contact 

information to sign up for a new account as shown in figure 3.9 and will receive a confirmation 

email message for the submitted request. After the ShakeCast administrator receives and approves 

the request, the user will receive a second approval email message. To activate the account and to 

log in for the first time, click on the link provided inside the approval message. If a user account is 

created by an administrator, the new user will simply receive one confirmation email message for 

account activation. 

24
Figure 3.9 The Registration page displaying a form in which the prospective user submits 

contact information for review. Depending on system configuration, the user will receive 

one confirmation message for submittal and another for account activation. 

25
4. ShakeCast Administrator Web Interface 

This section describes the Administrator Web Interface of ShakeCast. The ShakeCast 

interface is designed for an administrator to perform common tasks ranging from management of 

both facility and user inventory to system wide maintenance and configuration. Access to the 

administrative page is restricted to ShakeCast users with administrative privileges. The range of 

tasks that can be performed from the interface includes: (1) earthquake/ShakeMap management; (2) 

system configuration; (3) facility management; (4) notification/profile management; and (5) user 

account and notification management. 

The administrative page view displays a list of system management tasks in the left panel 

and the work area of the selected task in the right panel. Figure 4.1 shows the default page view 

when the page is first accessed. The right panel shows the current status of the ShakeCast system: 

(1) network connection with the upstream USGS server for ShakeMap RSS data feed; (2) system 

services and summary of process logs; (3) latest processed ShakeMap and notifications; and (4) 

code version of the current system and available script updates. For each of the first three server 

system functions, there is a color indicator in either green or red that reflects the status of the 

function. 

Figure 4.1 Default Web page of the ShakeCast administration interface. 

26
Depending on the level of user privilege the ShakeCast system is configured, the 

administrator may or may not be able to perform all ShakeCast functions from the administrator 

Web interface. These limitations apply specifically to ShakeCast functions that require administer 

privileges on the local operating system. The ShakeCast administrator Web interface does not 

cover management for system level services and supporting software. There are currently five 

ShakeCast daemon services (dispatch, polling, RSS, notify queue, notify processes) and their 

configuration files that require direct access to the operating system. In addition to the ShakeCast 

system services, the same restriction also applies to supporting software including the Apache Web 

server and MySQL database applications. An administrator will need to log on to the server system 

where the ShakeCast system resides to make changes to the configuration files of applications and 

to start and stop ShakeCast system processes and supporting software. 

4.1 General Administration 

The general administration section allows a ShakeCast administrator to manage system 

wide tasks in six different categories: (1) Backup Database; (2) General Configuration; (3) Log 

Viewer; (4) Mass Email; (5) Restore Database; (6) ShakeMap Server; (7) System Service; (8) Task 

Repeater; and( 9) Template. 

4.1.1 Backup Database 

This page allows an administrator to perform backup of the ShakeCast database, consisting 

of 70 tables. The backup options can be a combination of table structure and data as shown in 

figure 4.2. The output format is a single file in either plain text or compressed format. The backup 

copy can be used to restore the system database using the ‘Restore Database’ function described 

later. 

Figure 4.2 The database backup page has three backup options: full, structure-only, or 

data-only. After submitting the form, the administrator can specify the filename and 

location of the database backup file. 

4.1.2 General Configuration 

This page displays a list of configurable options of the system. These options include 

configurations of system identity and user page, session management, and external SMTP server. 

27
System identity. The hostname and port fields describe the URL that a ShakeCast user will 

use to access the system (fig. 4.3). Each hostname requires a unique API key from the Google 

Maps server. User-related settings include account activation, access control, and Web page style. 

 

Figure 4.3 The general configuration page handleing system-wide options regarding 

system identity and policy settings. 

Cookie settings. ShakeCast implements session control via a cookie stored on the user’s 

Web browser during log-in. The administrator can use this setting (fig. 4.4) to configure the time 

period for each successful log-in. 

Figure 4.4 The cookie settings determining the time window for persistent log-in and 

system identification on the remote system. 

28
Email settings. This form contains information on the Email server (fig. 4.5) that the 

ShakeCast system or administrator uses to send email to the end users. This configuration also 

updates the settings of SMTP server information in “sc.conf” that the ShakeCast system uses to 

send email notifications. A utility script “sync_conf.pl” is included for synchronization of 

configuration settings. 

 

Figure 4.5 The Email Settings Block holding information of the email server for all email 

messages sent from the administrative interface. 

4.1.3 Log Viewer 

Figure 4.6 displays a list of log files that are available for viewing inside the ShakeCast log 

directory. The log directory is configurable under the System Service link described later in this 

section. Each log file row contains information regarding the filename, file size, and other 

ShakeCast services that are related to the log file. The only available function for a log file is 

View. 

Figure 4.6 The ShakeCast Log File Viewer page listing available log files for viewing. 

The administrator can click on the View link to review the content of the selected log file 

(fig. 4.7). By default, up to 500 most recent entries of the selected log file will be displayed in the 

view pane in ascending order. There are three viewing options on the bottom of the view pane for 

fine-tuning the listing order of log entries, filtering of ShakeCast services, and changing the number 

of displayed log entries. 

29
Figure 4.7 The ShakeCast Log File Viewer page for a selected log file. Selectable viewing 

options are located at the bottom of the view pane and consist of three options: Reverse 

Listing, Service Filter, and # Lines. 

4.1.4 Mass Email 

This page displays a form (Figure 4.8) for the administrator to compose an email message 

for delivery to the registered users. 

30
Figure 4.8 The email form page for composing an email message. 

4.1.5 Restore Database 

This page displays a dialog for the administrator to upload a backup file of the database as 

shown in figure 4.9. The database backup file can be generated from the ShakeCast backup 

function or from common database dumping utilities. This process will overwrite any existing data 

in the current system. 

Figure 4.9 The Database Restore page. The source of backup file can be from previous 

backup operations or in a standard MySQL dump file. 

4.1.6 ShakeMap Server 

This page displays a list of trusted servers in which ShakeMap products reside (fig. 4.10); 

this list also includes the ShakeCast system itself. The ShakeCast system comes preconfigured 

with three default servers that should not be removed: 

1. Server ID 1 contains the hostname that is allowed for injecting ShakeMap products into the 

current ShakeCast system. The default setting is “localhost.” Any changes to this server should 

also be applied to the “sc.conf” file. 

2. Server ID 1000 is the ID of the current ShakeCast system. The default setting is “localhost” and 

should be changed to the hostname of the system on which the ShakeCast is installed. 

31
3. Server ID 1302 is the upstream USGS Web server that hosts ShakeMap products for real time 

notifications. The USGS Web server consists of a cluster of servers, and the content of each server 

is cached by a commercial vender (Alkamai) for the purpose of rapid dissemination of information 

and robustness. 

The new ShakeCast system also supports the server-client configuration of the original 

ShakeCast system. The administrator can consult documentation of Version 1 for details. 

Available functions for each server are Edit, Delete, and Password. 

Figure 4.10 The ShakeCast Server Administration page listing available servers and their 

current status. The system comes with three default server settings and should not be 

altered. 

Edit. The server form (fig. 4.11) contains server related information including identification 

and permitted functions. 

 

Figure 4.11 The Server Settings page for adding and editing servers to the ShakeCast 

database. 

Delete. Remove information on the server entry from the database. 

Password. Configure a password for accessing the designated server as shown in figure 

4.12. Neither Server ID 1000 (local system) nor 1302 (USGS Web server) require a password for 

access. The system has a preconfigured password for incoming password for Server ID 1 (injection 

system). Any changes to the incoming password for a server will update the password file “scservers” for authentication by the Apache Web server. 

32
Figure 4.12 The Server Password Configuration page. It is reserved primarily for 

backward compatibility with the Version 1 ShakeCast system. 

4.1.7 System Service 

This page displays a list of configurable options for the system that dictates the behaviors of 

both ShakeCast system services and command line utilities. Changes of system service settings 

will be carried over to the plain file equivalent “sc.conf” file under the ShakeCast configuration 

directory. The only exception is the access and authentication information for the ShakeCast 

database, which is kept solely in the “sc.conf” file. It is recommended to restart ShakeCast services 

to force reload of configurations on changes specific to the system services. 

Warning: Misconfigured system options will result in failed ShakeCast system services and 

utilities. 

General system service settings. Figure 4.13 shows systemwide configurations for the 

ShakeCast installation. These options include directories for ShakeCast root, data, notification 

template, log file, etc. Additional run-time information includes logging level, and user and group 

ID, if applicable. Each hostname requires a unique API key from the Google Maps server. The 

“Threshold” field is a new option that only applies to system version 2.0.1 and later. It is an option 

to trigger ShakeCast processes for ShakeMap updates only if changes of ground motion measures 

exceed the specified threshold in percentage ratio. The “Threshold” option is disabled if the field is 

left blank. 

 

33
Figure 4.13 The General System Service Settings page handling system-wide options 

regarding all ShakeCast system services and command line utilities. 

Local injection server settings. The form (fig. 4.14) contains information on the local 

server for injecting ShakeMaps into the database and triggering ShakeCast processes. Changes to 

the settings of the local injection server are usually not needed. 

Figure 4.14 The Local Injection Server Settings determining the destination server and 

authentication information on the remote system. 

Web server access control. This form contains information of the Apache Web server (fig. 

4.15) which the ShakeCast system or administrator uses to generate password entries for access 

control. By default, the ShakeCast system is preconfigured with access control for server-to-server 

communications (including the default local server). User authentication is by default handled by 

the portal page. To enable or disable the access control settings, the administrator will need to edit 

the Apache configuration file directly. 

 

34
Figure 4.15 The Web Server Access Control holding information of the Apache Web server 

for access control. 

Dispatcher service. This form contains information of the ShakeCast Dispatcher Service 

(fig. 4.16). The Dispatcher Service is a background process that manages worker processes for 

both incoming and outgoing service requests. 

 

Figure 4.16 The Dispatcher Service holding information of the ShakeCast Dispatcher 

process. 

Polling service. This form contains information of the ShakeCast Polling Service (fig. 

4.17). The Polling Service is a background process that routinely polls ShakeMap information 

from remote ShakeCast servers specified in the “ShakeMap Server” block described earlier in this 

section. 

 

35
Figure 4.17 The Polling Service holding information of the ShakeCast Polling process. 

Notification queuing service. This form contains information of the ShakeCast Notification 

Queuing Service (fig. 4.18). The Notification Queuing Service is primarily a background process 

but can be invoked from the command line. The process scans the database at the specified Scan 

Period (in seconds) for new ShakeMaps and creates notification queues based on the notification 

requests stored in the database. 

 

Figure 4.18 The Notification Queuing Service holding information of the ShakeCast 

Notification Queuing process. 

Notification service. This form contains information of the ShakeCast Notification Service 

(fig. 4.19). Like the Notification Queuing Service, the Notification Service is primarily a 

background process but can be invoked from the command line. The process scans the database at 

the specified Scan Period (in seconds) for new notification queues then assembles and delivers 

notifications to users who subscribe to ShakeCast notifications. 

 

36
Figure 4.19 The Notification Service holding information of the ShakeCast Notification 

process. 

RSS service. This form contains information of the ShakeCast RSS Service (fig.e 4.20). 

The RSS Service is a background process that routinely polls ShakeMap information from the 

USGS Web Server specified in the “ShakeMap Server” block described earlier this section. In 

addition to daemon specific information, the administrator can configure the service in the field 

“ShakeMap Originator Region” to retrieve region specific ShakeMaps. Table 2.1 lists available 

network codes for ShakeMaps. The field “Earthquake Time Window” is an optional filter that 

excludes ShakeMaps from being processed if the origin time of the event falls outside the active 

time window (in days). 

 

Figure 4.20 The RSS Service holding information of the ShakeCast RSS process. 

Notification SMTP settings. This form contains information of the email server (fig. 4.21) 

that the ShakeCast system services use to send email to the end users. A utility script 

“sync_conf.pl” is included for synchronization of configuration settings. 

 

37
Figure 4.21 The Notification SMTP Settings Service holding information of the email server 

for all email messages sent by the ShakeCast system services. 

Logrotate and logstats settings. This form contains information of both the logrotate and 

logstats ShakeCast utilities (fig. 4.22). Both command line utilities are ShakeCast add-ons and do 

not interfere with the core system services. The administrator can invoke the utilities from the 

DOS Window command line, the ShakeCast administrator default page, or the “Task Repeater” 

page (described next) as a scheduled task. 

 

Figure 4.22 The Logrotate and Logstats Settings holding information of both the logrotate 

and logstats ShakeCast utilities. 

4.1.8 Task Repeater 

Figure 4.23 displays a list of scheduled tasks on the local ShakeCast system. The Task 

Repeater page converts a ShakeCast task request into a Windows Scheduled Task via the system 

function “schtasks.” Thus, in order to schedule a ShakeCast task, the administrator will need both 

the username and password on which the ShakeCast software is installed. The available functions 

for the page are Run, Delete, and Add. 

38
Figure 4.23 The ShakeCast Task Repeater page listing scheduled tasks on the local system 

and their run-time information. 

Run. Execute the selected task immediately. 

Delete. Remove the selected task from the local system. 

Add. The editable form shown in figure 4.24 allows the ShakeCast administrator to 

schedule new tasks on the local system. Tasks available to schedule include heartbeat, 

logrotate, logstats, shake_fetch, and tester. Only one scheduled task is permitted 

for a unique task type. Additional command line options are needed for both shake_fetch and 

tester tasks. See Section 6.9 on required parameters for shake_fetch and Section 6.11 for 

tester. 

Figure 4.24 The Task Repeater Add page. The administrator can create scheduled tasks 

from five ShakeCast service utilities: heartbeat, logrotate, logstats, shake_fetch, and tester. 

4.1.9 Template 

Figure 4.25 displays a list of configurable notification templates that are available for the 

system. The templates are categorized in six different notification types, and each notification type 

consists of five different delivery methods—a total of 30 template variations. The six notification 

types are “Cancel Event,” “New Event,” “Updated Event,” “New Product,” “Facility Shaken,” and 

39
“Facility Damage.” The five different delivery methods are “Pager”, “HTML Email”, “Text 

Email”, “Voice”, and “Script.” In addition to the default template, the administrator can create 

custom templates for any template variant. Each defined template is divided into three sections, the 

header, body, and footer, and files reside in the “templates” directory. This configuration does not 

apply to the ShakeCast Web pages. The available functions for each defined template are: View, 

Edit, and Delete. 

Figure 4.25 The ShakeCast Template Administration page listing available templates for 

sending notifications. 

View. Show the content of the selected template (fig. 4.26). 

40
Figure 4.26 The ShakeCast Template Preview page. Each template file consists of three 

segment files: the header, body, and footer. It displays the layout and keywords embedded 

in the template file after joining the three individual segments. 

Edit. The editable form shown in figure 4.27 allows the ShakeCast administrator to 

create/edit both existing and new templates. A template variant only allows for one “default” 

template. Custom templates can be created by giving the template a new template name and 

filename other than “default.” 

Delete. Remove information on the template entry from the database and the local file 

system. 

41
Figure 4.27 The ShakeCast Template Edit page. The administrator can copy and paste a 

custom design into the editable box for each segment. If given a custom template name 

other than “default,” the system will create custom template files based on the given 

template name and register them in the database. 

4.2 Event Administration 

The Event Administration section allows a ShakeCast administrator to manage ShakeMap 

events in three different categories: (1) processed ShakeMap events; (2) ShakeCast test events; and 

(3) additional ShakeMap inventory on the USGS Web site. 

4.2.1 Processed Event 

This page displays a list of both actual and scenario ShakeMaps (fig. 4.28) that have been 

processed by ShakeCast and are present in the database. Available functions for each processed 

event are Re-Alert, Comment, and Delete. 

Re-Alert. The Re-Alert function triggers the ShakeCast notification process to re-send 

notifications to ShakeCast users who were on the recipient list. The list of recipients and facilities 

is based on the time the event was processed. 

42
Figure 4.28 The Processed Event List page listing all previously processed ShakeMaps for 

the local system. From here the administrator can view, re-alert, comment, or delete any 

processed ShakeMap events. 

Comment. The Comment function (fig. 4.29) allows a ShakeCast administrator to attach 

additional information to a processed event, via email notification and (or) Web posting. The target 

of email comment only applies to the list of recipients who received ShakeCast notifications for the 

specified event. 

43
Figure 4.29 The Event Comment page allowing the administrator to add additional 

information for the specified event for ShakeCast users whom are the recipients of 

notifications and/or on the ShakeCast portal page for the event. 

Delete. The Delete function removes all processed information for the specified event 

including event information, metrics, and notifications from the database. This function is typically 

used to remove unwanted events from the database and to reprocess selected ShakeCast events. 

This function does not remove ShakeMap products from the ShakeCast download directory. 

4.2.2 Test Event 

This page displays a list of processed ShakeMaps that are available for the purpose of local 

testing (fig. 4.30). To trigger a test event, click on the links in the Action column to simulate either 

a new or an updated event. Notifications generated from test events are sent to ShakeCast users 

whose notification profiles are configured to also receive test events. To add a processed 

ShakeCast event to the test event list, click on the “Add new test event” button on the bottom of the 

page and select an event from a list of processed ShakeCast events. To remove a test event, delete 

the event from the ShakeCast test event directory on the local file system. 

44
Figure 4.30 The ShakeCast Test Event List page listing available test events residing on the 

local system. From this interface, an administrator can trigger a local test event or convert 

a processed ShakeMap into a test event. 

4.2.3 USGS ShakeMap 

This interface retrieves a list of both actual and scenario ShakeMaps from the USGS Web 

site that are available for download and process as shown in figure 4.31. The two available options 

for a ShakeMap event are Download Only and Inject. The Download Only function retrieves all 

available products for a ShakeMap and stores them in the ShakeCast data directory on the server 

system. The Inject function performs the same Download Only function plus an additional 

ShakeCast process for the ShakeMap event, as for the real-time RSS system process. The Inject

function is different from the RSS process in that it is not restricted to the ShakeMap region 

directive of the RSS process and that it can also process scenario ShakeMaps. The ShakeCast 

administrator should use the Inject function with caution since the process treats actual USGS 

ShakeMaps as real events. 

 

45
Figure 4.31 The USGS ShakeMap page listing available ShakeMaps on the USGS Web 

server for both actual and scenario events. From this interface the administrator can 

download and inject the ShakeMap directly into the local ShakeCast system. This function 

overwrites the REGION directive in the system configuration and will process ShakeMaps 

for actual events as real events. It will skip events that have already been processed. 

4.3 Facility Administration 

The Facility Administration section handles facility-specific interaction with the 

ShakeCast system. This management section is divided into five categories: (1) Damage Level; (2) 

Facility Type; (3) Facility Management; (4) Supplemental Attributes; and (5) Upload. Changes 

made in the four categories have different scopes of influence. The Damage Level settings apply 

to all facilities in the ShakeCast database. Settings for both Facility Type and Supplemental 

Attributes are defined for specific structure types. Finally, Facility Management allows 

management of facility-specific information. It is worth noting that any changes made to Damage 

Level and Facility Type will not affect corresponding settings for existing facilities inside the 

database and will only apply to new facilities. In addition to manual editing of facility settings, the 

administrator can use the “manage_facility.pl” tool to refresh settings of all facilities via batch 

processing. 

4.3.1 Damage Level 

This page displays a list of available damage state descriptions for facilities (fig. 4.32). The 

ShakeCast system is preconfigured with a four-level damage classification. The number of damage 

levels is flexible and the ShakeCast administrator can create additional damage states for custom 

needs. Although defined damage levels are available to all facilities for damage assessment, it is 

not necessary to specify the range of ground intensity measures for all damage levels for a given 

46
facility. Unspecified damage levels of a facility will simply not be used to measure the damage 

state for the facility. 

Figure 4.32 The Damage Level Administration page listing defined damage levels on the 

local server. The ShakeCast system has prebuilt four damage level settings that match the 

HAZUS damage level settings. If custom damage levels are added to the system, the 

administrator should recheck the integrity of the default fragility settings for existing 

facilities. 

4.3.2 Facility Type 

This page displays a list of available definitions for structure types of facilities (fig. 4.33). 

Each facility type includes a set of optional fields of default fragility settings. The ShakeCast 

system comes with default fragility settings for 128 choices of HAZUS model building type and 

code era (see the document “HAZUS Damage Level” for detailed definitions). The database also 

contains definitions of common geotechnical structures, but includes no fragility settings. 

ShakeCast users can define custom structure types for their facilities. To define damage states for a 

given facility type as shown in figure 4.34, the ShakeCast administrator will need to provide the 

range of high and low values of the described damage level and the metric of ground intensity 

measure. 

47
Figure 4.33 The Facility Type Administration page of the ShakeCast administration 

interface. The ShakeCast comes with more than 150 predefined common facility types. 

Custom defined facility types can be added from this interface. 

Figure 4.34 The Facility Type Editing page. ShakeCast comes with default fragility settings 

for common building types, code level, and code era. Custom fragility settings can be 

added via the facility type editing page. 

4.3.3 Management 

This page displays a list of user-defined facilities populated in the ShakeCast database (fig. 

4.35). From this view the administrator can create new facilities and manage information of 

48
existing ones. When updating the facility inventory, the administrator can also remove the system 

cache of facility image tiles by checking the “Clear Cache” checkbox. The button Export Facility

will convert the current facility inventory into a standard CSV formatted text files including 

fragility settings and facility specific attributes. The format of the file is described in detail in 

Section 6.5. An exported facility file can be imported back to the ShakeCast database via either the 

Upload function (described later this section) or the command line utility “manage_facility.pl” (see 

Section 6.5). 

Required fields for a user-defined facility include facility name, facility type, and location 

in latitude and longitude (fig. 4.36). Facility location can be either a point location or a rectangular 

area. Fragility settings for a facility are needed for damage estimates. Custom fragility settings for 

a facility, either in values and (or) choices of metric, will override the default settings for the given 

facility type. For ShakeCast systems with large inventories of facilities, the administrator can use 

either the Upload function or the system utility “manage_facility.pl” to populate new facilities and 

to update/remove existing ones. 

Figure 4.35 The Facility Administration page displaying a list of user-defined facilities on 

the local system. Available options for facility management are Add, Edit, or Delete. 

49
Figure 4.36 The Facility Editing page displaying a form containing facility-specific 

information and optional fragility-setting information, either default or custom values. 

4.3.4 Supplemental Attribute 

This page displays a list of defined attributes associated with structure types. The 

supplemental attribute block is a free-form field and multiple fields are permitted. It is designed to 

store specific information for facility types that are not commonly shared among facilities. 

4.3.5 Upload 

This page displays a dialog for the administrator to upload a facility file into the database as 

shown in figure 4.37. A facility file can be generated from the ShakeCast facility export function 

or from common spreadsheet applications such as Excel. This interface uses the “manage_facility” 

utility to process uploaded facility data. Available process options are Replace, Insert, 

Delete, Update, and Skip. Detailed descriptions of these options and input file formats are 

included in Section 6.5. 

50
Figure 4.37 The Facility Upload page. The source of facility file can be from a previously 

exported facility file or in a standard facility CSV file. This interface uses the 

“manage_facility” utility to process uploaded facility data. Available process options are 

Replace, Insert, Delete, Update, and Skip. 

4.4 Profile Administration 

A ShakeCast profile can be viewed as a pseudo user who represents a group of users with 

shared notification requests but different delivery methods. ShakeCast notification profiles are 

optional for setting up notification for systems with relatively small facility inventory or with a 

number of users. For larger systems, notification profiles provide an efficient method to limit the 

growth of the database and to maintain performance of notification processing by aggregating 

common notifications. 

The profile administration section handles management of profiles with respect to both 

facilities and notification requests. This management section is divided into three categories: (1) 

management of profile geometry polygons for facility association; (2) notification request for 

profile; and (3) upload of profiles. As for facility management, there is a command line counterpart 

of the Web interface, “manage_profile.pl.” For systems with large inventory, the administrator can 

use the “manage_profile.pl” tool to refresh settings of all profiles via batch processing. 

51
Figure 4.38 The Profile Administration page listing defined profiles on the local system that 

are available to the ShakeCast users for subscription. 

4.4.1 Management 

This page displays a list of defined profiles to which a user can subscribe for notification 

requests (fig. 4.38). Each profile consists of a geometric polygon outlining the region of interest 

and a set of notification requests for the enclosed facilities. The administrator defines the polygon 

via the interactive map and with the additional options for selecting rectangular and circular regions 

(fig. 4.39). Upon submitting the form, a list of facilities enclosed by the geometric boundaries will 

be assigned to the profile. The list of facilities for a profile is not restricted to the facilities enclosed 

inside the polygon and can be edited later. 

Figure 4.39 The profile polygon page displaying a Google Maps-based GIS interface of a 

defined polygon for the profile. The administrator can modify the boundaries of the polygon 

or switch to other geometric forms, including rectangular and circular boundaries. 

4.4.2 Notification Request 

This page displays a list of available notification requests configured for each profile (fig. 

4.40). From this view the administrator can select a profile and edit or remove its notifications. 

52
Figure 4.40 The Profile Notification Request Administration summary page listing available 

profiles and their notification request settings. The administrator can edit or delete 

notification request settings associated with a profile from this interface. 

When creating a notification request, there are six different notification types to choose 

from as shown in Figure 4.41. The notification types include “New Event,” “Cancel Event,” 

“Update Event,” “New Product,” “Facility Shaken,” and “Facility Damage.” It is permitted to 

define more than one notification request of the same type for a profile. Multiple notification 

requests can be aggregated into groups as a combined message during the dissemination of 

notifications, based on users’ requests. 

Figure 4.41 The Notification Request summary page listing defined notification request 

settings for a profile. The administrator can add, edit or delete specific notification request 

settings. Facility-based notification requests will affect all facilities enclosed by the profile 

polygon. 

Inside the Notification Request summary view, the available functions are Add, Edit, 

Delete, and Facility selection. To add a new request, use the drop-down menu on the lower left 

corner of the form to create and configure the request (fig. 4.42). The Delete function removes the 

selected notification request from the database. 

53
All notification request types require information of notification type, event type, and 

delivery method. For “New Product” type, an additional field of product type is needed. For 

“Facility Damage” type, the additional required field is damage level. For “Facility Shaken” type, 

the administrator needs to specify both the metric and the limit value of shaking threshold. 

Figure 4.42 The Notification Request editing page displaying a configurable form for the 

specified request type. Available notification request types are: “New Event,” “Cancel 

Event,” “Update Event,” “New Product,” “Facility Shaken,” and “Facility Damage.” 

To fine tune the list of facilities for a profile, the administrator can click on the facility link 

inside the Notification Request summary page (fig. 4.43). The profile-facility association view is 

a set of paged tables with included facilities marked by check marks. The administrator can switch 

between the subscribed list and the full list of facilities to add and remove facilities from the list. 

The facility inventory is updated for the profile after the administrator submits the changes. 

54
Figure 4.43 The profile-facility association page displaying a list of facilities included in the 

profile. The administrator can toggle between the profile and master facility list to fine tune 

the list by adding or removing facilities from the interface. 

4.4.3 Upload 

This page displays a dialog for the administrator to upload a profile file into the database as 

shown in Figure 4.44. This interface uses the “manage_profile” utility to process uploaded profile 

data. Available process options are Replace/Update, Insert, and Delete. Detailed 

descriptions of these options and input file formats are included in Section 6.6. 

Figure 4.44 The Profile Upload page. This interface uses the “manage_profile” utility to 

process uploaded profile data. Available process options are Replace/Update, Insert, and 

Delete. 

55
4.5 User Administration 

The user administration section handles tasks of user-specific interactions with the 

ShakeCast system. Depending on the system configuration, creation of a new user account and 

notification requests can be initiated by either the end-user or the administrator. Upon a user’s 

request for a new account, the administrator can usually approve or deny the request by responding 

to the email message sent by the ShakeCast system. This management view allows the 

administrator to review settings of all user accounts and overwrite any existing settings. The 

section is divided into four categories: (1) Management; (2) Notification Request; (3) Replication; 

and (4) Upload. Batch processing for a large number of user accounts and settings of notification 

requests is available via the ShakeCast utility “manage_user.pl.” 

4.5.1 Management 

This page displays a list of users stored inside the ShakeCast database (fig. 4.45). In 

addition to the basic user information, the table also shows the user privilege and user status. A 

“Suspended” user status indicates that the user account exists in the database but the user can 

neither logon nor receive notifications. To remove a user permanently from the database, the 

administrator should use the Delete function from within this view. There are three available 

functions for the Management view: Add, Edit, and Delete. The Delete function removes all 

information including user data, notification requests, and previous notifications for the selected 

user from ShakeCast. Both the Add and Edit functions share the same interface as shown in figure 

4.46. The exception is that for Add the administrator needs to provide a unique user name for the 

new user account. 

Figure 4.45 The User Administration Summary page displaying a list of ShakeCast users 

including their privileges and status. The administrator can add, edit, or delete users from 

this interface. 

The user account form consists of four sections regarding information for user log-in, user 

profile, delivery addresses, and special fields. The user can update information for the first three 

sections from the user accessible account management page. The administrator-only fields allow 

both suspension and removal of any user account, including an administrator. The administrator 

56
can also use this form to modify user privileges. It is advisable to limit the number of users with 

administrative privilege. 

Figure 4.46 The User Administration Data Editing page displaying a form of editable fields 

containing contact information, notification preferences, and user status for the specified 

user. 

4.5.2 Notification Request 

This function works the same as the Notification Request view for profile management (fig. 

4.40). Changes of notification request settings only apply to the selected user and any user-profile 

association will be nullified. 

4.5.3 Replication 

This page displays a form with two drop-down lists for both the source and destination for 

the replication process (fig. 4.47). The ShakeCast replication function allows the administrator to 

duplicate notification requests of a selected profile or user to a group of users. For better 

performance of system notifications immediately after earthquakes, the administrator can create a 

profile for users who share common notification requests. By assigning the user group to a single 

57
profile, the administrator can effectively reduces the processing time and the table size of the 

notification queue. User replication may be used to produce a template of notification requests for 

particular users for further customization. 

Figure 4.47 The User/Profile Replication Administration page displaying two panels for 

both source and destination of the replication process. The administrator can toggle 

between user and profile as the source of replication. 

4.5.4 Upload 

This page displays a dialog for the administrator to upload a user file into the database as 

shown in figure 4.48. This interface uses the “manage_user” utility to process uploaded user data. 

Available process options are Replace, Insert, Delete, Update, and Skip. Detailed 

descriptions of these options and input file formats are included in Section 6.7. 

Figure 4.48 The User Upload page. This interface uses the “manage_user” utility to 

process uploaded user data. Available process options are Replace, Insert, Delete, Update, 

and Skip. 

58
4.6 Miscellaneous Administration 

4.6.1 Web Access to ShakeCast System Version 1 

In addition to the standard portal access, the ShakeCast version 2 system also retains the 

Web directories from the previous version for the purpose of both user and server communications. 

Access to these pages is restricted and is authenticated through the Apache Web server. The 

administrator has to edit the files “httpd-sc.conf” and “sc-servers” files to configure user access and 

password changes. To disable the version 1 Web access, edit the ShakeCast Web configuration file 

“httpd-sc.conf” under the “conf” directory by commenting out the “scripts/s” and the “scripts/c” 

sections. 

4.6.2 PMA Access 

The ShakeCast system has preconfigured an optional installation of PHPMyAdmin into the 

“/pma” directory. The application allows the administrator to interact with the database via the 

Web interface. To access the interface, the administrator is required to provide the same username 

and password as for the version 1 Web access and also the username and password to the 

ShakeCast database. To disable the PMA access, edit the ShakeCast Web configuration file “httpdsc.conf” under the “conf” directory by commenting out the “pma” section. 

4.6.3 Database Configuration 

Information regarding access to the ShakeCast database and authentication is stored inside 

the “sc.conf” configuration file under the “conf” directory. The administrator will also need to 

update the “sc.conf” file every time access information to the database is changed. 

4.6.4 Default Center Location 

The default center point for the ShakeCast mapping interface is stored in the file “defaultsc.js” under the “docs” directory and is currently set in California. The administrator can edit the 

content of the file to change the default center location. 

59
5. XML Documents 

This Section documents the ShakeCast XML file formats. Extensible Markup Language 

(XML) is a widely used and easily implemented method of exchanging data between disparate 

computer systems. The ShakeCast System receives ShakeMap information in XML from the 

USGS Web server and uses XML to communicate all kinds of information between ShakeCast 

servers: 

 The ShakeCast software itself and data about ShakeCast Servers, 

 Data about events (earthquakes) and products (data files) available on the network, and 

 Status information that helps the administrators of the ShakeCast servers know if their 

network is running smoothly. 

5.1 ShakeMap RSS Feed XML 

RSS, which stands for “Really Simple Syndication” (sometimes called Rich Site Summary), 

has been adopted by news services, Weblogs, and other online information services to deliver 

content to subscribers. After subscribing to an RSS feed, you will be notified when new content is 

available without having to visit the Web site. The USGS ShakeMap RSS data feed contains the 

following XML: 

<?xml version="1.0"?> 

<?xml-stylesheet href="shake_feed.xsl" type="text/xsl" media="screen"?> 

<rss xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" 

xmlns:dc="http://purl.org/dc/elements/1.1/" 

xmlns:eq="http://earthquake.usgs.gov/rss/1.0/" version="2.0"> 

<channel> 

<title>USGS Earthquake ShakeMaps</title> 

<description>List of ShakeMaps for events in the last 30 

days</description> 

<link>http://earthquake.usgs.gov/</link> 

<dc:publisher>U.S. Geological Survey</dc:publisher> 

<pubDate>Mon, 16 Jul 2007 20:23:29 +0000</pubDate> 

<item> 

<title>6.7 - NEAR THE WEST COAST OF HONSHU, JAPAN</title> 

<description><![CDATA[<img 

src="http://earthquake.usgs.gov/eqcenter/images/thumbs/shakemap_global_200

7ewac.jpg" width="100" style="float:left;" />Date: Mon, 16 Jul 2007 

01:13:27 GMT<br />Lat/Lon: 37.574/138.44<br />Depth: 49<br 

/>]]></description> 

<link>http://earthquake.usgs.gov/eqcenter/shakemap/global/shake/2007ewac/<

/link> 

<pubDate>Mon, 16 Jul 2007 01:13:27 GMT</pubDate> 

<geo:lat>37.574</geo:lat> 

<geo:long>138.44</geo:long> 

<dc:subject>6</dc:subject> 

<eq:seconds>1184598989</eq:seconds> 

<eq:depth>49</eq:depth> 

<eq:region>global</eq:region> 

<eq:shakethumb>http://earthquake.usgs.gov/eqcenter/images/thumbs/shakemap_

global_2007ewac.jpg</eq:shakethumb> 

</item> 

</channel> 

</rss> 

60
5.2 Event XML 

A ShakeCast Event is described by Event XML. A sample Event XML is provided. 

<event event_id="SAF_south7.8_se" event_version="1" 

event_status="RELEASED" event_type="SCENARIO" event_name="" 

event_location_description="SAF-southern M7.8 Scenario" 

event_timestamp="2006-08-03 12:00:00" external_event_id="SAF_south7.8_se" 

magnitude="7.8" lat="33.922270" lon="-116.469670" /> 

5.3 Product XML 

A ShakeCast Product is described by Product XML. A sample Product XML is provided. 

<product shakemap_id="SAF_south7.8_se" shakemap_version="1" 

product_type="HAZUS" product_status="RELEASED" generating_server="1" 

generation_timestamp="2007-02-08 16:07:03" lat_min="32.405603" 

lat_max="35.455603" lon_min="-114.769670" lon_max="-119.353003" /> 

5.4 ShakeMap XML 

A ShakeCast ShakeMap is described by ShakeMap XML. A sample ShakeMap XML is 

provided. 

<shakemap shakemap_id="SAF_south7.8_se" shakemap_version="1" 

event_id="SAF_south7.8_se" event_version="1" shakemap_status="RELEASED" 

generating_server="1" shakemap_region="ci" generation_timestamp="2007-02-

08 16:07:03" begin_timestamp="2007-02-08 16:07:03" end_timestamp="2007-02-

08 16:07:03" lat_min="32.405603" lat_max="35.455603" lon_min="-119.353003" 

lon_max="-114.769670"> 

<metric metric_name="MMI" min_value="9.4900" max_value="10.0000" /> 

<metric metric_name="PGA" min_value="9.9989" max_value="10.0002" /> 

<metric metric_name="PGV" min_value="10.0000" max_value="99.9109" /> 

<metric metric_name="PSA03" min_value="10.0005" max_value="99.9687" /> 

<metric metric_name="PSA10" min_value="10.0007" max_value="99.9747" /> 

<metric metric_name="PSA30" min_value="1.7880" max_value="9.9989" /> 

</shakemap> 

5.5 Exposure XML 

A ShakeCast Exposure is described by Exposure XML. A sample Exposure XML is 

provided. 

<?xml version="1.0" encoding="UTF-8"?> 

<exposure> 

 xmlns:xlink="http://www.w3.org/1999/xlink" 

 

 code_version="Pager 0.2.0" 

 event_id="usneb6_06" 

 version="1" 

 timestamp="2006-10-11T16:07:03Z" 

61
 source="us" 

 status="RELEASED"> 

 

 <event 

 type="ACTUAL" 

 id="urn:earthquake.usgs.gov:origin:usneb6_06:1" 

 magnitude="6.3" 

 depth="17.1" 

 latitude="-7.955000" 

 longitude="110.430000" 

 timestamp="2006-05-26T22:54:01GMT" 

 description="JAVA, INDONESIA" /> 

 

 <shakemap 

 code_version="3.1.1 GSM" 

 id="urn:earthquake.usgs.gov:shakemap:usneb6_06:6" 

 version="6" 

 timestamp="2006-10-11T16:07:03Z" 

 source="us" 

 status="RELEASED" /> 

 <summary type="MMI" units="mmi"> 

 <bin label="I" value="1" range="[.5,1.5)" 

keywords="incomplete"> 

 <measure type="population" value="0" units="people" 

source="landscan2005" /> 

 </bin> 

 <bin label="II" value="2" range="[1.5,2.5)" 

keywords="incomplete"> 

 <measure type="population" value="0" units="people" /> 

 </bin> 

 <bin label="III" value="3" range="[2.5,3.5)" 

keywords="incomplete"> 

 <measure type="population" value="963142" units="people" 

/> 

 </bin> 

 </summary> 

</exposure> 

62
6. ShakeCast Utilities 

This section describes utilities included in the standard ShakeCast distribution. All utilities 

(even core ShakeCast system services) can be executed directly from the command line and are 

only available to administrators. Utility such as “tester.pl” can be invoked directly from the 

Administration Interface for management of ShakeCast test events. As the development of the 

ShakeCast system continues, more utilities will be added to the existing inventory as part of the 

update. 

In general, the use of utilities is related to one or more of the three objectives: (1) state of 

the system; (2) system and inventory maintenance; and (3) data input/output. Among utilities 

described in this section, heartbeat, logrotate, and logstate are state-of-health utilities. 

The utilities manage_event, manage_facility, manage_profile, and manage_user

interact directly with the ShakeCast database for the purpose of maintenance. The 

scfeed_local, shake_fetch, tester, and template utilities provide the means for a 

ShakeCast system to digest special ShakeMaps, conduct local testing/exercise, and generate 

ShakeCast products that are unique to the local installation. 

6.1 heartbeat 

6.1.1 Name 

heartbeat.pl — ShakeCast Heartbeat Generator 

6.1.2 Synopsis 

heartbeat.pl 

6.1.3 Description 

The heartbeat.pl utility is used to generate a ShakeCast event XML with event type as HEARTBEAT. 

The output is injected into the ShakeCast system via sm_inject.pl, and a copy is stored in the 

ShakeMap data directory. This will trigger an event notification to users whom are subscribed to 

receive heartbeat events. 

The script reads no options from the command line. To create a customized heartbeat event, edit 

the script located inside the ShakeCast bin directory. 

63
6.2 logrotate 

6.2.1 Name 

logrotate.pl — ShakeCast Log File Rotation Tool 

6.2.2 Synopsis 

logrotate.pl [ --conf config file ] 

6.2.3 Description 

The logrotate.pl utility is used to generate rotating backup files of ShakeCast log files (“sc.log,” 

“sc_access.log,” and “sc_error.log”). Configurable parameters include rotate-time, max_size, 

keep-files, compress, and status-file. The administrator can schedule a routine run of this 

script for maintenance of ShakeCast log files. 

The script reads one optional configuration file from the command line. The default configuration 

file is “sc.conf.” 

rotate-time 

Specify the time window for keeping log entries. 

max_size 

Specify the size limit of log files. 

keep-files 

Specify the number of backup log files to retain. 

compress 

Specify the compression option of backup log files. 

status-file 

Specify the filename of process status. 

6.2.4 Options 

--conf

Specify the filename of a custom configuration file to read process parameters for 

logrotate.pl. 

64
6.3 logstats 

6.3.1 Name 

logstats.pl — ShakeCast Chart Generator for System Statistics 

6.3.2 Synopsis 

logstats.pl [ --conf config file ] 

6.3.3 Description 

The logstats.pl utility is used to process ShakeCast log files (“sc.log,” “sc_access.log,” and 

“sc_error.log”) specified in the system configuration file and to generate a set of image files in both 

histogram and pie charts. The daily activity chart is the default chart displayed in the default page 

of the Administration Web Interface. The administrator can schedule a routine run of this script to 

generate new statistics charts. 

The script reads one optional configuration file from the command line. The default configuration 

file is “sc.conf.” 

6.3.4 Options 

--conf

Specify the filename of a custom configuration file to read process parameters for 

logstats.pl. 

65
6.4 manage_event 

6.4.1 Name 

manage_event.pl — ShakeCast Event Management Tool 

6.4.2 Synopsis 

manage_event.pl [ mode ] [ option ... ] event_id [event_id2 ... ] 

6.4.3 Description 

The manage_event.pl utility is used to re-alert or delete processed ShakeMap events in the 

ShakeCast database. It reads one or more event IDs from the command line. Mode is one of 

--resend or --delete. The manage_event.pl utility will return an error message if you 

do not specify a mode. 

--resend

Reprocess notifications for the ShakeMaps and resend notifications to users who are 

on the recipient list. 

--delete

Delete existing events. All information for the processed ShakeMaps will be 

removed from the ShakeCast database; it does not affect downloaded products in the 

file system. 

6.4.4 Options 

--verbose

Display more detailed information about the progress of the import. This option 

may be repeated to increase detail further. 

--help

Print a synopsis of program usage and invocation options. 

66
6.5 manage_facility 

6.5.1 Name 

manage_facility.pl — ShakeCast Facility Management Tool 

6.5.2 Synopsis 

manage_facility.pl [ mode ] [ option ... ] file.csv [ file2.csv ... ] 

6.5.3 Description 

The manage_facility.pl utility is used to insert, update, or delete facility data in the ShakeCast 

database. It reads data from one or more CSV format files. One or more files must be given on the 

command line. Multiple files can have different formats. Mode is one of --insert, 

--replace, --delete, --update, or --skip. The manage_facility.pl utility will operate 

in replace mode if you do not specify a mode. 

--insert

New facility records are inserted. It is an error for the facility to already exist; if it 

does the input record is skipped. 

--replace

New records are inserted. If there is an existing facility it is first deleted, along with 

any associated attributes and fragility levels. All required facility fields must be 

supplied. 

--delete

Delete existing facilities. All required facility fields must be supplied. 

--skip

New facility records are inserted. Records for existing facilities are skipped without 

generating an error. The summary report will indicate how many records were 

skipped. 

--update

Update existing facilities. If the facility does not already exist an error is issued and 

the record is skipped. 

In this mode the only required fields are EXTERNAL_FACILITY_ID and 

FACILITY_TYPE. Any group values are simply added to the existing set of attributes 

for the facility, unless the new value matches an existing value, in which case the 

group value is skipped. For metrics, any metric that appears in the input will be 

completely replaced. 

6.5.4 Options 

--verbose

Display more detailed information about the progress of the import. This option 

may be repeated to increase detail further. 

--help

67
Print a synopsis of program usage and invocation options 

--limit=n

Terminate the import after n errors in input records. Set to 0 to allow an unlimited 

number of errors. 

This limit only applies to errors encountered when processing a data record from the 

input file. More serious errors, such as omitting a required field, will always cause 

the entire input file to be skipped. 

--quote=x

Use x as the quote character in the input file. The default quote character is a 

double-quote ("). This character is also used as the escape character within a quoted 

string. 

--separator=x

Use x as the field separator character in the input file. The default separator 

character is a comma (,). 

6.5.5 File Format 

The manage_facility.pl utility reads from one or more CSV-formatted files. By default, fields are 

separated by commas, and field values that include commas are protected by enclosing them in 

quotes, but these defaults can be modified; see the --quote and --separator options above. 

The first record in the input file must contain column headers in CSV-format. These headers tell 

manage_facility.pl how to interpret the rest of the records. Each header field must specify a 

facility field, a facility metric field, or a group field. The header fields are not case sensitive; 

facility_name and FACILITY_NAME are equivalent. Fields can appear in any order. 

6.5.5.1 Facility Fields 

The following facility names are recognized. These fields correspond to tables and columns in the 

ShakeCast database. Please refer to the ShakeCast Database Description on the USGS Web site for 

a more detailed description of the structure of the ShakeCast Database. 

external_facility_id (Text(32), required always) 

This field identifies the facility. It must be unique for a facility type but the same 

external_facility_id may be used for different types of facilities. 

facility_type (Text(10), required always) 

This field identifies the type of facility. It must match one of the types in the facility_type table. 

Currently defined types are: BRIDGE, CAMPUS, CITY, COUNTY, DAM, DISTRICT, 

ENGINEERED, INDUSTRIAL, MULTIFAM, ROAD, SINGLEFAM, STRUCTURE, TANK, 

TUNNEL, UNKNOWN, and HAZUS building types. Refer the HAZUS Damage Level document 

(appendix A) for the 128 HAZUS building types and code era. 

facility_name (Text(128), required for insert/replace) 

The value of this field is what the user sees. 

short_name (Text(10), optional) 

The value of this field is used by ShakeCast when a shorter version of the name is needed due to 

space limitations in the output. 

description (Text(255), optional) 

You can use this field to include a short description of the facility. 

lat (Float, required for insert/replace) 

68
Specifies the latitude of the facility in degrees and fractional degrees. 

lon (Float, required for insert/replace) 

Specifies the longitude of the facility in degrees and fractional degrees. 

6.5.5.2 Fragility Fields 

Each field beginning with METRIC: is taken to be a facility fragility specifier. The format of a 

fragility specifier is: 

METRIC:metric-name:damage-level

where metric-name is a valid Shakemap metric (MMI, PGV, PGA, PSA03, PSA10, or PSA30) and 

damage-level is a valid damage level (GREEN, YELLOW, ORANGE, or RED). Examples of 

Facility Fragility column labels are METRIC:MMI:RED and metric:pga:yellow. 

The metric-name values are defined by the ShakeMap system, and are generally not changed. The 

above values are current as of spring 2008. The damage level values shown above are the default 

values shipped with ShakeCast. These values are defined in your local ShakeCast database, and 

you may use the administration Web interface (Section 4.3) to change those values and the color 

names that refer to them. 

6.5.5.3 Attribute Fields 

A facility can have attributes associated with it. These attributes can be used to group and filter 

facilities. 

Each field beginning with ATTR: is taken to be a facility attribute specifier. The format of a facility 

attribute specifier is: 

ATTR:attribute-name

where attribute-name is a string not more than 20 characters in length. 

Examples of Facility Attribute column labels are ATTR:COUNTY and ATTR:Construction. 

Attribute values can be any string up to 30 characters long. 

6.5.6 Example 

6.5.6.1 Example 1 — Point Facilities 

Assume we have a file named ca_cities.csv containing California cities that we want to load into 

the ShakeCast database. The file is in CSV format and includes the name of each city and the 

latitude/longitude of its city center or city hall. Records in the file are in the form 

 Rancho Cucamonga,34.1233,-117.5794 

 Pasadena,34.1561,-118.1318 

69
The file is missing two required fields, facility_type and external_facility_id. 

Since the city name is unique we can add a new column that is a copy of the name column and use 

that as the external_facility_id. Another column containing the value CITY for each row 

is added for the facility_type. You can either make these changes using an editor, a 

spreadsheet program, or with a simple script written in a text processing language like Perl. 

After making these modifications the records look like 

 CITY,Rancho Cucamonga,Rancho Cucamonga,34.1233,-117.5794 

 CITY,Pasadena,Pasadena,34.1561,-118.1318 

The input file also needs a header record; after adding one the input file looks like 

 FACILITY_TYPE,EXTERNAL_FACILITY_ID,FACILITY_NAME,LAT,LON 

 CITY,Rancho Cucamonga,Rancho Cucamonga,34.1233,-117.5794 

 CITY,Pasadena,Pasadena,34.1561,-118.1318 

 ... 

The facilities in this file can now be loaded into ShakeCast using the command 

 manage_facility.pl ca_cities.csv 

6.5.6.2 Example 2 — Fragility Parameters 

It is easy to load fragility parameters for your facilities using manage_facility.pl. Building on 

example 1, assume a simple model where Instrumental Intensity (MMI) above 7 corresponds to 

likely damage (RED), MMI between 5 and 7 corresponds to possible damage (YELLOW), and 

MMI below 5 corresponds to little chance of damage (GREEN). The lower threshold of each range 

(1, 5, 7) is appended to every record in the input file and the header record is changed to reflect the 

added fields: 

 FACILITY_TYPE,EXTERNAL_FACILITY_ID,FACILITY_NAME,LAT,LON, \ 

 METRIC:MMI:GREEN,METRIC:MMI:YELLOW,METRIC:MMI:RED 

 CITY,Rancho Cucamonga,Rancho Cucamonga,34.1233,-117.5794,1,5,7 

 CITY,Pasadena,Pasadena,34.1561,-118.1318,1,5,7 

 ... 

Import this file as before. New facility data will replace existing ones. 

6.5.6.3 Example 3 — Multiple Attributes and Multiple Metrics 

You can include multiple attributes, multiple metrics, or multiple attributes and multiple metrics for 

each row of an import file. For example, 

 FACILITY_TYPE,EXTERNAL_FACILITY_ID,ATTR:COUNTY, ATTR:SIZE,\ 

 METRIC:MMI:GREEN, METRIC:MMI:YELLOW, METRIC:MMI:RED 

 CITY,Rancho Cucamonga,San Bernardino,Small,1,2,6 

 CITY,Pasadena,Los Angeles,Medium,1,2,6 

70
This file would be loaded using the command 

 manage_facility.pl --update city_county.csv 

The above example updates the existing city locations to associate them with a county attribute and 

a size attribute, and defines the green, yellow, and red shaking thresholds. 

71
6.6 manage_profile 

6.6.1 Name 

manage_profile.pl — ShakeCast Profile Management Tool 

6.6.2 Synopsis 

manage_profile.pl [ mode ] [ option ... ] [ profile.conf ] [ lat,lon ... ] 

6.6.3 Description 

The manage_profile.pl utility is used to insert, update, or delete geometry profiles in the 

ShakeCast database and to associate facilities within the profile boundaries with the profile. It 

reads data from a profile configuration file or lat/lon pairs of a polygon from the command line. 

Mode is one of --insert, --delete, --update, or --poly. The manage_profile.pl utility 

will operate in replace mode if you do not specify a mode. 

--insert

New profiles are inserted. It is an error if the profile already exists; if it does the 

input record is skipped. 

--delete

Delete existing profiles. All required profile fields must be supplied. 

--poly

Read polygon data from the command line and output facility data within the 

polygon boundaries. 

6.6.4 Options 

--conf

Specify the optional profile configuration file. 

--verbose

Display more detailed information about the progress of the import. This option 

may be repeated to increase detail further. 

--help

Print a synopsis of program usage and invocation options. 

6.6.5 File Format 

The manage_profile.pl utility reads data from a file in Apache config format. Lines beginning 

with ‘#’ and empty lines will be ignored. Spaces at the beginning and the end of a line will also be 

ignored as well as tabulators. If you need spaces at the end or the beginning of a value you can use 

double-quote ("). An option line starts with its name followed by a value. An equal sign (=) is 

optional. Some possible examples: 

 user max 

 user = max 

72
 user max 

If there is more than one statement with the same name, an array will be created instead of a scalar. 

Each profile is defined as a block of options. A block looks much like a block in the well known 

Apache config format. It starts with <blockname> and ends with </blockname>. An example: 

 <CI> 

 POLY 35.8000 -116.4000 \ 

 34.0815 -114.4717 \ 

 32.0000 -114.3333 \ 

 32.0000 -120.5000 \ 

 34.5000 -121.2500 \ 

 37.2167 -118.0167 \ 

 36.6847 -117.7930 \ 

 35.8000 -116.4000 

 <NOTIFICATION> 

 NOTIFICATION_TYPE NEW_EVENT 

 DELIVERY_METHOD EMAIL_HTML 

 EVENT_TYPE ALL 

 </NOTIFICATION> 

 <NOTIFICATION> 

 NOTIFICATION_TYPE NEW_PROD 

 DELIVERY_METHOD EMAIL_HTML 

 PRODUCT_TYPE GRID_XML 

 EVENT_TYPE ALL 

 </NOTIFICATION> 

 </CI> 

6.6.5.1 Profile Tag Names 

The following profile tag names are recognized. These fields correspond to tables and columns in 

the ShakeCast database. Please refer to the ShakeCast Database Description for a more detailed 

description of the structure of the ShakeCast Database. 

poly (float pairs, required always) 

This field identifies the boundaries of the profile geometry. It must contain at least three anchor 

points in order to define a polygon. The total number of anchor points should be limited to less 

than 100, otherwise the administration interface may not be able to display the entire polygon 

during editing. The manage_profile.pl will, however, process the polygon definition. 

notification (Text(32), optional) 

One notification block represents one notification request associated with the profile and applies to 

all facilities within the profile polygon. Multiple notification blocks for a profile are permitted. 

6.6.5.2 Notification Tag Names 

Each notification block defines one notification request. Tag names correspond to the field names 

of the table “profile_notification_request.” Required tags for a notification block include 

NOTIFICATION_TYPE, DELIVERY_METHOD, and EVENT_TYPE. The EVENT_TYPE tag is 

required for notification type NEW_PROD, and the DAMAGE_LEVEL tag for notification type 

DAMAGE. Valid notification types are CAN_EVENT, NEW_EVENT, UPD_EVENT, SHAKING,

NEW_PROD, and DAMAGE. 

73
can_event 

This notification request is triggered when an event is cancelled by the seismic network in 

which the event was located and the ShakeMap is removed from the USGS Web site. 

Requires EVENT_TYPE and DELIVERY_METHOD tags. 

new_event 

This notification request is triggered when an event is located by a seismic network and a 

ShakeMap becomes available on the USGS Web site. Requires EVENT_TYPE and 

DELIVERY_METHOD tags. 

upd_event 

This notification request is triggered when the source parameters of an event are updated 

with a new version by the seismic network. New versions of ShakeMaps for the event may 

or may not coincide with an updated event. Requires EVENT_TYPE and DELIVERY_METHOD

tags. 

new_prod 

This notification request is triggered when a specified ShakeMap product of an event is 

available on the USGS Web site. Requires EVENT_TYPE, DELIVERY_METHOD, and 

PRODUCT_TYPE tags. 

shaking 

This notification request is triggered when the ground shaking parameter at the location of 

the facility exceeds the preset value. Requires EVENT_TYPE, DELIVERY_METHOD, METRIC, 

and LIMIT_VALUE tags. 

damage 

This notification request is triggered when the ground shaking parameter at the location of 

the facility falls between the high and low values of facility fragility settings. Requires 

EVENT_TYPE, DELIVERY_METHOD, and DAMAGE_LEVEL tags. 

74
6.7 manage_user 

6.7.1 Name 

manage_user.pl — ShakeCast User Management Tool 

6.7.2 Synopsis 

manage_user.pl [ mode ] [ option ... ] file.csv [ file2.csv ... ] 

6.7.3 Description 

The manage_user.pl utility is used to insert, update, or delete user data in the ShakeCast database. 

It reads data from one or more CSV format files. One or more files must be given on the command 

line. Multiple files can have different formats. Mode is one of --insert, --replace, 

--delete, --update, or --skip. The manage_user.pl utility will operate in replace mode 

if you do not specify a mode. 

--insert

New user records are inserted. It is an error for the user to already exist; if it does 

the input record is skipped. 

--replace

New records are inserted. If there is an existing user it is first deleted, along with 

any associated delivery addresses, notification requests, and profiles. All required 

user fields must be supplied. 

--delete

Delete existing users. All required user fields must be supplied. 

--skip

New user records are inserted. Records for existing users are skipped without 

generating an error. The summary report will indicate how many records were 

skipped. 

--update

Update existing users. If the user does not already exist an error is issued and the 

record is skipped. 

In this mode the only required fields are USERNAME and USER_TYPE. Any delivery 

methods, profiles and users for cloning that appears in the input will be completely 

replaced. 

6.7.4 Options 

--verbose

Display more detailed information about the progress of the import. This option 

may be repeated to increase detail further. 

--help

Print a synopsis of program usage and invocation options 

--limit=n

75
Terminate the import after n errors in input records. Set to 0 to allow an unlimited 

number of errors. 

This limit only applies to errors encountered when processing a data record from the 

input file. More serious errors, such as omitting a required field, will always cause 

the entire input file to be skipped. 

--quote=x

Use x as the quote character in the input file. The default quote character is a 

double-quote ("). This character is also used as the escape character within a quoted 

string. 

--separator=x

Use x as the field separator character in the input file. The default separator 

character is a comma (,). 

6.7.5 File Format 

The manage_ user.pl utility reads from one or more CSV-formatted files. By default, fields are 

separated by commas, and field values that include commas are protected by enclosing them in 

quotes, but these defaults can be modified; see the --quote and --separator options above. 

The first record in the input file must contain column headers. These headers tell manage_user.pl

how to interpret the rest of the records. Each header field must specify a user name field and a user 

type field. The header fields are not case sensitive; username and USERNAME are equivalent. 

Fields can appear in any order. 

6.7.5.1 User Fields 

The following facility names are recognized. These fields correspond to tables and columns in the 

ShakeCast database. Please refer to the ShakeCast Database Description for a more detailed 

description of the structure of the ShakeCast database. 

username (Text(32), required always) 

This field identifies the user. It must be unique for a user type. 

user_type (Text(10), required always) 

This field identifies the type of use. It must match one of the types in the user_type table. 

Currently defined types are: ADMIN, USER, and SYSTEM. 

full_name (Text(32), optional) 

The value of this field is the user’s full name. 

email_address (Text(10), optional) 

The value of this field is the user’s email address for receiving communication from the 

ShakeCast system. 

password (Text(10), optional) 

The value of this field is used by ShakeCast to generate a password for accessing the 

ShakeCast interface and the Web site if password protected. 

phone_number (Text(255), optional) 

You can use this field to include a user’s phone numbers. 

76
6.7.5.2 Delivery Method Fields 

Each field beginning with DELIVERY: is taken to be a delivery method specifier. The format of a 

delivery method specifier is: 

DELIVERY:delivery-method

where delivery-method is a valid message format (PAGER, EMAIL_HTML, or EMAIL_TEXT). 

Examples of Delivery Method column labels are DELIVERY:EMAIL_HTML and 

delivery:email_html. 

The message format values are defined by the ShakeCast system, and are generally not changed. 

The damage level values shown above are the default values shipped with ShakeCast. These values 

are defined in your local ShakeCast database, and you may use the administration Web interface to 

change those values and the color-names that refer to them. 

6.7.5.3 Profile Fields 

A user can have notification requests replicated from an existing profile. Each field beginning with 

PROFILE: is taken to be a profile specifier. The format of a profile specifier is: 

PROFILE:profile-name

where profile-name is a valid profile name. 

6.7.5.4 User Fields 

A user can have notification requests replicated from an existing user. Each field beginning with 

USER: is taken to be a user specifier. The format of a user specifier is: 

USER: shakecast-user

where shakecast-user is a valid user ID. 

77
6.8 scfeed_local 

6.8.1 Name 

scfeed_local.pl — ShakeMap Grid/Product Injection Tool 

6.8.2 Synopsis 

scfeed_local.pl [ --event event_id ] [ option ... ] 

6.8.3 Description 

The scfeed_local.pl utility is used to process downloaded ShakeMap products located in the 

ShakeCast data directory. It reads one event ID from the command line and creates XML messages 

before feeding them to ShakeCast. The injection process triggers the ShakeCast process in the 

same manner as for a real earthquake with respect to facility damage assessment and user 

notifications. 

The name of an unprocessed ShakeMap must match the name of an event ID. ShakeMaps can be 

downloaded via the USGS ShakeMap link from the ShakeCast Administration Panel or manually 

from other sources. It will be renamed with the version number appended to the end of the 

directory name after scfeed_local.pl has processed the ShakeMap. Outputs of ShakeCast XML 

files will also be stored in the same directory. 

The script will quit gracefully if the ShakeMap has been processed earlier by the ShakeCast system, 

and as a result no notifications will be delivered. To reprocess a ShakeMap that already exists in 

the ShakeCast system, the administrator will need to either convert the ShakeMap into a test event 

or delete the event first. Instead of using the Administration Interface, an administrator can use the 

tester.pl utility to convert a ShakeMap to a test event and the manage_event.pl utility to delete a 

ShakeMap. The ShakeCast data directory for the deleted ShakeMap also needs to be removed from 

the file system before starting the reprocess procedure described earlier. 

6.8.4 Options 

--event

Specify ID of the event to process. All information for the processed ShakeMaps 

will be removed from the ShakeCast database; it does not affect downloaded 

products in the file system. 

--verbose

Display more detailed information about the progress of the import. This option 

may be repeated to increase detail further. 

--help

Print a synopsis of program usage and invocation options 

78
6.9 shake_fetch 

6.9.1 Name 

shake_fetch.pl — USGS ShakeMap Fetching Tool 

6.9.2 Synopsis 

shake_fetch.pl [ option ... ] 

6.9.3 Description 

The shake_fetch.pl utility is used to retrieve ShakeMaps from the USGS Web site then triggers the 

ShakeCast process for the downloaded event. An event can be either an actual or a scenario 

ShakeMap. The script is usually invoked as a scheduled task from the administration interface but 

also can be executed directly from the command line interface. Both --network and --event

options are required. A previously processed event will not re-trigger the ShakeCast process. 

6.9.4 Options 

--network

Specify network code of the ShakeMap to process. 

--event

Specify ID of the ShakeMap to process. 

--help

Print a synopsis of program usage and invocation options. 

79
6.10 template 

6.10.1 Name 

template.pl — ShakeCast General Templating Tool 

6.10.2 Synopsis 

template.pl [ option ... ] -–event event_id –-template template 

6.10.3 Description 

The template.pl utility is used to generate a ShakeCast facility summary for the specified event. 

The script reads at least one event ID and one template file from the command line. The output file 

is stored in the ShakeCast data directory for the specified event. By default, if no output filename 

is specified, the filename of the template file will be used (without “.tt” postfix) instead. The 

underscore symbol (_) will be interpreted as the file extension separator. 

--event=s

Specify ID of the event to process. 

--template=s

Specify a filename for the template used to generate ShakeCast summary. The 

template files are located under the ShakeCast “template/xml” directory. The 

system comes with two default templates. The file “shakecast.tt” is the template for 

generating “exposure.xml’ and the file “kml.tt” for generating Google Earth KML 

format XML files. 

6.10.4 Options 

--version=n

Specify version number of the event to process. 

--output=s

Specify filename of the output of ShakeCast summary. The output directory is the 

ShakeCast data directory for the specified event. 

--help

Print a synopsis of program usage and invocation options. 

6.10.5 File Format 

The template.pl utility is based on the Perl Template Toolkit. Please see the Template Manual 

manual page on the Comprehensive Perl Archive Network (CPAN) for the complete reference, 

which goes into much greater detail about the features and use of the Template Toolkit. 

This section covers a brief summary of the template directives. ShakeCast specific identifiers 

include exposure, item, and type. Facility specific identifiers include name, latitude,

longitude, damage_level, MMI, PGA, PGV, PSA03, PSA10, and PSA30. 

80
6.10.5.1 GET 

Evaluate and print a variable or value. 

 [% GET variable %] 

 [% variable %] 

 [% hash.key %] 

 [% list.n %] 

 [% code(args) %] 

 [% obj.meth(args) %] 

 [% "value: $var" %] 

6.10.5.2 CALL 

As per GET but without printing result (for example, call code). 

 [% CALL variable %] 

6.10.5.3 SET 

Assign a values to variables. 

 [% SET variable = value %] # 'SET' also optional 

 [% variable = other_variable 

 variable = 'literal text @ $100' 

 variable = "interpolated text: $var" 

 list = [ val, val, val, val, ... ] 

 list = [ val..val ] 

 hash = { var => val, var => val, ... } 

 %] 

6.10.5.4 DEFAULT 

Like SET above, but variables are only set if currently unset (that is, have no true value). 

 [% DEFAULT variable = value %] 

6.10.5.5 INSERT 

Insert a file without any processing performed on the contents. 

 [% INSERT legalese.txt %] 

6.10.5.6 INCLUDE 

Process another template file or block and include the output. Variables are localised. 

 [% INCLUDE template %] 

 [% INCLUDE template var = val, ... %] 

6.10.5.7 PROCESS 

As INCLUDE above, but without localising variables. 

 [% PROCESS template %] 

 [% PROCESS template var = val, ... %] 

6.10.5.8 WRAPPER 

Process the enclosed block WRAPPER ... END block then INCLUDE the named template, passing 

the block output in the 'content' variable. 

 [% WRAPPER template %] 

 content... 

 [% END %] 

81
6.10.5.9 BLOCK 

Define a named template block for subsequent INCLUDE, PROCESS, etc. 

 [% BLOCK template %] 

 content 

 [% END %] 

6.10.5.10 FOREACH 

Repeat the enclosed FOREACH ... END block for each value in the list. 

 [% FOREACH variable = [ val, val, val ] %] # either 

 [% FOREACH variable = list %] # or 

 [% FOREACH list %] # or 

 content... 

 [% variable %] 

 [% END %] 

6.10.5.11 WHILE 

Enclosed WHILE ... END block is processed while condition is true. 

 [% WHILE condition %] 

 content 

 [% END %] 

6.10.5.12 IF / UNLESS / ELSIF / ELSE 

Enclosed block is processed if the condition is true / false. 

 [% IF condition %] 

 content 

 [% ELSIF condition %] 

 content 

 [% ELSE %] 

 content 

 [% END %] 

 [% UNLESS condition %] 

 content 

 [% # ELSIF/ELSE as per IF, above %] 

 content 

 [% END %] 

6.10.5.13 SWITCH / CASE 

Multi-way switch/case statement. 

 [% SWITCH variable %] 

 [% CASE val1 %] 

 content 

 [% CASE [ val2, val3 ] %] 

 content 

 [% CASE %] # or [% CASE DEFAULT %] 

 content 

 [% END %] 

6.10.5.14 MACRO 

Define a named macro. 

 [% MACRO name <directive> %] 

 [% MACRO name(arg1, arg2) <directive> %] 

82
 ... 

 [% name %] 

 [% name(val1, val2) %] 

6.10.5.15 FILTER 

Process enclosed FILTER ... END block then pipe through a filter. 

 [% FILTER name %] # either 

 [% FILTER name( params ) %] # or 

 [% FILTER alias = name( params ) %] # or 

 content 

 [% END %] 

6.10.5.16 USE 

Load a "plugin" module, or any regular Perl module if LOAD_PERL option is set. 

 [% USE name %] # either 

 [% USE name( params ) %] # or 

 [% USE var = name( params ) %] # or 

 ... 

 [% name.method %] 

 [% var.method %] 

6.10.5.17 PERL / RAWPERL 

Evaluate enclosed blocks as Perl code (requires EVAL_PERL option to be set). 

 [% PERL %] 

 # perl code goes here 

 $stash->set('foo', 10); 

 print "set 'foo' to ", $stash->get('foo'), "\n"; 

 print $context->include('footer', { var => $val }); 

 [% END %] 

 [% RAWPERL %] 

 # raw perl code goes here, no magic but fast. 

 $output .= 'some output'; 

 [% END %] 

6.10.5.18 TRY / THROW / CATCH / FINAL 

Exception handling. 

 [% TRY %] 

 content 

 [% THROW type info %] 

 [% CATCH type %] 

 catch content 

 [% error.type %] [% error.info %] 

 [% CATCH %] # or [% CATCH DEFAULT %] 

 content 

 [% FINAL %] 

 this block is always processed 

 [% END %] 

6.10.5.19 NEXT 

Jump straight to the next item in a FOREACH/WHILE loop. 

 [% NEXT %] 

83
6.10.5.20 LAST 

Break out of FOREACH/WHILE loop. 

 [% LAST %] 

6.10.5.21 RETURN 

Stop processing current template and return to including templates. 

 [% RETURN %] 

6.10.5.22 STOP 

Stop processing all templates and return to caller. 

 [% STOP %] 

6.10.5.23 TAGS 

Define new tag style or characters (default: [% %]). 

 [% TAGS html %] 

 [% TAGS <!-- --> %] 

6.10.5.24 COMMENTS 

Ignored and deleted. 

 [% # this is a comment to the end of line 

 foo = 'bar' 

 %] 

 [%# placing the '#' immediately inside the directive 

 tag comments out the entire directive 

 %] 

84
6.11 tester 

6.11.1 Name 

tester.pl – ShakeCast Test Event Tool 

6.11.2 Synopsis 

tester.pl [ option ... ] 

6.11.3 Description 

The tester.pl utility is used to handle ShakeCast test events and includes conversion, listing, and 

triggering of test events. The script is usually invoked from the administration interface but also 

can be executed directly. It reads one process type from the command line. 

6.11.4 Options 

--type

Specify the type of action to process. Process type is one of event_menu, 

new_test, create_test, inject_next, or inject_first. 

event_menu 

Output a list of test events available on the system. 

new_test 

Output a list of actual events on the system that have not been converted into test 

events. 

create_test 

Convert the specified event into a test event that can be triggered locally. Require 

an additional --key option. A new data directory for the event will be created 

under the “test_data” directory with the name of event ID and “_scte” postfix. 

inject_first 

Trigger a ShakeCast process for the specified test event as a new event. Require an 

additional --key option. 

inject_next 

Trigger a ShakeCast process for the specified test event as an updated event. 

Require an additional --key option. 

--key

Specify ID of the event to process. All information for the processed ShakeMaps 

will be removed from the ShakeCast database; it does not affected downloaded 

products in the file system. 

85
References 

Lin, K. W, Wald, D.J., Worden, B., and Shakal, A. F., 2005, Quantifying ShakeMap uncertainty, in

SMIP05 Seminar on the Utilization of Strong Motion Data, Los Angeles, Calif., 10 May 

2005, Proceedings: Sacramento, Calif., California Geological Survey, California Strong 

Motion Instrumentation Program, p. 37-49. 

National Institute of Building Sciences and Federal Emergency Management Agency, 2003, Multihazard loss estimation methodology, Earthquake model. HAZUS®MH technical manual: 

Washington, D.C., Federal Emergency Management Agency, 690 p. 

Wald, David J, and Lin, K., 2007, USGS ShakeCast—Automating, simplifying, and improving the 

use of ShakeMap for post-earthquake decisionmaking and response: U.S. Geological 

Survey Fact Sheet 2007-3086, 6 p., http://pubs.usgs.gov/fs/2007/3086/. 

Wald, David J., Lin, K., Porter, K., and Turner, L., in press, ShakeCast—Automating and 

improving the use of ShakeMap for post-earthquake decision-making and response: 

Earthquake Spectra. 

Wald, D. Naecker, J., P., Roblee, C., and Turner, L., 2003, Development of a ShakeMap-based, 

earthquake response system within Caltrans, in Beavers, J., ed., Advancing mitigation 

technologies and disaster response for lifeline systems: Reston, Va., American Society of 

Civil Engineers, Technical Council on Lifeline Earthquake Engineering, Monograph No. 

25, p. 113-122. 

Wald, D.J., Quitoriano, V., Heaton, T.H., Kanamori, H., Scrivner, C.W. and Worden, C.B., 1999, 

TriNet "ShakeMaps"—Rapid generation of peak ground motion and intensity maps for 

earthquakes in southern California: Earthquake Spectra, v. 15, p. 537-555. 

Wald, David J., Worden, B. C., Quitoriano, V., and Pankow, K. L., 2005, ShakeMap manual— 

Technical manual, user’s guide, and software guide: U.S. Geological Survey Techniques 

and Methods 12–A1, 128 p., http://pubs.usgs.gov/tm/2005/12A01/. 

86
Appendix A. Converting HAZUS Structure Type to 

Structural Damage Level 

A.1 Selecting Model Building Type and Code Era 

ShakeCast offers structural damage estimation capability adapted from the HAZUS-MH 

earthquake module (NIBS and FEMA, 2003). For any site of interest, the user begins by selecting 

from the available HAZUS model building types, of which there are 36 (table A.1). “Model 

building type” refers to the materials of construction (wood, steel, reinforced concrete, etc.), the 

system used to transmit earthquake forces from the ground through the building (referred to as the 

lateral force-resisting system), and sometimes height category (lowrise, midrise, and highrise, 

which generally correspond to 1-3, 4-7, and 8+ stories, respectively). 

The user must also select for each facility its building code era, of which there are four 

(high code, moderate code, low code, and pre-code; table A.2 and fig. A.1). Code eras reflect 

important changes in design forces or detailing requirements that matter to the seismic performance 

of a building. Sixteen combinations of model building type and code era do not exist (for example, 

high-code unreinforced masonry bearing wall), so in total there are 128 choices for HAZUS model 

building type and code era. Note that code era is largely a function of location and year built, so in 

principal ShakeCast could simplify the user’s job of selecting a code era by asking for era of 

construction (pre-1941, 1941-1975, or post-1975) instead and then looking up the code era via 

internal GIS database. 

Figure A.1 Seismic zone map of the United States (fig. 16-2, ICBO, 1997). 

87
A.2 Describing Damage

The user selects between 3 and 4 alert levels, meaning that any facility affected by an 

earthquake is noted either green, yellow, or red (3 levels), or green, yellow, orange, or red (4 

levels). These colors index the likely structural damage state of the facility in HAZUS terms: green 

corresponds to HAZUS’ undamaged or slight structural damage states, yellow corresponds to 

moderate structural damage, orange to extensive structural damage, and red to complete structural 

damage. These terms (slight, moderate, etc.) are described via likely effects of the earthquake on 

the structural system. For example, for a small woodframe building (W1, regardless of code era), 

“green” corresponds to “Undamaged or small plaster or gypsum-board cracks at corners of door 

and window openings and wall-ceiling intersections; small cracks in masonry chimneys and 

masonry veneer.” These descriptions can be found in the HAZUS-MH technical manual (NIBS and 

FEMA, 2003) Section 5.3.1. 

A.3 Relating Seismic Excitation to Structural Damage 

When an earthquake occurs, its shaking intensity at each facility location is estimated in 

terms of peak horizontal ground acceleration (PGA). Buildings and ground motions are highly 

variable, even given a model building type and PGA level, so it is uncertain the exact level of PGA 

that will cause a given facility to experience structural damage of any particular level. The 

relationship between PGA and damage state is therefore probabilistic, meaning that one can 

estimate the probability of a given building experiencing a given structural damage state when the 

building experiences a certain level of PGA. It is more convenient here to estimate the PGA at 

which there is a given probability of damage exceeding a given structural damage state. In 

ShakeCast, a facility is indicated as damage level x (that is, green, yellow, orange, or red) when the 

PGA is such that there is at least a 50% probability of the corresponding HAZUS structural damage 

state and less than a 50% probability of the next-higher HAZUS structural damage state. These 

PGA values are taken from the HAZUS-MH Technical Manual Table 5.14a-d. 

A.4 Tabular Lookup Data

Two lookup files in CSV format are provided with this manual, one for a three-level 

damage scheme, the other for a four-level damage scheme. Each has seven columns or fields, listed 

in table A.3. The fields correspond to data appearing in the ShakeCast Facility Administration 

screen (see Section 4.3). 

88
Table A.1. HAZUS-MH earthquake model building types (NIBS and FEMA 2003 Table 3.1) 

Height 

No. Label Description Range Typical 

Name Stories Stories Feet 

1 W1 Wood, Light Frame (≤ 5,000 sq. ft.) 1 - 2 1 14 

2 W2 Wood, Commercial and Industrial 

(>5,000 sq. ft.)

All 2 24 

3 S1L Low-Rise 1 - 3 2 24 

4 S1M Steel Moment Frame Mid-Rise 4 - 7 5 60 

5 S1H High-Rise 8+ 13 156 

6 S2L Low-Rise 1 - 3 2 24 

7 S2M Steel Braced Frame Mid-Rise 4 - 7 5 60 

8 S2H High-Rise 8+ 13 156 

9 S3 Steel Light Frame All 1 15 

10 

11 

12 

S4L 

S4M 

S4H 

Steel Frame with Cast-in-Place 

Concrete Shear Walls 

Low-Rise 

Mid-Rise 

High-Rise 

1 - 3 

4 - 7 

8+ 

2 

5 

13 

24 

60 

156 

13 

14 

15 

S5L 

S5M 

S5H 

Steel Frame with Unreinforced 

Masonry Infill Walls 

Low-Rise 

Mid-Rise 

High-Rise 

1 - 3 

4 - 7 

8+ 

2 

5 

13 

24 

60 156 

16 C1L Low-Rise 1 - 3 2 20 

17 C1M Concrete Moment Frame Mid-Rise 4 - 7 5 50 

18 C1H High-Rise 8+ 12 120 

19 C2L Low-Rise 1 - 3 2 20 

20 C2M Concrete Shear Walls Mid-Rise 4 - 7 5 50 

21 C2H High-Rise 8+ 12 120 

22 

23 

24 

C3L 

C3M 

C3H 

Concrete Frame with Unreinforced 

Masonry Infill Walls 

Low-Rise 

Mid-Rise 

High-Rise 

1 - 3 

4 - 7 

8+ 

2 

 5 

 12 

20 

50 

120 

25 PC1 Precast Concrete Tilt-Up Walls All 1 15 

26 

27 

28 

PC2L 

PC2M 

PC2H 

Precast Concrete Frames with 

Concrete Shear Walls 

Low-Rise 

Mid-Rise 

High-Rise 

1 - 3 

4 - 7 

8+ 

2 

5 

12 

20 

50 

120 

29 RM1L Reinforced Masonry Bearing Walls Low-Rise 1-3 2 20 

30 RM2M with Wood or Metal Deck Diaphragms Mid-Rise 4+ 5 50 

31 

32 

33 

RM2L 

RM2M RM2H Reinforced Masonry Bearing Walls 

with Precast Concrete Diaphragms 

Low-Rise 

Mid-Rise 

 High-Rise 

1 - 3 

4 - 7 

8+ 

2 

5 

12 

20 

50 

120 

34 URML Low-Rise 1 – 2 1 15 

35 URMM Unreinforced Masonry Bearing Walls Mid-Rise 3+ 3 35 

36 MH Mobile Homes All 1 10 

89
90

Table A.2. HAZUS-MH guidelines for selection of damage functions for typical buildings based on 

UBC seismic zone and building age (NIBS and FEMA 2003 Table 5.20). 

UBC Seismic Zone 

(NEHRP Map Area) 

Post-1975 1941 - 1975 Pre-1941

Zone 4 

(Map Area 7) 

High-Code Moderate-Code Pre-Code 

(W1 = Moderate-Code) 

Zone 3 Moderate-Code Moderate-Code Pre-Code 

(Map Area 6) (W1 = Moderate-Code) 

Zone 2B Moderate-Code Low-Code Pre-Code 

(Map Area 5) (W1 = Low-Code) 

Zone 2A Low-Code Low-Code Pre-Code 

(Map Area 4) (W1 = Low-Code) 

Zone 1 Low-Code Pre-Code Pre-Code 

(Map Area 2/3) (W1 = Low-Code) (W1 = Low-Code) 

Zone 0 Pre-Code Pre-Code Pre-Code 

(Map Area 1) (W1 = Low-Code) (W1 = Low-Code) (W1 = Low-Code) 

Table A.3. Layout of damage lookup tables. 

Field name Type Description 

ID Integer A unique index 

Facility Type String HAZUS model building type and seismic design level 

Color String Green, Yellow, Orange, or Red 

Damage Level String Equivalent HAZUS structural damage level(s) 

Low Limit Integer Intensity with 50% probability of this damage level occurring 

High Limit Integer Intensity with 50% probability of next damage level occurring

Metric String Intensity metric