TNS - Getting started

 

Newsfeed


Japanese (partial) translation


 

General

As of January 1, 2016, the Transient Name Server (TNS) is the official IAU
mechanism for reporting new astronomical transients (ATs) such as supernova
candidates. Once spectroscopically confirmed, new supernova discoveries are
officially designated a SN name (of the form SN 2016A and so on, as before).
This is a continuation of the IAU naming scheme for supernovae which was
handled by the Central Bureau for Astronomical Telegrams until the end of 2015, 
and has been approved as the official IAU naming scheme by the IAU Executive 
Committee from 1st January 2016.

Variable stars and CVs, including in particular Galactic nova candidates, should
be reported in the same manner done prior to January 2016, and should not be
submitted to the TNS.

This service is provided by the IAU supernova working group, free of charge to
registered users, who can also choose to receive automated email alerts
regarding new discoveries.

If an event is not already known at the reported coordinates, a new name
is provided and this will serve as the formal unique designation of the
transient.

If an object already exists in the system at the reported location, the AT
report and its details will be formally saved (and associated with the existing
object), and the object's (existing) designation will be reported back.

A name of the form, e.g. 2016ab, defines the object uniquely. Before it is
spectroscopically classified it will have a prefix of "AT". If classified as a
SN of whichever type, the prefix changes to "SN".

[ Top ]

 

Registration, reporting methods

Submitting reports of any kind requires registration for a user account. This
registration will be open to all professional astronomers as well as to
amateurs.

To register, go to Login / Create new account.

AT reports (AT reps) and Classification reports (Class reps) can be submitted to
the TNS either by interactive forms (for individual users; this replicates
exactly the previous system) or via the Bulk reports method - submission of
JSON-formatted data or TSV lists in an automated way from defined machines
(we call "BOTS") of e.g. the various involved surveys.

[ Top ]

 

Email notifications

A registered user can define the notifications he/she wishes to receive from the
system. In the MY ACCOUNT page it is possible to specify if you wish to receive
immediate notifications or either a daily digest, for discovery and/or
classification reports, with the option to define a magnitude cut.
It is also possible to choose to receive immediate notifications whenever a new
transient is found to be coincident with sources of external catalogs. Currently
the KEGS catalogs are active; more catalogs will be added over time.

[ Top ]

 

NASA ADS indexing

All the TNS discovery & classification reports (those that serve as the formal
"discoverers"/"classifiers") are now officially indexed on the NASA ADS system.
The bibcodes of the TNS reports begin with either YYYYTNSTR... or YYYYTNSCR...;
TR standing for Transient (discovery) Report, CR standing for Classification
Report. The reports are arranged as daily aggregates per the reporting group and
reporter name/s (author/s).

Querying the ADS by object name (e.g. 2016A) or author/s retrieves any relevant
TNS reports, so they can be officially related to and cited.

On the ADS - for an index of a single object, clicking the "Electronic On-line
Article" directs to the discovery/classification certificate on the TNS. If an
aggregate report for multiple objects, clicking the "On-line Data" directs to
the aggregate report on the TNS, which includes links to all objects' pages and
certificates.

Note that the indexes are updated on the ADS only once per week, every Mon/Tue.

[ Top ]

 

Report forms

The interactive forms open from the REPORTS menu item, where there are two
 tabs, for the AT report and the Classification report forms.

Mandatory fields are marked with red asterisks.

AT rep: After the header section, a photometry section exists, where a last
non-detection should be specified, followed by specification of the discovery
photometry point (mandatory). Additional photometry points may be provided, as
well as any "related files" to go along with the AT rep (finding chart,
discovery image etc…).

If an instrument/filter/flux units are not found in the pop-down lists, The
value "Other" should be chosen, and the details should be described in the
following Comments field (e.g. Instrument=XXX, filter=XXX). The same holds for
the Class rep form.

Class rep: It is mandatory to provide at least one spectrum (for supporting the
classification); additional ones may be uploaded as well, and also here, any
relevant related files.

[ Top ]

 

API - Bulk reports

The Bulk API method allows for submission of AT or Class reports to the TNS via
JSON-formatted data or TSV (Tab-Separated-Values) lists in an automated way
from defined machines (BOTS) of e.g. the various contributing surveys.

The Bulk reports are being processed as promptly as possible in an
asynchronous mode, dependent on the actual incoming queue of reports and 
the server’s available resources.

We have set up on our SANDBOX site an API TEST FORM webpage where it is
possible to experiment with submission of reports using a dedicated form.

