= Conversion Software =

== Summary ==

The first software aspect of this project is to convert the survey data into a standard format that will be widely understandable. This will be the PSRFITS format, a variant of the FITS standard specialised for pulsar data structures but readable by anything that can read a FITS file. This stage has involved the creation of a number of programs:
 * {{{pvoconvert}}}: Convert PKS format survey observations to PSRFITS format.
 * {{{pvosummary}}}: Summarise the positions, observation date/time, frequency of PSRFITS files, with the ability to produce a csv file listing a range of useful metadata.
 * {{{pvoconesearch}}}: A command-line tool to search for PSRFITS files that cover sky within a specified radius of a specified position.

The source code for these programs is available in this repository: source:/trunk/src [[BR]]
It has also been installed in the pulsar file system, in {{{/pulsar/psr/pvo/}}} and the binaries have been compiled under linux and installed in {{{/pulsar/linux/bin/}}}.

== Usage ==

=== PVOCONVERT ===

{{{pvoconvert}}} operates on existing "tape" files, converting them into a set of PSRFITS (.fits) format files with one sky position per fits file. You can either provide one or more tape files as the argument, or a directory with the {{{-D}}} flag (in which case it will operate on all appropriate files in that directory). It recognises 70-cm survey data and PM survey data. If you have high-latitude (PH) survey data, you need to give the {{{-H}}} flag to get the settings right.

{{{
Usage: pvoconvert [options] <survey file(s)> ...
  Options:
  -D <dir>          Run pvoconvert on all files in the stated directory.
  --directory <dir>
                     No <survey file> needs to be given in this case.
  -H                Use the PH (High Latitude) Survey settings, rather than
  --highlat          those for the PM/Multibeam Survey
  -h                Display this help page.
  --help
  -v                Verbose mode for error/warning messages.
  --verbose
}}}

=== PVOSUMMARY ===

{{{pvosummary}}} is designed to produce a summary list of metadata for either a given fits file, or all fits files in the current directory. It normally writes the information to the terminal, but can also produce a csv (comma-separated values) file.

The fields returned are:  FILENAME, RAJ, DECJ, BEAM FWHM, OBSFREQ, SCANLEN, DATE-OBS

{{{
Usage:
  1. pvosummary [options]
  2. pvosummary [options] <FILE>
Options:
 -c <file>    Write all parameters in csv format to the specified file.
 --csv <file>
 -p           List all parameters
 -q           Quiet mode -- nothing printed to screen
               (used in conjunction with -c)
 -h           Print this help message.
 --help 
 -v           Verbose mode for error/warning messages.
 --verbose
}}}

=== PVOCONESEARCH ===

{{{pvoconesearch}}} is a simple cone-search tool that searches around a given (RA,DEC) location, within a given radius, and returns the same metadata as {{{pvosummary}}} for all FITS files whose beams overlap the search area. The returned files are listed in order of increasing separation from the requested (RA,DEC) position. RA & DEC can be in hh:mm:ss.s format or decimal degrees, while the search radius is in degrees.

{{{
Usage:
  1. pvoconesearch ra dec radius
  2. pvoconesearch -h
}}}