SOD - CSV Events

CSV Events

CSV stands for "Comma-Separated Values" and is a plain-text file format that is readable and writable by spreadsheet applications like Excel. The first line is made up of the field names separated by commas. Subsequent lines contain the data in the same order as their corresponding fields, also separated by commas. SOD has the capability of importing events from and exporting them to .csv files. On this page we will explain the CSV importing process.

CSVEventSource

The CSVEventSource acts much like the eventFinder in that it provides events for SOD to process, but the events have already been found. Now it's just a case of reading them in and doing whatever you want to do with them. The most likely scenario where you would need to import a list of events from a .csv file is if you were to come in possesion of such a list that was exported from SOD using the CSVEventPrinter. We will discuss the CSVEventPrinter later on this page.

Fields

The fields are broken up into three categories:

Required
Optional
Defaultable

Defaultable fields are ones that, if omitted, will default to a sensible value during the import process.

Required field

time

time at which the event occurred

Data in the time field should be formatted according to the ISO 8601 standard for representation of date and time. Here is an example:

2006-05-09T13:15:00.000Z

Optional fields

latitude

the latitude of the event from -90 to 90

longitude

the longitude of the event from -180 to 180

depth

how far the event was below the ground

magnitude

the value of the magnitude

catalog

the catalog to which the event belongs

contributor

the organization that estimated the event

name

the name of the event. probably the id of whatever database it came from

flinnEngdahlRegion

number value of the region in which the event occurred

flinnEngdahlRegionType

type of region in which the earthquake occurred. can be either 0 (seismic region) or 1 (geographic region)

Defaultable fields

depthUnits

the units of depth. default is "kilometer"

magnitudeType

the type of magnitude estimation. default is "M"

Creating a CSV event file

If you are creating a file from hand, a good place to start is just creating one with the only required field: time.

time
2006-05-09T13:15:00.000Z
2006-05-09T14:57:14.000Z
2006-05-10T06:03:30.000Z

Seeing as a lot of SOD's usefulness depends on knowing at least a little bit more information about an event than its origin time, a csv file that includes magnitudes and locations along with the time will probably yield better results.

time, magnitude, latitude, longitude, depth
2006-05-09T13:15:00.000Z, 7.0, -20.21, -173.90, 16
2006-05-09T14:57:14.000Z, 5.5, -19.70, -172.53, 40
2006-05-10T06:03:30.000Z, 5.2, -20.75, -173.10, 38

SOD's CSVEventPrinter will output all of the fields. If you wish to see an example, here is one created by our tutorial.xml recipe file demo.

Configuring the recipe file

If you want to use a CSVEventSource in a SOD run, it's fairly simple to configure. In the eventArm of your recipe file, instead of using the eventFinder ingredient, use the CSVEventSource. If you have a file called events.csv that contains your events, the eventArm in your recipe file may look something like this:

<?xml version="1.0"?>
<sod>
    <eventArm>
        <CSVEventSource>
            <filename>events.csv</filename>
        </CSVEventSource>
        <originOR>
            <originAND>
                <magnitudeRange>
                    <min>5</min>
                </magnitudeRange>
                <originDepthRange>
                    <unit>KILOMETER</unit>
                    <min>100</min>
                    <max>200</max>
                </originDepthRange>
            </originAND>
            <magnitudeRange>
                <min>6</min>
            </magnitudeRange>
        </originOR>
        <printlineEventProcess/>
    </eventArm>
</sod>

HTML XML

CSVEventPrinter

The CSVEventPrinter outputs events found by SOD to a .csv file. It may be useful if you want to import events retrieved with SOD into a spreadsheet.

Configuring the recipe file

If you want the events retrieved by SOD to be exported to a .csv file, all you need to do is add a CSVEventPrinter to the eventArm in your recipe file.

<?xml version="1.0"?>
<sod>
    <eventArm>
        <fdsnEvent>
            <originTimeRange>
                <startTime>
                    <year>2003</year>
                    <month>1</month>
                    <day>1</day>
                </startTime>
                <endTime>
                    <year>2003</year>
                    <month>1</month>
                    <day>10</day>
                </endTime>
            </originTimeRange>
            <magnitudeRange>
                <min>5</min>
            </magnitudeRange>
        </fdsnEvent>
        <originOR>
            <originAND>
                <magnitudeRange>
                    <min>5</min>
                </magnitudeRange>
                <originDepthRange>
                    <unit>KILOMETER</unit>
                    <min>100</min>
                    <max>200</max>
                </originDepthRange>
            </originAND>
            <magnitudeRange>
                <min>6</min>
            </magnitudeRange>
        </originOR>
        <CSVEventPrinter>
            <filename>events.csv</filename>
        </CSVEventPrinter>
    </eventArm>
</sod>

HTML XML