Python module API reference

Module rmsynthesis.rmsynthesismain

rmsynthesis.rmsynthesismain.add_phi_to_fits_header(fits_header, phi_array)

Returns a deep copy of fits_header. The returned copy has Faraday depth as the third axis, with reference values and increments as derived from phi_array. It is assumed that phi_array contains values on a regular comb.

rmsynthesis.rmsynthesismain.as_wavelength_squared(frequencies)

Convert frequencies (in Hz) to wavelength squared (in m^2). Accepts a scalar value as well as arrays. The return value has the same shape as frequencies.

rmsynthesis.rmsynthesismain.compute_rmsf(frequencies, phi_array)

Compute the Rotation Measure Spread Function, derotating to the average lambda^2.

rmsynthesis.rmsynthesismain.file_exists(filename, verbose=False)

Returns True oif filename exists, False if it does not. If verbose is True, it also prints an error message if the file does not exist.

rmsynthesis.rmsynthesismain.output_pqu_fits_names(output_dir)

rmsynthesis.rmsynthesismain.output_pqu_headers(fits_header)

rmsynthesis.rmsynthesismain.parse_frequency_file(filename)

Read a text file containing one floating point number per line, and return an array of those values. Empty lines are ignored. Comments can be included in the file behind a # mark. The frequencies should be listed in Hz.

Raises a printable ParseError in case of problems with the contents of the file.

rmsynthesis.rmsynthesismain.proper_fits_shapes(qname, uname, frequencyname)

Verify that the Q and U FITS cubes and the file with frequency data have compatible shapes. qname and uname are the filenames of the Q and U FITS files, respectively; frequencyname is the filename of the frequency file.

Returns True if all is well, raises ShapeError otherwise.

rmsynthesis.rmsynthesismain.rmsynthesis_dirty(qcube, ucube, frequencies, phi_array)

Perform an RM synthesis on Q and U image cubes with given frequencies. The rmcube that is returned is complex valued and has a frame for every value in phi_array. It is assumed that the dimensions of qcube, ucube, and frequencies have been verified before with the help of the proper_fits_shapes() function. The polarization vectors are derotated to the average lambda^2.

rmsynthesis.rmsynthesismain.rmsynthesis_dirty_lowmem(qname, uname, q_factor, u_factor, frequencies, phi_array)

Perform an RM synthesis on Q and U image cubes with given frequencies. The rmcube that is returned is complex valued and has a frame for every value in phi_array. It is assumed that the dimensions of qcube, ucube, and frequencies have been verified before with the help of the proper_fits_shapes() function. The polarization vectors are derotated to the average lambda^2.

rmsynthesis.rmsynthesismain.rmsynthesis_dirty_lowmem_main(q_name, u_name, q_factor, u_factor, output_dir, freq_hz, phi_rad_m2, force_overwrite)

rmsynthesis.rmsynthesismain.rmsynthesis_phases(wavelength_squared, phi)

Compute the phase factor exp(-2j*phi*wavelength_squared).

rmsynthesis.rmsynthesismain.write_rmcube(rmcube, fits_header, output_dir, force_overwrite=False)

Writes a complex valued, 3D rmcube to output_dir as three separate FITS cubes:

• output_dir/p-rmcube-dirty.fits : Absolute value.
• output_dir/q-rmcube-dirty.fits : Real part.
• output_dir/u-rmcube-dirty.fits : Imaginary part.

This function raises an IOError if output_dir does not exist, or is not writable, or if the output file(s) already exist and force_overwrite is False. If force_overwrite is True, the output files will be overwritten.

Module rmsynthesis.fits

A collection of small utilities to interface with pyfits.

rmsynthesis.fits.get_data_offset_length(fits_name)

Returns the offset from the beginning of the file as well as the length of the data block, in bytes, for the first Header Data Unit (HDU). The length includes padding to the next 2880 byte boundary.

Parameters

fits_name : string

File name from which to read the header.

Returns

A tuple of integers (offset, data_length).

Raises

IOError:

If fits_name cannot be opened.

Example

>>> get_data_offset_length('testdata/Q_Fthinsource.fits')
(2880, 4000320)

rmsynthesis.fits.get_header(fits_name)

Read only the header in FITS file fits_name. Internally simply calls pyfits.getheader().

Parameters

fits_name : string

File name from which to read the header.

Returns

A pyfits.Header instance.

Raises

OSError

If fits_name cannot be opened.

Example