The development of the required codes and the experimentation with submission
of bulk reports should be done only against the SANDBOX environment.

Only after verifying that your JSON/TSV reports are submitted and 
processed in acorrect manner should you direct the submission of your 
reports to the real site.

 

A detailed manual of the Bulk API in pdf format can be obtained here.

Sample codes for using the API can be downloaded here: PHP, Python.

Templates of the TSV lists are up on the SANDBOX BULK page.

[ Top ]

 

API - Change proprietary period

This API serves for updating the prop. period end date of reported entries, for
switching an AT report and/or classification report and/or spectra to public,
either on the same day or some future date (back-dating is not possible).
Only a bot that is associated with the group that submitted the report
(AT/Classification/spectra) can request to perform such a change to the prop.
period end date.

 

A detailed manual of the APIs in pdf format can be obtained here.

Sample codes for using the API can be downloaded here: PHP, Python.

[ Top ]

 

API - Search/Get objects

The Search API serves for listing the object names (objname & prefix) satisfying
given search criteria.

The Get Object API retrieves object details per given object name, including its
associated photometry and/or spectra if requested.

Retrieving specific files (e.g. spectra ascii/FITS files) is possible via the
Get File API.

 

A detailed manual of the APIs in pdf format can be obtained here.

Sample codes for using the API can be downloaded here: PHP, Python.

 

The Search/Get APIs can also be implemented by single-line curl cmds, e.g.:

  • curl -X POST -H 'user-agent: tns_marker{"tns_id":YOUR-BOT-ID,"type": "bot", "name":"YOUR-BOT-NAME"}' -d 'api_key=YOUR_API_KEY&data={"objname": "2021rf"}' https://www.wis-tns.org/api/get/search
  • curl -X POST -H 'user-agent: tns_marker{"tns_id":YOUR-BOT-ID,"type": "bot", "name":"YOUR-BOT-NAME"}' -d 'api_key=YOUR_API_KEY&data={"objname": "2021rf", "photometry": "1", "spectra": "1"}' https://www.wis-tns.org/api/get/object

