One of the challenges we faced was the need to interface the SEED representations of seismic data with the css3.0 representations of seismic data. Note that SEED is not, nor has it every been, a relational database. It is possible to map a relational database schema to some of the SEED data structures, but generally this is difficult to do. Instead SEED is an exchange format with defined binary data structures and documentation of how the fields in these data structures should be used. Probably the biggest challenge we faced with interfacing SEED with the css3.0 schema was in the basic naming conventions used to identify channels of waveform data. css3.0 uses a naming convention where a single unique channel of waveform data is named with a combination of a station code (sta) and a channel code (chan). In the css3.0 schema, the sta code is not longer than 6 characters and the chan code is not longer than 8 characters. SEED uses a naming convention where a single channel of waveform data is named with a combination of four codes; a 2 character network code (snet), a 5 character station code (ssta), a 3 character channel code (schan) and an optional 2 character "location" code (sloc).
Unfortunately, we could not follow this same approach for mapping the SEED snet and ssta codes into a single css3.0 sta code. The problem is that the css3.0 sta attribute can be no longer than 6 characters. Since the SEED snet code is 2 characters and the SEED ssta code can be up to 5 characters, we would need sta to be 8 characters long to map a 2 character snet code and 5 character ssta code in the same manner as we did with the SEED schan and sloc codes. At the time we first did this, since ssta codes were "generally" unique by themselves and since most network operators were used to using a single sta code to represent their station location, we just dropped the snet code in the mapping of SEED to css3.0, i.e. for SEED snet, ssta the css3.0 sta code = ssta. This did not provide either a unique or reversible transformation. However, it usually worked in situations where it was not necessary to transform from css3.0 back to SEED. In the early Antelope code base, these mappings were hardwired.
As Antelope evolved it became apparent that we needed a more robust way to make the SEED to css3.0 mappings completely unique and reversible. We accomplished this by introducing two new tables into the css3.0 schema; snetsta, for mapping SEED snet and ssta codes into css3.0 sta code, and schanloc, for mapping SEED schan and sloc codes into css3.0 chan codes. We preserved the schan, sloc to chan code mappings as before, but these mappings are recorded in the schanloc database table and the mappings could be changed by the user if desired. We also preserved the snet, ssta to sta code mappings, but these mappings are now recorded in the snetsta table so that the reverse mapping from css3.0 sta to SEED snet, ssta is supported. Also, with the css3.0 snetsta table, we could check to see if a new SEED ssta code matched a previous code but with a different snet. In those cases it is possible to make a new unique css3.0 sta alias to preserve the different snet-ssta combination. All of this was typically handled through a new software library, the so called foreign keys library documented in foreign(3), that made up new aliases automatically according to a set of rules. Although this approach allowed for automatic mappings that were always unique and reversible within a single database, the aliasing of the css3.0 sta code did not always provide globally unique and reversible transformations across multiple databases. The best solution to this problem would be if the css3.0 sta code attribute was long enough to accommodate the same kind of mapping as we used with the css3.0 chan code.
In the 5.2 release of Antelope we have included a new css3.1 schema definition. You can run 'dbhelp css3.1' to get a detailed listing of the changes. The sta attribute in css3.1 is 14 characters, more than enough to accommodate the same kind of globally unique and reversible mapping we have been using for the chan attribute. The chan attribute in css3.1 is 15 characters long. This provides a means for concatenating processing identification strings, such as for beam forming or filtering, onto the chan code of the raw data to uniquely represent processed data. There are many other changes as well that all involve expanding the css3.0 attribute sizes. The one place where we made a name change in css3.1 was that we added a new prefmag attribute to the event table. We use the css3.1 schema in the original 5.2 version of the GSN demo.
Why would you want to use css3.1? One reason is to make use of an unambiguous and globally unique and reversible mapping of SEED snet, sta to css3.1 sta codes. One possibility is to map SEED snet, ssta codes to css3.1 sta = SEED snet_ssta, in the same manner of the chan code mapping. This would result in css3.1 sta codes that look like II_PFO, for station PFO in network II, as an example. This makes it easy to form database queries that involved SEED network codes. For instance, using this mapping you could see all of the IU network stations with something like 'dbpick -sc IU_.* mydatabase'. This is a lot easier than doing the join of the site table with the snetsta table and sifting of the snet code. Also, in display programs like dbpick you can see immediately which network a particular station belongs to. Other places where css3.1 would be useful is in any situation where you need the more precise time stamps or locations and in situations where you want to archive processed data that has been tagged by appending processing strings onto the raw css3.1 chan codes.
One simple way to preserve compatibility across css3.0 and css3.1 databases is to stick to the original sta name mapping definitions in your css3.1 databases. In order to preserve compatibility, the Antelope code base by default will use the old sta name mappings in css3.1 databases. If you really want to switch to the new expanded sta name mapping, then it is advisable to convert all of your existing css3.0 databases to css3.1 databases while simultaneously converting the sta name mapping. This can be done with cssconvert(1), as we will demonstrate.
If you decide to use the expanded sta name mapping for your css3.1 databases, you will also need to consider how new SEED channels of data get included into your css3.1 databases. We define a new SEED channel as one that is not already in the database and therefore not referenced in the snetsta table. This can happen in a real time system when new data channels appear in one or more data streams. When a new SEED snet-ssta combination is seen, the Antelope foreign key routines will automatically generate a new entry in the snetsta table for the new data. the name mapping that Antelope will use is defined in the trdefaults.pf parameter file (see trdefaults(5)). We have preserved the default behavior to be that of the original old name mapping. Therefore, if you are acquiring new unseen data into your css3.1 system which already has sta codes generated using the expanded sta code mapping, and you have not changed trdefaults.pf from the default version, the new sta codes will use the old style sta code mapping. In order to avoid this behavior, you will need to modify the seed_net_sta table in trdefaults.pf to look like this:
seed_net_sta &Tbl{ # pattern substitution # net_fsta sta # The following pattern maps SEED snet, ssta to css sta = snet_ssta (.*)_(.*) $1_$2 }
You should put this modified trdefaults.pf file in the pf directory of your rtexec instances. We do not recommend changing the trdefaults.pf file in $ANTELOPE/data/pf since that would make it difficult to acquire and write out new css3.0 databases throughout your system.
Aside from the sta name mapping issues, many of the real-time Antelope software modules have been modified to be able to switch database schemas on-the-fly. For instance orb2dbt(1) can take css3.0 external origin rows, generated by dborigin2orb(1), and properly merge them into a css3.1 output database. In this example sta name mapping is not important because the sta field is not in the origin rows produced by dborigin2orb(1).
If you decide to switch to the new expanded sta name mapping, all of your css3.1 sta codes will look different from what they were previously in your css3.0 databases. This means you will have to find everyplace where you had to specify a css sta code in the various parameter files in your real-time processing systems and modify these to reflect the new sta codes. An example is ttgrid.pf.
You should get into the habit of always using database descriptor files instead of depending on the default behavior of assuming databases are of schema css3.0 (we did not change this default behavior). Programs like seed2db(1) will write out css3.1 databases as long as you provide a database descriptor file for for the output database. You can generate css3.1 metadatabases from dataless SEED data with either sta name mappings, depending on trdefaults.pf, by running seed2db(1) with a preexisting output database file descriptor that specifies the css3.1 schema.
If you are using the expanded sta name mapping, it is important that you use css3.1 as the schema for the temporary databases create by orbassoc(1). This is done by the schema parameter in orbassoc.pf.
cssconvert(1) foreign(3) trdefaults(5)