PulsarAstronomy.net
The Pulsar Astronomy Network

||paralactic_angle ||float (angle) ||NO ||The paralactic angle at the start of the data block|| need TCS ||

[[!Data Formats]]

The rest of this document outlines the XML elements present in a version 1 PsrXML header file. The code can be found [[http://github.com/SixByNine/psrxml/tree/master|here]].

||!Element Name ||!Data Type ||!Req'd ||!comment ||!BPSR Status ||

||frequency_header_type ||String ||YES ||Type of the frequency info: `SIMPLE, `MULTIBAND or `COMPLEX. Only SIMPLE is supported in v1.0 || OK ||

'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 ||

||!Element Name ||!Data Type ||!Req'd ||!comment || BPSR Status ||

||!Element Name ||!Data Type ||!Reqired ||!comment || BPSR Status ||

||!Element Name ||!Data Type ||!Req'd ||!comment || BPSR Status ||

||!Element Name ||!Data Type ||!Req'd ||!comment || BPSR Status ||

||!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 ||

||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 ||

||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|| ?? ||

||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|| ?? ||

||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|| ?? ||

||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 ||

||utc ||ISO8601 Date ||NO ||Approimate UTC date/time at start of this data block||
||current_coordinate ||Coordinate ||NO ||The position on the sky at the first sample of this data block||
||telescope_position ||Az/El ||NO ||The Azimuth and Elevation at the start of the data block||

||feed_polarisation_basis ||String ||YES ||`LINEAR or `CIRCULAR||
||feed_handedness ||String ||YES ||The sign of the polarisaiton phase. `LEFT or `RIGHT||

||feed_symetry ||float (angle) ||YES ||Polarisation symmetry angle||

||sideband ||String ||YES ||`UPPER or `LOWER||
||cross_phase ||String ||YES ||`STANDARD or `REVERSE||

!!Block header elements
Data block headers exist up to one per block
||!Element Name ||!Data Type ||!Req'd ||!comment ||
||sha1_hash ||String ||NO ||A 40 character SHA1 hash of the data block.||
||current_coordinate ||Coordinate ||NO ||The position on the sky at the first sample of this data block||
||telescope_position ||Az/El ||NO ||The Azimuth and Elevation at the start of the data block||
||paralactic_angle ||float (angle) ||NO ||The paralactic angle at the start of the data block||

||frequency_header_type ||String ||YES ||Type of the frequency info: `SIMPLE, `MULTIBAND or `COMPLEX. Only SIMPLE is supported in v1.0
||centre_frequency_first_channel||float (freq) ||YES ||The observing frequency at the centre of the first channel. Only valid for `SIMPLE frequency headers||
||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||

||frequency_type ||String ||YES ||Type of the frequency info: `SIMPLE, `MULTIBAND or `COMPLEX. Only SIMPLE is supported in v1.0

||lo_setting ||float(freq) ||NO ||The LO setting, can have multiple values in one file.||

!PsrXML
!!Introduction
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.

!!PsrXML elements
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.

||border=1 cellspacing=0
||!Element Name ||!Data Type ||!Req'd ||!comment ||
||source_name ||String ||YES ||Pulsar name or grid ID ||
||source_name_centre_beam ||String ||NO ||The source that the telescope was set to point at ||
||cat_reference ||String ||NO ||A catalogue reference id for the data||
||day_of_observation ||float ||YES ||The MJD at the start of the observation||
||midnight_to_first_sample ||int (64 bits) ||YES ||Aproximate number of nanosec from midnight||
||utc ||ISO8601 Date ||YES ||Approimate UTC date/time at start of observation||
||lst ||String (hh:mm:ss) ||YES ||Approimate LST time at start of observation||
||local_time ||ISO8601 Date ||NO ||Approimate local time time at start of observation||
||number_of_samples ||int ||YES ||The number of samples recorded in total||
||native_sample_rate ||float (time) ||NO ||The sampling rate of the backend||
||current_sample_interval ||float (time) ||YES ||The time between the centre of adjacent samples||
||requested_obs_time ||float (time) ||NO ||The observing time requested||
||actual_obs_time ||float (time) ||YES ||The actual observing time represented||
||centre_frequency_first_channel||float (freq) ||YES ||The observing frequency at the centre of the first channel||
||channel_offset ||float (freq) ||YES ||The frequency offset between adjacent channels (or the channel bandwidth if only one channel)||
||number_of_channels ||int ||YES ||Number of channels in the file||
||receiver_beam ||int ||NO ||The beam of the receiver the data are from.||
||start_coordinate ||Coordinate ||YES ||The position on the sky at the first sample of this data||
||end_coordinate ||Coordinate ||NO ||The position on the sky at the last sample of this data||
||requested_coordinate ||Coordinate ||NO ||The requested observation position (of the centre beam)||
||start_paralactic_angle ||float (angle) ||NO ||The paralactic angle at the start of the obs||
||end_paralactic_angle ||float (angle) ||NO ||The paralactic angle at the end of the obs||
||paralactic_angle_tracking ||boolean ||NO ||Is the receiver rotating with the sky||
||start_telescope_position ||Az/El ||NO ||The Azimuth and Elevation at the start of the obs||
||end_telescope_position ||Az/El ||NO ||The Azimuth and Elevation at the end of the obs||
||observing_programme ||String ||NO ||A descriptor of the observing programme||
||observer_name ||String ||NO ||The name of the observer||
||observation_type ||String ||NO ||Freeform classification of the observation||
||observation_configuration ||String ||NO ||Freeform description of the configuration||
||total_beams_recorded ||int ||NO ||Number of `sister' observations that should exist||
||recorded_polarisations ||String ||YES ||II=total intensity||
||telescope_identifying_string ||String ||NO ||Freeform string identifying the specifics of the telescope used||
||receiver_identifying_string ||String ||NO ||Freeform string identifying the specifics of the receiver used||
||backend_identifying_string ||String ||NO ||Freeform string identifying the specifics of the backend used||
||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)||

!!Data elements
||!Element Name ||!Data Type ||!Req'd ||!comment ||
||filename ||String ||YES ||The name of the file||
||data_type ||String ||YES ||What this file represents. e.g. `TIMESERIES', `BANDPASS' and `VIRTUAL' are used||
||sequence ||int ||YES ||Once this file is read, go may to the next in sequence of the same type||
||data_uid ||String (typed) ||NO ||A means to identify this file||
||checksum ||String (typed) ||NO ||A checksum for the whole file||
||header_length ||int (data) ||YES ||Number of bytes to skip at start of the file||
||block_header_length ||int (data) ||YES ||Number of bytes to skip at the start of a data block||
||block_size ||int (data) ||YES ||Size of blocks to be read at once||
||bits_per_sample ||int ||YES ||The number of bits per sample||
||data_order ||String ||YES ||Order of the data indices. F=freq T=time P=pol, slowest incrementing first||
||bit_order_first_sample_in ||String ||YES ||Order of bits within byte. Either `MSB' or `LSB'.||
||endian ||String ||YES ||Endianness of data. `BIG', `LITTLE' or `INDEPENDANT' (for less than 8 bit data)||
||signed ||boolean ||YES ||True indicates using signed integers||

!!Telescope Elements
||!Element Name ||!Data Type ||!Req'd ||!comment ||
||name ||String ||YES ||The human name of the telescope||
||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||

!!Receiver elements
||!Element Name ||!Data Type ||!Reqired ||!comment ||
||name ||String ||YES ||The human name of the receiver||
||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 symetry angle||
||number_of_polarisations ||int ||YES ||Polarisations in the feed, 1 or 2||

!!Backend elements
||!Element Name ||!Data Type ||!Req'd ||!comment ||
||name ||String ||YES ||The human name of the backend||
||sideband ||String ||YES ||`UPPER' or `LOWER'||
||cross_phase ||String ||YES ||`STANDARD' or `REVERSE'||
||sigproc_code ||int ||NO ||Identifying code in sigproc||