TABLE OF CONTENTS:
1) Mail your submission to "firstname.lastname@example.org".
2) The email Subject-line must contain at least one of the following case-sensitive strings:
"GRB", "grb", "SGR", "XRF", FXT", "XTR", "XRT", "XRB", "AXP",
"Swift", "SWIFT", "INTEGRAL", "IBAS", "KONUS", "AGILE", "Fermi", "MAXI",
"IPN", "IceCube", "ICECUBE", "ANTARES", "HAWC", "Chandra", "HST", "SDSS",
"RATIR", "VLA", "VLBI",
"IceCube", "ICECUBE", "HAWC", "ANTARES",
"LIGO", "LVC", "Virgo", "GW".
3) Your submission will be checked against the vetted list,
and you will receive a 'success' report or a 'problem' report.
4) The TITLE, SERNUM, SUBJECT, DATE, & FROM will be prepended
to the body of your email submission, and will then be distributed.
The GCN system has the capability to receive_from and distribute_to the GRB and Transient research community timely information on GRBs/transients (called GCN Circulars). These Circulars are in the prose-style (as opposed to the highly formatted "TOKEN: value"-style of the original GCN Notices). The process is simple. People can e-mail their Circulars to a central location and then those Circulars will be automatically distributed to a list of people. This list of Circular recipients is completely separate from the list of Notice recipients.
PURPOSE & MOTIVATION:
These GCN Circulars allow the GRB/transients follow-up community to make optimum use of its limited resources (labor and telescope time) by communicating what has already been done or will soon be done. This facility is also fast (~20min) and cheap (0$) for the submitter.
The procedure for submitting and distributing a GRB/Transient Circular is as follows:
1) E-mail your Circular to "email@example.com".
(And it is a wise precaution to CC your submission to firstname.lastname@example.org,
so that I am apprised of what's happening (in case something goes wrong and assistance is needed).)
2) A demon running on the "gcncirc" account will detect the incoming e-mail,
deposit it in a predefined filename, and spawn a program to process your e-mail.
3a) This program checks to make sure you are a valid submitter.
If you are not a valid submitter (you are not in the submit/receive list),
the message is transferred to the "pending" file for human intervention
at a later time.
You are notified with an e-mail message
that your submission will NOT be distributed and
there is an explanation of the possible reasons
for this and what remedies you can employ to allow a successful resubmission.
3b) If you are valid submitter, the program prepends a header (Title,
Serial Number, Date/Time of submission, an exact copy of your Subject-line,
and your identity) to the body of your e-mail.
You will receive 3 (or 4) e-mails as notification of success:
(a) a T_zero immediate email that your submission was a success,
(b) your copy of the outgoing Circular (if you have elected to receive Circulars,
(c) a generic e-mail message that your submission was successful and was distributed, and
(d) an e-mail giving the number of recipients your Circular was distributed to and the delta_time from first to last.
Depending where you are in the distribution list,
the number of entries in the list is,
and the time-of-day and machine this process is running on,
you should wait at least 2 to 3 minutes for items 'c' and 'd'.
Item 'a' should come immediately.
4) This combined text is e-mailed to everyone in the database enabled to receive.
This list of recipients (and valid submitters) is completely separate
from the the list used in the already active GCN Notices.
An example Circular is shown in the next section.
This section discusses the message format and style. An example of an Circular is shown below (between the "=======" bars):
The first six lines constitute the header that the GCN program prepends to the body of your e-mail submission (the next 33 lines in the example). The submitted e-mail is copied (without any alteration) to the outgoing Circular. The TITLE-line is fixed for all Circulars. The NUMBER-line is a unique sequential serial number assigned to each Circular. It provides a short-hand notation for reference citations in later Circulars. The SUBJECT-line in the outgoing e-mail is the same Subject-line as submitted. The DATE-line is the date and time that the Circular was processed (which is less than 10 seconds after the email was received). The FROM-line identifies the submitter (name, institution and reply address which come from the list database). After the 5 lines of TITLE, NUMBER, SUBJECT, DATE, & FROM there is a blank line and then an exact copy of the submitter's e-mail. Do NOT include these 5 lines in your submission -- they are automatically supplied by the GCN program.
In the outgoing Circular, the e-mail (sendmail) header From-line (without the colon character)will be "email@example.com" and the From:-line (with the colon character) will be "GCN Circulars". These two details are important if the recipient has any filtering or any demon active on his/her e-mail inbox. (Please note that prior to 10Sep04, the From-line used to be "firstname.lastname@example.org".)
========================================================================= TITLE: GCN GRB OBSERVATION REPORT NUMBER: 40 SUBJECT: GRB980329 VLA observations DATE: 98/04/03 07:10:15 GMT FROM: Greg Taylor at NRAO
G.B. Taylor, D.A. Frail (NRAO), S.R. Kulkarni (Caltech), and the BeppoSAX GRB team report: We have observed the field containing the proposed x-ray counterpart 1SAX J0702.6+3850 of GRB 980329 (IAUC 6854) with the VLA at 8.4 GHz on UT 1998 Mar 30.2, April 1.1, and April 2.1. Observations on April 1.1 detected a radio source VLA J0702+3850 within the 1 arcminute error circle of 1SAX J0702.6+3850. The coordinates of VLA J0702+3850 are: ra = 07h02m38.02170s dec = 38d50'44.0170" (equinox J2000) with an uncertainty of 0.05 arcsec in each coordinate. The size of this radio source is less than 0.25 arcsec. The density of sources on the sky stronger than 250 microJy at this frequency is 0.0145 arcmin**-2. The flux density measurements of VLA J0702+3850 are as follows: Date(UT) 8.4 GHz Flux Density -------- ---------------------- Mar 30.2 166 +/- 50 microJy Apr 1.1 248 +/- 16 " Apr 2.1 65 +/- 25 " where the uncertainty in the measurement reflects the 1 sigma rms noise in the image. These measurements clearly demonstrate that the radio source is variable on timescales of less than 1 day. This rapid variability is similar to that observed in the radio afterglow from GRB 970508. We propose VLA J0702+3850 is the radio afterglow from GRB 980329. Additional radio observations are in progress. =========================================================================
1) One GRB/Transient per Submission: Each message should be limited to a
single GRB/transient. If you have observations on more than one GRB/transient,
then you should divide them up into individual submissions.
The reason for the 1-GRB/transient-per-Circular request is to allow
the automated archiving by individual burst ID. All distributed
Circulars are collected into archive files based on source_name designation YYMMDDa).
If there are two YYMMDDa's in the Subject-line, then the automated
processing script gets confused.
2) Scope: The only acceptable content for the GCN Circulars falls within four areas:
2a) Observations: A report of the observations made, the conditions under which they were made, the analysis methods used to reduce the data, and the conclusions to be drawn from them. It is acceptable to discuss the differences between your results and another's results, however, it is not permitted to simply critique or editorialize another's data -- there must be new observations in each Circular. Another Circular can be issued if the analysis, interpretation, and/or results of previous data has significantly changed.
2b) Quantitative Near-Term Predictions: Theory/model-based Circulars which make predictions of developments in the burst counterpart MUST BE quantitative in nature and MUST BE near-term. Quantitative means that the prediction should have a probability (confidence level) of the likelihood that it will happen, and it should only be made if it is going to happen in the near-term (see below for definition of near-term). Examples to guide the submitter are: "the OT will brighten in the I-band by 0.5-2 mags in the next 3-5 days"; "the probability of a repeated lensed event is less than 10% in the next 2 weeks, but if it happens it will be about 3arcsec to the north of the current OT position"; or "to separate the X & Y models, the observations must be made in the I & R bands and should be taken hourly". Please note that the probability (c.l.) requirement is an attempt to get the predictor (submitter) to assess his/her certitude on the prediction, and thereby give the reader a measure to use when making future observing plans.
2c) Requests for Correlated or Cooperative Observations: Requests for observations to be made by others because of local bad weather or the need for longer-term monitoring, etc. A given site may get a 4-hour set of hourly sampled data, but due to weather, dawn or a setting target the observer can request/suggest that stations westward pick up the observation program.
2d) Future Plans: Sites can make statements about future plans for observations. An example would be "HST will image the OT plus host galaxy to X-th mag Y days from now (and the data will be made available to the public within Z hours)".
3) Near-Term: The working definition near-term is 2-4 weeks. If your predicted phenomenon takes longer than 2-4 weeks (from the current epoch), then other channels exist for communication (direct email, astro-ph, Nature, GRB/transient workshops & conferences). It should be noted that this time division is unrelated to the waveband of the predicted phenomenon. While it is true that the optical and x-ray light curves develop much faster than the radio light curve, the time frame for Circular submission still remains at 2-4 weeks. Further, since there are only a few radio instruments capable of making the critical observations (as opposed to the several dozen optical telescopes), direct communication by the person making the prediction to the appropriate persons at the radio instruments is doable (and preferred).
4) Line Length: People are encouraged to keep the line length to about 70-75 characters. The use of proportional fonts when composing a circular is discouraged. The reason being that when read by people using fixed-width fonts (a common choice) the line lengths come out a little longer, and as a result strange 1 or 2-word orphaned lines come out.
5) Line Breaks: It is now getting common that people use mailers with an editor window that automatically inserts line breaks on the screen. However, these line breaks are not actually in the message. As such, when they are received/read by people using simple-text displays, they appear as one long giant line that wraps on their screens at strange places. Please insert explicit line-breaks into your text when composing the circular.
6) Total Length: The length of Circular submissions should be kept to less than a page (about 50-60 lines). Circulars are brief statements of what was measured or what will happen (in the case of predictive-theory Circulars). For those observational Circulars that have large data sets, it is perfectly acceptable to summarize your data, state a conclusion(s), and provide a pointer to the full data set (typically a URL). For predictive-theory Circulars, it is acceptable to summarize your predictions, assumptions, major caveats, and quantative results in a short Circular and include a URL to a larger, and more detailed description (which includes all the assumptions, caveats, input numbers, etc). However, the Circulars are NOT to be used as an advertisement to some paper or web page. Any predictive-theory Circular submission must have the calculations done for the specific burst at hand (not some general calculation done previously for some "typical" burst scenario). The follow-up community does not have time to absorb a full paper -- it needs to know what to look for about the current burst, and be able to know it within a short reading session.
7) Subject-line Format: The Subject-line in your submission should be of the form "GRB YYMMDDa: " and any optional string like "optical observations", "counterpart detection", "spectroscopy", or "VLA observations", etc. So the full Subject-line should look like: "GRB 971214: optical observations". The Subject-line is copied unaltered to the SUBJECT-line in the header of the outgoing Circular.
Subject-lines that contain "RE: ", "Re: ", "out of the office", "away from my office", etc will be rejected (this is part of the infinite-loop prevention). This filtering is one of several methods used to reject people who hit the 'reply' key and automated replies from 'vacation' programs that would otherwize be interpretted as a new submission. Do not include the string "SUBJECT:" in your Subject-line; "SUBJECT:" is provided in the template the program uses to build the full Circular. There are other name templates for other kinds of transients.
8) Quality of Content: It is understood by everyone in the GCN/GRB/transient community that these reports are preliminary. While everyone makes their best attempt to submit accurate reports, these reports are also timely, based on preliminary analysis, and may be subject to change when the full analysis is done months later. See the "Corrections" section below.
9) Just the Facts: Submitters are discouraged from editorializing, debating, critiquing, etc other people's work and reports. This is not a "discussion group" nor a "chat room". Limit your submissions to just the facts of your observations, the conclusions to be drawn from your observations, plans for future observations, & requests for correlated efforts with the rest of the community. However, if your observations are in disagreement with another observation, you can of course discuss these differences in your Circular.
10) URLs & Tables: If you have observations that are too voluminous to fit within this GCN Circular framework or their format is incompatible (binary images, spectra, etc), then you should include a URL or other instructions directing the reader to these data.
In both cases (observations and predictive-theory), it is required that the pointed-to full description (e.g. URL) exist at the time the Circular is submitted. It does not serve the rest of the follow-up community if they cannot read the details of your Circular until after some time has passed. The GRB field is dynamic and the observer needs to know the full details of your prediction and calculation before he can make an informed decision about his observing plan.
11) Tabs and Special Characters: The use of tabs in producing tables is cautioned, because the recipient may have a different tab-stop setting than the one you used (tabstops of 4 and 8 spaces are common). The use of special characters (e.g. control characters) is strongly discouraged, as well are any formatting type directives (e.g. LaTeX, *roff, MSWord, etc), since it is extremely unlikely that the reader will have access to these formatting packages, especially at remote locations like telescope domes, etc. And for things like exponentiation, please use techniques like: 1.2x10^-11 erg/cm2-s or 1.2x10E-11 erg/cm^2-s, etc.
12) MIME/Mailer Stuff: The processing of the incoming circular submissions is now MIME-compliant. That means any HTML-ized duplicates attached will be ignored -- only the plain_text version will be distributed. Attachments will also be deleted from the outgoing distribution. Also, a few Circulars have been distributed with signature blocks, PGP authentication blocks, and other non-Circular_message stuff. Many people have their mailers set up to automatically include these items in all their outgoing e-mail. When submitting a Circular it helps the readership if you disable or delete these items when making a submission. (It is not possible to have the Circulars processing software remove these items with 100% confidence of not screwing up part or all of the main message. I'm working on it.)
13) References: References to previous GCN Circulars should be of the form "J. Doe, et al., GCN Circ. 270" or "J. Doe, et al., GCN Circ. 270, 1998" (where "J. Doe" is the first author, not the person given in the FROM-line). References to journal articles, books, etc, follow the standard conventions and formats.
14) Contact Information: You can list "contact" information (e.g. phone number(s) & e-mail address(s), especially if different than the address that appears in the by-line) to allow the reader to contact you for further communications. But automatic inclusion of signature blocks is strongly discouraged. Be sure to disable your mailer agent from automatically appending your signiture block onto the end of your Circular text, or manually delete it while editing your circular text.
15) Support Acknowledgements: It is quite acceptable to included statements acknowledging support (eg "This work was support by XYZ Grant #1234." or "This work was conducted using the National Hoosits Facility.", etc).
16) Citability (all are citable by default): Originally, the GCN Circulars scheme was set up with the allowance for Circulars to be citable or not citable (with a statement of such at the end of each submission). However, I suspect that this concept was not well founded. Out of the first 250 Circulars, none have been listed as "not citable". In the future, unless explicitly stated to be non-citable, all Circulars should be assumed to be citable even if the "can be cited" tag line is not explicitly included.
17) Citations: Since these GRB follow-up efforts are fast-paced, it is possible that not everyone will be aware of all previous work. The reasons are numerous: people may not have access to their normal or full e-mail accounts, they have just spent the last two hours furiously analyzing their own data, it's 5 o'clock in the morning and the mind is somewhat frazzled by lack of sleep, etc. As such, a reference to prior work may be innocently left out of the current Circular. While everyone will make an honest effort to be current and to cite prior work, it is understood that some omissions will inevitably happen.
18) Writing Style: Please remember that this media (e-mail) does not lend itself to a wide latitude of inter-personal communications. That is to say, the reader does not have access to the writer's "tone of voice", facial expressions, nor (in some cases) knowledge of the writer's personality. So a casually used phrase might be taken the wrong way by the reader. Please keep your writing style to that used in scientific journals.
Outgoing: Currently, there is no ability to filter outgoing Circulars based on any type or category (e.g. optical, radio, x-ray). I was not able to devise any clean way which would work via the e-mail submission method which did not require a lot of thought and effort on the part of the submitter. (The web-page form submission method is much easier on this, but the e-mail method required the user to know predefined keyword tokens that would be used in the filtering process.) At the present time, the number of Circulars being distributed is small enough so as not to overwhelm the recipient (2-5 per average burst/transient in the 1990's; and now 5-20 per burst/transient in the 2010's).
Incoming: In addition to the checking to see if the current incoming
submission is from anyone in the pre-approved vetted list of submitters,
there are other checks made. The Subject-line must contain one of the
"GRB", "grb", "SGR", "XRF", "Transient", "transient", "Swift", "AGILE", "Fermi", "INTEGRAL", "MAXI", ... see the full list at the top of this page.
(Strings that are no longer in the list: "SAX", "HETE", "GLAST", ....)
Commonly, there will be a "GRB yymmdda" string, so that the auto-archiver demon will know which burst-specific or source-specific archive file to append it to. If the Subject-line does not contain one of these strings, the submitter is notified by with an e-mail message that the submission failed and will not be distributed. There are also several checks made to prevent infinite loops. People's use of the "vacation" program (and similar programs) plus bounced e-mail all provide the possibility to set up an infinite loop within this automated service. These checks are not fool-proof, so the possibility exists of initiating an infinite loop. As a stop-gap to that situation, the demon limits submissions to no more than three per 100 seconds. It should be noted that it is theoretically possible (but very improbable) that four people could submit within a 100sec interval. Should this happen, the fourth submission to arrive at the capella2 machine would not be distributed and the submitter would be notified as such with an explanation. (The notification offers suggestions about what to do about the various reasons why your particular submission was rejected -- two of which are the "GRB" string requirement in the Subject-line and this very rare submission-rate limitation.)
BECOMING A MEMBER:
To receive or submit to this GCN Circular list, you must first be added to the list. It is this vetting process that protects against spam (i.e. junk mail) and adds some veracity to the contents of the messages (i.e. no spoofers). There are no restrictions to being added to the list -- all you need do is send a request to the GCN operator (email@example.com). If you think it is unlikely that I would already know you, it would be helpful to me if you would include with your membership request a couple sentences explaining who you are, what type of work you do, why you are interested in GRBs, etc. It's not much -- just a few sentences to help me understand the membership so as to better operate the system to suite the communities needs.
The following pieces of information are needed for the list entry:
1) Your name: John Doe
2) Your institutional and/or project affiliation: GSFC
3) The e-mail address you want the Circulars sent: firstname.lastname@example.org
4) Your account name you will be using for submissions: jdoe
5) The domain you will be submitting from: llnl.gov
6) A flag enabling(=1) the entry to receive Circulars: 1 or 0
Items 4 & 5 are used in the validation checking process for incoming Circulars. Item 3 is the address you want to receive the Circulars. The account-names in items 3 and 4 can be different -- this is common for large institutions that have generic aliases for their personnel for incoming e-mail (e.g John.Q.Doe@gsfc.nasa.gov). Items 1 & 2 are used in the FROM-line in the header attached to all outgoing Circulars to clearly identify the author/submitter. Item 3 is also used on the FROM-line to aid the reader if he/she wishes to respond back to the submitter.
Or go to sign up for Circulars.
By requiring that the incoming submission come from a prearranged account_name (e.g. jdoe) and a domain (gsfc.nasa.gov), this rejects spam and random submissions from, say, highschool kids in Germany. By making the domain restriction at the institutional level instead of the machine level, the submitter can use any machine within that institution (however, the acct_name must be the same on all of those machines, which is common but not ubiquitous). To handle the situation where a person might be submitting from multiple machines which have different acct_names or different institutional-level domains, that person can have multiple entries in the list (one for each acct_name and/or institutional domain). And if that person does not want to receive multiple copies of the Circulars, then item 6 allows for the 2nd, 3rd, etc entries to be disabled from receiving outgoing reports (0=disabled, 1=enabled to receive). Of course much of this is overkill, because it is easy for a person to remotely login to their prearranged machine to submit. However, the capability is in place to handle those situations where that is not possible or convenient.
1) Operator's Notes: On very rare occasions a "GCN Operator's Note" may be appended onto the submitter's Circular. These Operator's Notes will be clearly identified so as not to be confused with the submitter's message. There are two sub-classes of these attached notes: (1) real-time attachments, and (2) post-distribution attachments in the archived copies. The real-time attachments are used to: (a) to clarify a Circular that is being distributed after some delay because it did not initially satisfy the automated validation process for some reason and, therefore, required intervention by the operator, or (b) to make some general announcement of interest to the GCN community. (This would be a pre-arranged announcement. It is picked up by the program processing the next Circular submission, and so causes no delay in the distributions.) The post-distribution attachments are edited into the archived copies of the Circulars. They usually pertain to some correction communicated to the Operator by the author.
2) Corrections: Authors may find that after they have submitted a Circular they have made a mistake, a typo, an omission, etc in their Circular. There are two courses of action: (1) For minor problems it is sufficient to email the Operator with an explanation of the problem and the correction. The Operator will correct the problem in the archived copy of the Circular along with "[GCN OPS NOTE:]" explaining that a correction was made. Or (2), for more serious problems, the authors can submit a new Circular explaining the problem and the correction (and a citation back to the original Circular), or resubmit the entire (but corrected) Circular again -- with a prefatory remark stating the the corrected information. These corrected Circulars should be submitted as soon as possible, so the community is appraised of any modifications which might affect their observing plans. As of Jan 99 (~240 Circulars), there have been several instances of each type.
3) Updates: Updates to previously submitted Circulars are permitted. As the observers collect more data (e.g. another night's worth) or if additional analysis is applied to the original data (e.g a more accurate magnitude referencing standard), an updated Circular can certainly be submitted. Whether or not the original data is included in with the new data depends on the amount and type. Certainly for a small set of numbers (e.g magnitudes, fluxes, etc) or for clarity in recognizing a trend, the old data should be included.
4) Turn-around Time: Because the intent of the GCN Circulars is
to disseminate observational results (the main thrust) to the follow-up
community, so that they can know what is going on and what has happened
with the source, I strongly encourage the observer/submitter to submit
his/her data with all possible speed. I have noticed (as have others)
that some of the observational Circulars are being delayed by 1, 2, 3 days,
even a week(!) after they were made. Some of this may be motivated
by the desire to beat down the last 1 or 2 tenths of a magnitude uncertainty
(to use the optical band as an example). If the result that the OT
is at 23 mag comes out 2 or 3 days after the fact, then many
small-telescope observers will waste their precious telescope time
chasing after something that they will just get an upper limit on.
The GCN Circulars are not a formal publication mechanism. As such,
the standard for accuracy and veracity is not as high as Nature or ApJ (say).
You are expected to be thorough and accurate, but people also understand
that they will get some increase in errors with an increase in
distribution speed, and they expect/accept that. A quick rough value
is worth more than a fine-tuned but delayed value.
5) Web-page Submission Method: The Web page submission form is not implemented yet, because I have not devised a way for the submitter validation to be clean and simple. This method may be added in the future. However, I do not expect that this lack will generate too much hardship, as the e-mail method satisfies most needs and is a more ubiquitous method available to the user-community anyway.
6) Archives: All the Circulars are archived in the GCN web site. Currently, this is done within the Circulars archive page (on a serial_number sequential basis), and on a event-by-event grouping basis in the Bursts/Transients of Special Interest page.
7) Size of List: As of 18 Jun 98, there were 270 people in the vetted submit/receive list. With 270 people it takes about 3 minutes to distribute the individual e-mail messages. As of 30 Jan 99, there were 335 in the list; 476 as of 28 Jan 01; 550 as of 01 Oct 01; 801 as of 19 Sep 04; 903 as of 12 Dec 05 (takes 15 min to distribute all 903). But then with the faster machine and the dynamic load-throttling algorithm, the time is 1.5-2.0 min for 965 recipients (as of Sep 06). But then security checking in the internet has slowed things. As of Jun 2020, the time is 19-20 min for a single Circular, and 22-35 min with two simultaneous Circulars in distribution.
8) Acknowledgements: This GCN Circular service has benifited from numerous discussions and beta-testing with many people, most notably Roland Vanderspek, Ralph Wijers, James Rhoads, and Hye-Sook Park, plus the people at the 4th Huntsville GRB Workshop evening SIG session and the Woods Hole GRB Workshop.
9) Programming: The programming for this GCN Circular e-mail
exploder service is custom. The various e-mail exploder programs
available (listproc, majordomo, elm, sendmail, and others) all had one
problem or another, and did not match all of our needs.
10) Community Mindedness:
This GCN Circulars system is (and has to be) a self-policing relationship.
Since the system is automated, there can be no single-point editorial
filtering. If an individual goes beyond the guidelines too many times,
they will likely incur the loss of respect from the GRB follow-up community.
These are obvious concepts, but sometimes they need explicit statement.
REQUEST FOR COMMENTS:
Nothing is cast in concrete. This is an evolving system and must meet the needs of the community. If you don't like it, you won't use it and it will die. Suggestions of changes and comments are always welcome (contact).
The Theory Content Discussion (back in the early days):
Please see the request for comments (RFC)
on the discussion of proper content for these Circulars
(i.e. Are theory-content Circulars to be allowed). [31 Jan 99]
Also see the addendum to the RFC. [04 Feb 99]
And see the Results of the RFC. [16 Feb 99]