PsrXML is a definition for an XML based pulsar data header format. PsrXML is designed to be independant of the format of the underlying data, specifying meta-data to sucessfuly read the data. Data provided by a PsrXML file are stored with human friendly names and with units specified in the XML tag. This reduced the chances of confusion with regard to the meaning or values of header fields that has been present in previous data formats. PsrXML files are associated with one or more data files that contain the raw data or other associated data files in an arbitrary format. The PsrXML header file and associated files can be collected together in a TAR archive for ease of filing and writing to magnetic tape.
The PsrXML header format is designed to be extendable with new header fields, this document specifies the minimum fields required to conform to version 1 of the PsrXML format. Fields marked as non-required are optional additional parameters that should be included if the information is avaliable when the header is written, however software based on this specification should be aware that not all headers will be able to provide this data. Software reading PsrXML documents should also be aware that additional XML elements may be present in the file that are not specified by this document. It is intended that any future versions of the PsrXML shall also be complient with this version 1 specification, therefore software may treat PsrXML documents with a version higher than 1 as version 1 documents.
The rest of this document outlines the XML elements present in a version 1 PsrXML header file. The code can be found here.
PsrXML documents are contained in a root psrxml element. This contains the main header elements, plus elements describing the properties of the telescope,receiver, backend and associated data files. Associated data files include the raw data as well as any extra information such as bandpass dumps.
‘BPSR Status’ is a temporary column for marking the status of that field in the BPSR observing system.
| Element Name | Data Type | Req’d | comment | BPSR Status |
|---|---|---|---|---|
| source_name | String | YES | Pulsar name or grid ID | OK |
| source_name_centre_beam | String | NO | The source that the telescope was set to point at | need TCS |
| cat_reference | String | NO | A catalogue reference id for the data | need BK |
| day_of_observation | float | YES | The MJD at the start of the observation | OK |
| midnight_to_first_sample | int (64 bits) | YES | Aproximate number of nanosec from midnight | OK |
| utc | ISO8601 Date | YES | Approimate UTC date/time at start of observation | need dspsr |
| lst | String (hh:mm:ss) | YES | Approimate LST time at start of observation | need dspsr |
| local_time | ISO8601 Date | NO | Approimate local time time at start of observation | need dspsr |
| number_of_samples | int | YES | The number of samples recorded in total | OK |
| native_sample_rate | float (time) | NO | The sampling rate of the backend | OK |
| current_sample_interval | float (time) | YES | The time between the centre of adjacent samples | OK |
| requested_obs_time | float (time) | NO | The observing time requested | need TCS |
| actual_obs_time | float (time) | YES | The actual observing time represented | OK |
| frequency_header_type | String | YES | Type of the frequency info: SIMPLE, MULTIBAND or COMPLEX. Only SIMPLE is supported in v1.0 | OK |
| centre_frequency_first_channel | float (freq) | YES | The observing frequency at the centre of the first channel. Only valid for SIMPLE frequency headers | OK |
| channel_offset | float (freq) | YES | The frequency offset between adjacent channels (or the channel bandwidth if only one channel). Only valid for SIMPLE frequency headers | OK |
| number_of_channels | int | YES | Number of channels in the file | OK |
| lo_setting | float(freq) | NO | The LO setting, can have multiple values in one file. | OK |
| receiver_beam | int | NO | The beam of the receiver the data are from. | need TCS |
| start_coordinate | Coordinate | YES | The position on the sky at the first sample of this data | need TCS |
| end_coordinate | Coordinate | NO | The position on the sky at the last sample of this data | need TCS |
| requested_coordinate | Coordinate | NO | The requested observation position (of the centre beam) | need TCS |
| start_paralactic_angle | float (angle) | NO | The paralactic angle at the start of the obs | need TCS |
| end_paralactic_angle | float (angle) | NO | The paralactic angle at the end of the obs | need TCS |
| paralactic_angle_tracking | boolean | NO | Is the receiver rotating with the sky | need TCS |
| start_telescope_position | Az/El | NO | The Azimuth and Elevation at the start of the obs | need TCS |
| end_telescope_position | Az/El | NO | The Azimuth and Elevation at the end of the obs | need TCS |
| observing_programme | String | NO | A descriptor of the observing programme | need TCS |
| observer_name | String | NO | The name of the observer | need TCS |
| observation_type | String | NO | Freeform classification of the observation | need dspsr |
| observation_configuration | String | NO | Freeform description of the configuration | need TCS |
| total_beams_recorded | int | NO | Number of `sister’ observations that should exist | need TCS |
| recorded_polarisations | String | YES | II=total intensity | OK |
| telescope_identifying_string | String | NO | Freeform string identifying the specifics of the telescope used | OK |
| receiver_identifying_string | String | NO | Freeform string identifying the specifics of the receiver used | OK |
| backend_identifying_string | String | NO | Freeform string identifying the specifics of the backend used | OK |
| telescope_config_string | String | NO | Freeform string identifying the config of the telescope used | ?? |
| receiver_config_string | String | NO | Freeform string identifying the config of the receiver used | ?? |
| backend_config_string | String | NO | Freeform string identifying the config of the backend used | ?? |
| telescope | Telescope | YES | Telescope XML block | - |
| receiver | Receiver | YES | Receiver XML block | - |
| backend | Backend | YES | Backend XML block | - |
| data | Data (multiple) | YES | Data XML blocks (one per assoc. file) | OK |
| Element Name | Data Type | Req’d | comment | BPSR Status |
|---|---|---|---|---|
| filename | String | YES | The name of the file | OK |
| data_type | String | YES | What this file represents. e.g. TIMESERIES’, BANDPASS’ and VIRTUAL’ are used | OK |
| sequence | int | YES | Once this file is read, go may to the next in sequence of the same type | OK |
| data_uid | String (typed) | NO | A means to identify this file | OK |
| checksum | String (typed) | NO | A checksum for the whole file | OK |
| header_length | int (data) | YES | Number of bytes to skip at start of the file | OK |
| block_header_length | int (data) | YES | Number of bytes to skip at the start of a data block | OK |
| block_size | int (data) | YES | Size of blocks to be read at once | OK |
| bits_per_sample | int | YES | The number of bits per sample | OK |
| data_order | String | YES | Order of the data indices. F=freq T=time P=pol, slowest incrementing first | OK |
| bit_order_first_sample_in | String | YES | Order of bits within byte. Either MSB’ or LSB’. | OK |
| endian | String | YES | Endianness of data. BIG’, LITTLE’ or INDEPENDANT’ (for less than 8 bit data) | OK |
| signed | boolean | YES | True indicates using signed integers | OK |
| Element Name | Data Type | Req’d | comment | BPSR Status |
|---|---|---|---|---|
| name | String | YES | The human name of the telescope | OK |
| zenith_limit | float (angle) | YES | The zenith limit of the telescope | ?? |
| longitude | float (angle) | YES | Telescope longitude | ?? |
| lattitude | float (angle) | YES | Telescope lattitude | ?? |
| x | float | YES | Telescope X’ coordinate | ?? |
| y | float | YES | Telescope Y’ coordinate | ?? |
| z | float | YES | Telescope Z’ coordinate | ?? |
| tempo_code | String | YES | Telescope code as defined by Tempo(2) | ?? |
| sigproc_code | int | NO | Telescope code as defined by Sigproc | ?? |
| pulsarhunter_code | String | NO | Telescope name as defined by Pulsarhunter | ?? |
| Element Name | Data Type | Reqired | comment | BPSR Status |
|---|---|---|---|---|
| name | String | YES | The human name of the receiver | OK |
| feed_polarisation_basis | String | YES | LINEAR or CIRCULAR | ?? |
| feed_handedness | String | YES | The sign of the polarisaiton phase. LEFT or RIGHT | ?? |
| cal_phase | float | YES | Polarisation phase of the cal | ?? |
| feed_symetry | float (angle) | YES | Polarisation symmetry angle | ?? |
| number_of_polarisations | int | YES | Polarisations in the feed, 1 or 2 | ?? |
| Element Name | Data Type | Req’d | comment | BPSR Status |
|---|---|---|---|---|
| name | String | YES | The human name of the backend | OK |
| sideband | String | YES | UPPER or LOWER | ?? |
| cross_phase | String | YES | STANDARD or REVERSE | ?? |
| sigproc_code | int | NO | Identifying code in sigproc | ?? |
Data block headers exist up to one per block
| Element Name | Data Type | Req’d | comment | BPSR Status |
|---|---|---|---|---|
| sha1_hash | String | NO | A 40 character SHA1 hash of the data block. | OK |
| utc | ISO8601 Date | NO | Approimate UTC date/time at start of this data block | need TCS |
| current_coordinate | Coordinate | NO | The position on the sky at the first sample of this data block | need TCS |
| telescope_position | Az/El | NO | The Azimuth and Elevation at the start of the data block | need TCS |
| paralactic_angle | float (angle) | NO | The paralactic angle at the start of the data block | need TCS |