(Copy/Paste from your Bot's edit page the required tns_marker string to put in the User-Agent section. You can clearly also specify the appropriate browser User-Agent.) 

We also want to point to a shell script utility kindly provided by Prof. Shri
Kulkarni in AstroNote 2021-4, which may be found convenient for searching and
downloading the reported events on the TNS for requested months in a given year.

[ Top ]

 

Rate-limit (Quota)

As part of improving the control over the activity against the TNS, to prevent
overloads, a Rate-Limit (quota) mechanism is in place for controling the amount
of requests that are allowed within a duration of 60 sec (a running window),
according to the type of action and the source - whether a logged-in user, a
guest or a Bot. The submission of bulk reports (discovery / classification) and
the retrieval of the replies are excluded from the Rate-Limit mechanism; we
clearly do not want to delay the live submission of reports.

The main principles behind the decision on how many requests should be allowed
per duration window are as follows:

- Cone searches create heavier load, therefore a smaller number is allowed.

- Bots receive a higher Rate-limit. Anonymous users (not logged in) receive a small
allowed Rate-limit.

- Exceeding the Rate-limit will result in a "429 - Too Many
Requests" error code.

For additional details on the Rate-limit mechanism and how to handle this,
please refer to the following NewsFeed.

Also note that the provided sample codes (see the APIs section above) also
contain examples on how to relate and respond to the Rate-limit.

[ Top ]

 

Groups, Proprietary period

Every registered user can create a new group (GROUPS menu item). Details of
the group should be filled in, including up to three group owners. Upon approval
of the group by the TNS administrators, users can ask to join the group, for the
group's owners to approve. A group can then be specified as the "source group"
for a reporting (Discovery/Classification), or be specified for sharing
private/proprietary data only among it's members as described below.

For both the AT rep and Class rep it is possible to request a proprietary
period.

The data will then be visible and accessible only to members of the defined
"source group" and/or "associated groups".

For an AT rep, requesting a proprietary period means that the object is created
but will not be visible to non-members of the relevant group/s, unless other
people/surveys report the same event without requesting a proprietary period, or
one that expires sooner.

For Class reps, it is possible to request a proprietary period separately for
the classification itself (typing+redshift), or for the uploaded spectrum/a.

[ Top ]

 

"Discoverer" / "Classifier"

With respect to the proprietary period options just mentioned, the formal
"discoverer" of a transient is defined to be the reporter/s whose discovery report
first turns to public (or was immediately so). Likewise for "classifier".

[ Top ]

 

Search page

From the SEARCH page it is possible to perform all sorts of queries on the
existing objects.

E.g. clicking the "Unclassified ATs" checkbox will list all reported ATs
that are not yet classified.

The page initially loads with a default query parameter (at the top): Discovered
Within the Last 1 Months. If willing to perform queries without any limitation
on the discovery date range, this field can just be cleared (left empty) or set
to 0 (zero).

For each entry (object) in the retrieved list it is possible to open up
sub-tables displaying the related AT/Class reps and the spectrum/a if exist
for the object. Clicking on an object name directs to the Object page (e.g.
https://www.wis-tns.org/object/2016A), where the details of the
object are shown, as well as interactive spectra plots.

Clicking on the icons under the Reps and Class columns link to the formal
"certificates" of the discovery and classification, respectively. These replace
the former supernova CBET telegrams, and are citable and officially indexed on
the ADS.

Links of the form
https://www.wis-tns.org/object/2016A/discovery-cert or
https://www.wis-tns.org/object/2016A/classification-cert
lead to these certificates, which are available free of charge to anyone.

In case a correction has to be performed for a submitted AT report: If being the
sender of an AT-report, or either an owner of the relevant group/bot that sent
the report, it is possible to click on the AT-rep id (in the AT reports
sub-table) for updating some of the AT-rep details: The Reporters (authors list),
Source group, Internal name, Host name/redshift and the requested proprietary
period (if a proprietary report).

Note the additional query options under the "Advanced search" section, and
also the possibility to define which columns to display or hide.

[ Top ]

 

Statistics page

Our STATISTICS page, linkable from the TNS homepage, consists of 3 tabs for
viewing the following:
- The amount of transients, ATs and classified SNe, that have been reported 
to the TNS, by different cuts and for the top contributing groups.
- Timeline (history) plots of the received AT and classification reports. 
(Hovering on the data points reveals relevant information for the given date.)
- Full-Sky maps showing the projected locations of the reported
transients; by types and groups.

[ Top ]

 

LIGO GW Events

For every new GW event, alerted on by the GCN/LVC, we create sky maps
showing the localization contours, with all known public TNS transients that
are within the error regions over-plotted. We provide a map showing all
transients with discovery date BEFORE the GW event (i.e. these are not
potential counterparts), and also a map showing the transients having
discovery date AFTER the event. The latter is being updated on an hourly
basis during a period of 2 weeks after the GW event date. All maps and the
corresponding transient lists are downloadable as CSV/JSON files. Here's the
main LIGO GW page listing the existing GW events.

Past events (like the two events from 2015) are accessible to all; new events
are accessible only to members of groups that are part of the LV-EM MOU.

[ Top ]

 

Quick query links

Unclassified ATs:

https://www.wis-tns.org/search?&isTNS_AT=yes&unclassified_at=1&num_page=100

Unclassified ATs within a discovery magnitude range (e.g. 15-17):

https://www.wis-tns.org/search?&isTNS_AT=yes&unclassified_at=1&discovery...

Classified SNe:

https://www.wis-tns.org/search?&isTNS_AT=yes&classified_sne=1&num_page=100

 

To download as CSV, add "&format=csv", e.g. for classified SNe:

https://www.wis-tns.org/search?&isTNS_AT=yes&classified_sne=1&num_page=1...

Additional notes:

- The maximum allowed number of results per page is 100 (num_page=100).

- If downloading as CSV/TSV and the retrieved results surpass the maximum, you
may implement paging by specifying &page=X (0 being the 1st page), e.g.:

https://www.wis-tns.org/search?&page=0&isTNS_AT=yes&classified_sne=1&num...

https://www.wis-tns.org/search?&page=1&isTNS_AT=yes&classified_sne=1&num...

 

You may check this python Sample code for easily downloading as CSV/TSV the
results of your search page query.

Example searches exist at the bottom of the script. Do not forget to specify
your TNS_BOT_ID, TNS_BOT_NAME and api_key, and clearly your specific query
parameters.

There's also a flag (MERGE_TO_SINGLE_FILE) for specifying whether you want
to merge the retrieved entries into a single final CSV/TSV file or if to leave the
downloaded files as they are (the number of entries in each file are according
to the num_page parameter, and up to the maximum of 100, as mentioned).
 

*** IMPORTANT NOTE ***

Please note that we highly discourage using the search page downloading options
for retrieving the full TNS data. This causes substantial overloading of the
system and we would not allow such a mode of operation.

For downloading and managing locally the full list of the TNS objects we advise
to make use of the staged csv's as described in the following section.

Using the Search page for the downloading of a CSV/TSV should be done for very
specific queries that retrieve a limited set of results. Also in this case, we
recommend to check and use the options provided by the Search/Get APIs.

*******************************

[ Top ]

 

Daily CSV Staging

Every day after UT midnight, two CSV files are created and are accessible for
download under: https://www.wis-tns.org/system/files/tns_public_objects/

1. tns_public_objects.csv.zip - holds the entire catalog of TNS public objects
(AT/SN/FRB/... ~70,000 currently). This file is overwritten daily. The date and
time when the list of objects was created is specified in the first line; e.g.
"2021-03-15 00:00:00"

2. tns_public_objects_YYYYMMDD.csv.zip - holds only those entries (objects) that
were either added or modified during the specified day. So, e.g. during Mar 15,
2021 it is possible to download this latest CSV for the previous day:
tns_public_objects_20210314.csv.zip The first line in the CSV will contain the
exact duration covering the entries in the file; e.g. for the above example:
"2021-03-14 00:00:00 - 23:59:59"

The separate daily files remain in place for 1 month backwards.

Staging the CSV files serves to fulfil requests by TNS users, as well as encourage
performing time-consuming operations locally by users, reducing the load on the
TNS servers.

For example, if you need to cross-match entire catalogs or long object lists, we
request that this would be done locally, against the csv (or a locally managed
DB), rather than by executing multiple cone-searches via the Search API. Calling
the APIs for a limited number of objects is clearly fine, but we ask that our
users apply appropriate caution and sensibility when using the TNS resources,
that serve a broad community.

The csv's contain the following columns:

  • "objid","name_prefix","name","ra","declination","redshift","typeid","type",
  • "reporting_groupid","reporting_group","source_groupid","source_group",
  • "discoverydate","discoverymag","discmagfilter","filter",
  • "reporters","time_received","internal_names","creationdate","lastmodified" 

cURL usage examples for downloading (note that the api_key is required):

(Copy/Paste from your Bot's edit page the required tns_marker string to put in the User-Agent section. You can clearly also specify the appropriate browser User-Agent.) 

Or if logged in, you can just go to the URL for downloading the CSV:

https://www.wis-tns.org/system/files/tns_public_objects/tns_public_objec...
https://www.wis-tns.org/system/files/tns_public_objects/tns_public_objec... (specify the required date)
 

A clarification:

The full csv includes all objects that were reported to the TNS, so NOT including the past ("historic") SNe.
The past SNe can be downloaded using this search query: https://www.wis-tns.org/search?&isTNS_AT=no

[ Top ]

 

AstroNotes

The AstroNotes service allows all registered users to distribute notifications
regarding a broad range of astrophysical topics to those TNS users that choose
to subscribe to the AstroNotes service. These include in particular:

1. Notes about discovery or classification of objects that contain 
more elaborate information than the automated TNS notifications, 
including in particular notifications about re-classification of 
objects.  
2. Notes providing additional data or analysis of transients.  
3. Notifications about new astrophysical tools and utilities. 
4. Notifications about new surveys or new observing campaigns.
5. Notifications about Data Releases.  
6. General notifications of interest to the community.

The AstroNotes system is built to automatically connect notes to the
related objects, thus making it possible to search for information
about an object by coordinates, name, type and more.

All AstroNotes are public, are provided free of charge to post and to read and
are indexed on the ADS and are citable.

All registered TNS users can submit AstroNotes, as long as they comply with
general ethical standards for scientific publications (including proper credit
via references), with applicable laws, and their contents are scientifically
relevant to the astronomical community.

We have initially subscribed all TNS users to this service. If you would prefer
to not receive any additional AstroNotes, or to select which notifications to
receive and how often, just login to the TNS, go to "My Account", scroll down to
the "AstroNotes notifications" box and change your preferences accordingly.

The AstroNotes service consists of four main webpages (see below in detail): 

  • Main AstroNotes page - displaying existing AstroNotes, with many query options. 
  • Add AstroNote - a form for creating a new AstroNote for public release. 
  • My Draft AstroNotes - Viewing and editing your draft AstroNotes for release.
  • My Templates - creating and managing your templates, with which standardized
    AstroNotes (usually on behalf of a group/survey) can be easily written and
    released.

Main page:

The main AstroNotes page consists of the 4 following sections:

- Top left: Query fields section, which include querying options by object
details, such as name, coordinates and obj type.

- Below the query fields the resulting AstroNotes entries are shown, most recent
at the top.

- Top right: the Most Viewed AstroNotes are displayed.

- Bottom right: A changing display of the recently released public AstroNotes of
type Announcement-Tool/Utility.

Add AstroNote:

To reach the form for adding a new AstroNote, click the "Add an AstroNote" tab.

Mandatory fields are marked with red asterisks. If not posting on behalf of a
specific group choose "None" for Source Group.

Make sure to fill in the Authors list with the appropriate format: First-name
(or initial) Last-name (affiliation), etc...

The Abstract is intended for summarising the AstroNote and for highlighting the
main points, and is limited to 1000 characters, simple text only (no HTML
mark-ups etc...). It is this text that will be displayed in the notification
emails, together with the title, authors and related objects. The abstract is
also formally indexed on the ADS.

If relating to objects, all objects mentioned in the body should be added to the
Related Objects table below.

If the object names have been mentioned in the Body, clicking the "Identify known
TNS IAU names and Related AstroNotes
" fills in the Related Objects table below.
(In future additional name resolvers will be added, not only for the TNS
objects.)

When specifying a TNS object in the Related Objects table, its main properties
are injected to the table (RA, DEC, Type, Redshift), and those fields are
editable. Note that updating those fields does not replace a formal Discovery or
Classification report, but these denote what has been reported in the AstroNote
itself. On the AstroNote page (of a specific AstroNote), those fields will be
displayed as the "Reported" properties, and by clicking the "Show current TNS
values
" above the table, it is also possible to show what are the actual current
values on the TNS. Reported values that differ from the current TNS values are
highlighted in red.

Any relevant Related Files can be uploaded with association to the AstroNote.

If not willing to publicly release the AstroNote yet but to save as a draft (for
e.g. sharing with colleagues and await revisions), make sure to click the "Save
as a draft
" checkbox, followed by Submit (a confirmation message will appear).

It is possible to use an existing Template (of the group or a personal one) by
choosing it in the "Use Template" select field at the top. After loading a
template all relevant fields can be edited, and upon submission there is a
validity check to make sure that no double curly brackets "{{...}}", as defined
in the template, were left unchanged (see My Templates descriptions below).

When creating a new AstroNote (Add AstroNote), it is possible to assign up
to 3 additional editors (registered TNS users), who will also be able to edit
the draft AstroNote, besides the person who created the AstroNote. This is
especially useful when an AstroNote is submitted on behalf of a survey/group,
and whenever its relevant for additional people to be able to update and release
the Note. The specification of the additional editors is not done on the
level of a template definition but when adding (creating) a new AstroNote. The
editors fields are auto-complete on the first/last names.
 

My Draft AstroNotes:

Here you can view your draft AstroNotes for further editing and until the final
public release.

My Templates:

Every registered TNS user can create and manage their own AstroNote templates,
either a private one (with Source group=None) or for the use of a group (in
which he/she is a member of).

In the Template select field at the top either leave "New" for creating a new
template or choose a template from the list, which either belongs to one of your
groups, or of which you are an owner.

It is possible to update and save only the templates for which you are one of
the owners.

In order to create a new template based on an existing one, load the relevant
template and then set the select field back to New. The fields remain as they've
been loaded, and you should then update the Title and all other relevant fields
and save as a new template.

It is possible to specify Template Instructions that will be shown when the
template is being used for the creation of a new AstroNote.

A template includes all fields of an AstroNote besides the Related Objects and
Related Files sections.

For the Related Objects, it is possible to specify as part of the template the
additional columns, which will be shown when adding related objects in the
creation of the AstroNote itself.

A neat feature we advise to make use of - in the fields: Title, Authors,
Abstract & Body, it is possible to specify, as part of the template, text
encapsulated in double curly brackets: {{ TEXT... }}. This indicates text that
should be adjusted or removed in the creation of the actual AstroNote. Upon
submission of the AstroNote, a validity check verifies that no double curly
brackets remain in those fields.

[ Top ]

 


 

Feedbacks and comments on all levels are clearly most welcome.

Please contact us via the contact-us page.


 

Funding and Support

This activity is supported by funding from:

  • The Weizmann Institute of Science (WIS)

As well as grants from:

  • The Israeli Institute for Advanced Studies (IIAS)
  • The EU via ERC grant No. 725161

[ Top ]


 

The following people are involved in the design, development and administration of the TNS:

Ofer Yaron, Avner Sass, Nikola Knezevic, Eran Ofek and Avishay Gal-Yam.

[ Top ]