There were no changes in functionality requested by WGIII.
Chad has added some clarifications to the documentation of the various services motivated by comments received from the working group. The following items summarize these changes
2013/10/04 – 1.1 release candidate
1) Add description and clarification for the columns of the text formats for fdsnws-station and fdsnws-event.
2) Avoid ambiguity of required parameters by re-naming the appropriate column “Support” and changing the values to “Required” and “Optional”.
3) Add another example request to the fdsnws-event interface illustrating a query for text data and a portion of the response that might be expected.
Since there were no real changes in functionality, please have any comments back to the WG by next Monday 10/21/13. We will put this version up on the FDSN web site next
Monday assuming we hear of no objections.
Cheers
Tim
Dr. Tim Ahern
FDSN Archive for Continuous Data
International Federation of Digital Seismograph Networks (FDSN)
c/o IRIS DMC
1408 NE 45th Street #201
Seattle, WA 98105
(206)547-0393 x118
(206) 547-1093 FAX
can I suggest to add a couple of small notes to clarify best practices:
* I think an additional note to the "format" parameter that states that the "format" parameter is the only way to change the default output format is a good idea. In other words: If no "format" parameter is given, a client can be sure that the format is the default format. This eases client development and is mostly the case anyway but I have seen otherwise, e.g. an event service that has a "kml=(true/false)" parameter.
* I believe the WADLs should always contain the long versions of the parameter names. Again this eases client development as more assumptions can be made.
* Furthermore I would require non-standard parameters specified in the WADLs to have a type and potentially a short description. In future versions of the standard XSD schemas could be provided.
All the best!
Lion Krischer
On Oct 14, 2013, at 18:54 , Tim Ahern wrote:
Members of WG III
There were no changes in functionality requested by WGIII.
Chad has added some clarifications to the documentation of the various services motivated by comments received from the working group. The following items summarize these changes
2013/10/04 – 1.1 release candidate
1) Add description and clarification for the columns of the text formats for fdsnws-station and fdsnws-event.
2) Avoid ambiguity of required parameters by re-naming the appropriate column “Support” and changing the values to “Required” and “Optional”.
3) Add another example request to the fdsnws-event interface illustrating a query for text data and a portion of the response that might be expected.
<FDSN-WS-Specifications-1.1RC.pdf>
Since there were no real changes in functionality, please have any comments back to the WG by next Monday 10/21/13. We will put this version up on the FDSN web site next
Monday assuming we hear of no objections.
Cheers
Tim
Dr. Tim Ahern
FDSN Archive for Continuous Data
International Federation of Digital Seismograph Networks (FDSN)
c/o IRIS DMC
1408 NE 45th Street #201
Seattle, WA 98105
(206)547-0393 x118
(206) 547-1093 FAX
1. For time series and catalog searches, I think it would be preferable
to specify a half-open time interval:
[start_time ... end_time)
which means:
start_time <= interval < end_time
rather than
start_time < interval <= end_time
Otherwise, there is no good way to specify non-overlapping time intervals.
2. For time specifications, I would recommend allowing ISO 8601 ordinal
dates, eg:
YYYY-DDD
YYYY-DDDTHH:MM:SS
YYYY-DDDTHH:MM:SS.ssssss
in addition to the ISO 8601 calendar dates.
3. Table 1 is incomplete.
"longestonly", "quality", minimumlength" used in fdsn-dataselect do
not appear in Table 1 (used in fdsn-dataselect).
Therefore, their types, allowable values, and defaults are never defined.
4. Text output (for fdsnws-event and fdsnws-station) is not well defined.
a. How do you include a vertical bar | in a field?
b. Is it permissible for any field (or all fields) to be empty?
c. In fdsnws-event, if format=text is specified, does this imply that
the following are invalid (or ignored)?
includeallorigins
includeallmagnitudes
includedarrivals
5. The meaning and use of "includeavailability" in fdsnws-0sstation
is not well defined.
a. Does this mean include detailed waveform availability for each
channel in the specified time, just a single min and max time for
any waveform in that time interval?
b. Can the waveform starttime be before the time inteval,
and can the waveform endtime be outside of the time interval?
b. Do you output this info only if "level=channel" is specified?
c. Do you output this information for every discrete segment of
time series data for the channel?
d. How do you represent this info when "format=text" is specified?
6. What does "matchtimeseries" specify?
Need better definition of "where selection matches time series data
availability". Does this mean that you output a metadata segment
iff there is any time series data in that interval, or that you limit
the metadata interval to match each discrete time series segment?
- Doug N
--
------------------------------------------------------------------------
Doug Neuhauser University of California, Berkeley
doug<at>seismo.berkeley.edu Berkeley Seismological Laboratory
Office: 510-642-0931 215 McCone Hall # 4760
Fax: 510-643-5811 Berkeley, CA 94720-4760
Remote: 530-752-5615 (Wed,Fri)
1. For time series and catalog searches, I think it would be preferable
to specify a half-open time interval:
[start_time ... end_time)
which means:
start_time <= interval < end_time
rather than
start_time < interval <= end_time
Otherwise, there is no good way to specify non-overlapping time intervals.
I agree that such functionality is important, as this would effect every service I suggest we discuss this in the context of the specification after 1.1.
The use case of non-overlapping intervals for the purposes of dove-tailing the results makes sense. At the DMC, and I would guess more broadly, most requests are independent of other requests and are not destined to be combined with other results. In these cases an inclusive end time makes sense, so we really have two conflicting use cases.
Instead of changing the meaning of the endtime parameter, we might consider adding an alternate end time parameter defined as non-inclusive. For example: "endtimeexclusive", could be such an alternate end time specifier and used to define half-open intervals.
2. For time specifications, I would recommend allowing ISO 8601 ordinal
dates, eg:
YYYY-DDD
YYYY-DDDTHH:MM:SS
YYYY-DDDTHH:MM:SS.ssssss
in addition to the ISO 8601 calendar dates.
These two time conventions are easily converted on either the server or client end. In my experience more-quickly-discovered errors and errors with less significant impact occur when leaving it on the client end. In this case the "syntactic sugar" is not worth it in my opinion. It would be interesting to hear perspectives from others on the working group.
3. Table 1 is incomplete.
"longestonly", "quality", minimumlength" used in fdsn-dataselect do
not appear in Table 1 (used in fdsn-dataselect).
Therefore, their types, allowable values, and defaults are never defined.
Thanks for the careful read, I will remedy that in the specification.
4. Text output (for fdsnws-event and fdsnws-station) is not well defined.
a. How do you include a vertical bar | in a field?
You do not, any that exist in the metadata fields should be replaced with something else.
b. Is it permissible for any field (or all fields) to be empty?
For the DMC's services yes.
c. In fdsnws-event, if format=text is specified, does this imply that
the following are invalid (or ignored)?
includeallorigins
includeallmagnitudes
includedarrivals
For the DMC's services yes.
I would not oppose adding a bit of clarification to the specification regarding these issues if no one objects.
While we should clarify format details that will cause incompatibilities, I recommend against trying to work out a very strict formalism or extensions to allow the text output to serve more use cases; the text output works very well for a large number of common use cases where simpler is better. If we need something more flexible and formal, containing information between the levels provided by the XML and text, I would recommend we spend our effort defining or adopting a JSON-based output.
5. The meaning and use of "includeavailability" in fdsnws-0sstation
is not well defined.
a. Does this mean include detailed waveform availability for each
channel in the specified time, just a single min and max time for
any waveform in that time interval?
In StationXML the data availability extension includes the capability to specify either: details of specific segments and/or extents (min/max). This is left intentionally up to the data center regarding what level of detail is included, the reason being that each data center has different capabilities of reporting these details.
b. Can the waveform starttime be before the time inteval,
and can the waveform endtime be outside of the time interval?
Yes?
b. Do you output this info only if "level=channel" is specified?
Again, seems like a detail that might depend on data center capability and desires. StationXML is capable of reporting data availability at Channel, Station and Network levels.
c. Do you output this information for every discrete segment of
time series data for the channel?
Up to the data center.
There is currently no mechanism to request "degree of detail" for data availability information or "level at which to report", to properly address these questions I think we need either more parameters or values for the existing 'includeavailabilty' parameter.
To sum up, the current specification leaves it up to the data center what degree of detail and at what level of information data availability is reported. You are free to suggest extensions for consideration that would allow more explicit requests for availability.
At the DMC we currently only include data availability information at the channel level and then only the extents. Our ability to report data availability will evolve over time and we hope to provide more detailed information in the future. So we will be interested in refining this part of the specification, and would be happy to work with others on the best approach.
d. How do you represent this info when "format=text" is specified?
You do not.
6. What does "matchtimeseries" specify?
Need better definition of "where selection matches time series data
availability". Does this mean that you output a metadata segment
iff there is any time series data in that interval, or that you limit
the metadata interval to match each discrete time series segment?
Neither. The intent of matchtimeseries is: In addition to matching metadata based on selection criteria, the results will be further limited to metadata for which the criteria also match the existence of available time series data.
The idea is to prepare for a time series data request. For example, a client can request metadata for a number of channels intersecting a one hour range and by specifying matchtimeseries=TRUE has a reasonable expectation that time series data is available networks/stations/channels of metadata returned.
I will clarify the original intent in the specification.
Chad
- Doug N
--
------------------------------------------------------------------------
Doug Neuhauser University of California, Berkeley
doug<at>seismo.berkeley.edu Berkeley Seismological Laboratory
Office: 510-642-0931 215 McCone Hall # 4760
Fax: 510-643-5811 Berkeley, CA 94720-4760
Remote: 530-752-5615 (Wed,Fri)
_______________________________________________
fdsn-wg3-products mailing list
fdsn-wg3-products<at>iris.washington.edu http://www.iris.washington.edu/mailman/listinfo/fdsn-wg3-products