>>> print(get_header('testdata/Q_Fthinsource.fits'))
SIMPLE  =                    T / Written by IDL:  Tue Sep 28 22:42:54 2010      
BITPIX  =                  -32 / Number of bits per data pixel                  
NAXIS   =                    3 / Number of data axes                            
NAXIS1  =                  100 /                                                
NAXIS2  =                  100 /                                                
NAXIS3  =                  100 /                                                
DATE    = '2010-09-28'         / Creation UTC (CCCC-MM-DD) date of FITS header  
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy  
COMMENT and Astrophysics', volume 376, page 359; bibcode 2001A&A...376..359H    
CTYPE1  = 'X       '           /                                                
CRVAL1  =                    0 /                                                
CDELT1  =          1.30000E+06 /                                                
CRPIX1  =                    0 /                                                
CUNIT1  = 'Hz      '           /                                                
CTYPE2  = 'Y       '           /                                                
CRVAL2  =                    0 /                                                
CRVAL3  =          1.10000E+08 /                                                
POL     = 'Q       '           /                                                

>>> print(get_header('testdata/non-existent.fits'))
Traceback (most recent call last):
...
IOError: [Errno 2] No such file or directory: 'testdata/non-existent.fits'

rmsynthesis.fits.get_header_data(fits_name)

Returns the first HDU of fits_name as a (header, data) tuple.

Parameters

fits_name : string

File name from which to read the header.

Returns

A (pyfits.Header, numpy.ndarray) tuple.

Raises

IOError

If fits_name cannot be opened.

Example

>>> hdr, data = get_header_data('testdata/Q_Fthinsource.fits')
>>> print(hdr)
SIMPLE  =                    T / Written by IDL:  Tue Sep 28 22:42:54 2010      
BITPIX  =                  -32 / Number of bits per data pixel                  
NAXIS   =                    3 / Number of data axes                            
NAXIS1  =                  100 /                                                
NAXIS2  =                  100 /                                                
NAXIS3  =                  100 /                                                
DATE    = '2010-09-28'         / Creation UTC (CCCC-MM-DD) date of FITS header  
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy  
COMMENT and Astrophysics', volume 376, page 359; bibcode 2001A&A...376..359H    
CTYPE1  = 'X       '           /                                                
CRVAL1  =                    0 /                                                
CDELT1  =          1.30000E+06 /                                                
CRPIX1  =                    0 /                                                
CUNIT1  = 'Hz      '           /                                                
CTYPE2  = 'Y       '           /                                                
CRVAL2  =                    0 /                                                
CRVAL3  =          1.10000E+08 /                                                
POL     = 'Q       '           /                                                

>>> data.shape
(100, 100, 100)

FITS single floats are big endian 32 bit numbers. >>> str(data.dtype) ‘>f4’

Operating on them in any way, converts the output to ‘float32’: >>> str((data*1).dtype) ‘float32’

Of course, opening a non-existent file results in an OSError... >>> get_header_data(‘testdata/non-existent.fits’) Traceback (most recent call last): ... IOError: [Errno 2] No such file or directory: ‘testdata/non-existent.fits’

rmsynthesis.fits.image_frames(fits_name)

An iterator over a FITS image (hyper) cube:

Parameters

fits_name : string

Fits file over which to iterate.

Returns

A 2D numpy.array for each image in the (hyper)cube contained in the file. It has shape (NAXIS2, NAXIS1).

Example

>>> i = 0
>>> for frame in image_frames('testdata/Q_Fthinsource.fits'):
...     if i % 10 == 0:
...         print('%r: %3.2f' % (frame.shape, frame[50,50]))
...     i += 1
(100, 100): -9.29
(100, 100): 23.13
(100, 100): 81.73
(100, 100): -87.40
(100, 100): 40.75
(100, 100): 68.86
(100, 100): -72.43
(100, 100): -87.07
(100, 100): -0.70
(100, 100): 76.28

rmsynthesis.fits.streaming_output_hdu(fits_name, fits_header, force_overwrite)

Creates an HDU stream to which data can be written incrementally. This is very useful for writing large FITS image cubes.

Parameters

fits_name : string

Output file name..

fits_header : pyfits.Header

The header for the output FITS file.

force_overwrite : Bool

If True, overwrite existing file with name fits_name. If False, an OSError is raised if the file already exists.

Returns

A pyfits.core.StreamingHDU instance.

Raises

IOError

If output file exists and force_overwrite is False

Example

>>> fits_name = 'testdata/partial_output.fits'
>>> if os.path.exists(fits_name): os.remove(fits_name)
>>> 
>>> hdr, data = get_header_data('testdata/Q_Fthinsource.fits')
>>> shdu  = streaming_output_hdu(fits_name, hdr, force_overwrite = False)
>>> for image in data:
...     reached_end = shdu.write(image)
>>> shdu.close()
>>> 
>>> os.path.exists(fits_name)
True
>>> os.stat(fits_name).st_size
4003200
>>> hdr2, data2 = get_header_data(fits_name)
>>> print(hdr2)
SIMPLE  =                    T / Written by IDL:  Tue Sep 28 22:42:54 2010      
BITPIX  =                  -32 / Number of bits per data pixel                  
NAXIS   =                    3 / Number of data axes                            
NAXIS1  =                  100 /                                                
NAXIS2  =                  100 /                                                
NAXIS3  =                  100 /                                                
DATE    = '2010-09-28'         / Creation UTC (CCCC-MM-DD) date of FITS header  
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy  
COMMENT and Astrophysics', volume 376, page 359; bibcode 2001A&A...376..359H    
CTYPE1  = 'X       '           /                                                
CRVAL1  =                    0 /                                                
CDELT1  =          1.30000E+06 /                                                
CRPIX1  =                    0 /                                                
CUNIT1  = 'Hz      '           /                                                
CTYPE2  = 'Y       '           /                                                
CRVAL2  =                    0 /                                                
CRVAL3  =          1.10000E+08 /                                                
POL     = 'Q       '           /                                                
>>> (data2 == data).all()
True

If we try this again:

>>> shdu  = streaming_output_hdu(fits_name, hdr, force_overwrite = False)
Traceback (most recent call last):
...
IOError: testdata/partial_output.fits already exists. Will not overwrite unless forced.

Let’s try that again:

>>> import time
>>> current_time = time.time()
>>> shdu  = streaming_output_hdu(fits_name, hdr, force_overwrite = True)
Overwriting existing file 'testdata/partial_output.fits'.
>>> for image in data:
...     reached_end = shdu.write(image)
>>> shdu.close()
>>> 
>>> os.path.exists(fits_name)
True
>>> os.stat(fits_name).st_size
4003200
>>> os.stat(fits_name).st_mtime > current_time
True
>>> os.remove(fits_name)

rmsynthesis.fits.write_cube(fits_name, fits_header, data, force_overwrite=False)

Write an image cube to a FITS file containing only one HDU.

Parameters

fits_name : string

Output file name.

fits_header : pyfits.Header

The header describing data.

data : numpy.array

The (hyper)cube to write to the FITS file.

force_overwrite : bool

If True, the output file will be overwritten. Otherwise, an IOError is raised if the output file already exists.

Returns

None

Raises

IOError

If the output file already exists and force_overwrite == False.

Example

>>> fits_name = 'testdata/write_cube_output.fits'
>>> if os.path.exists(fits_name): os.remove(fits_name)
>>> 
>>> hdr, data = get_header_data('testdata/Q_Fthinsource.fits')
>>> write_cube(fits_name, hdr, data)
>>> hdr2, data2 = get_header_data(fits_name)
>>> print(hdr2)
SIMPLE  =                    T / Written by IDL:  Tue Sep 28 22:42:54 2010      
BITPIX  =                  -32 / Number of bits per data pixel                  
NAXIS   =                    3 / Number of data axes                            
NAXIS1  =                  100                                                  
NAXIS2  =                  100                                                  
NAXIS3  =                  100                                                  
DATE    = '2010-09-28'         / Creation UTC (CCCC-MM-DD) date of FITS header  
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy  
COMMENT and Astrophysics', volume 376, page 359; bibcode 2001A&A...376..359H    
CTYPE1  = 'X       '           /                                                
CRVAL1  =                    0 /                                                
CDELT1  =          1.30000E+06 /                                                
CRPIX1  =                    0 /                                                
CUNIT1  = 'Hz      '           /                                                
CTYPE2  = 'Y       '           /                                                
CRVAL2  =                    0 /                                                
CRVAL3  =          1.10000E+08 /                                                
POL     = 'Q       '           /                                                

>>> (data2 == data).all()
True

>>> write_cube(fits_name, hdr, data)
Traceback (most recent call last):
...
IOError: File 'testdata/write_cube_output.fits' already exists.

>>> import time
>>> current_time = time.time()
>>> write_cube(fits_name, hdr, data, force_overwrite = True)    
Overwriting existing file 'testdata/write_cube_output.fits'.
>>> os.path.exists(fits_name)
True
>>> os.stat(fits_name).st_size
4003200
>>> os.stat(fits_name).st_ctime > current_time
True
>>> os.remove(fits_name)