CPROPStoo

Welcome!

This is an IDL package to aid in the analysis of emission line data cubes. It expands and modularizes the CPROPS package introduced by Rosolowsky & Leroy (2006). It provides utilities to estimate noise and mask cubes, identify local maxima, partition cubes into object assignments, and derive properties from object assignments. It also increasingly acts as a "cube library" for IDL work focused on radio data cubes.

If you use this version, please reference Rosolowsky & Leroy (2006). An additional updated reference is forthcoming in 2014 or 2015. If you would like to contribute to the code, please feel encouraged to do so via pull request or email aleroy@nrao.edu about being added as a collaborator on the wiki. Thanks for stopping by!

Prerequisites

The IDL Astronomy User's library is required to run the package and the Coyote Graphics libraries are a nominal (though currently unused) requirement. If you encounter any other dependencies, please email and we will endeavor to include the routine in this distribution.

Contributors

Many thanks to those who have contributed code (add your name if it should be here): Annie Hughes, Amanda Kepley, Adam Leroy, Stephen Pardy, Erik Rosolowsky, Karin Sandstrom, Andreas Schruba. And thanks for feedback to many folks including Frank Bigiel, Dario Colombo, and Tony Wong.

Examples

A suite of rich examples remains under development. Currently the repository includes one full example applying the full analysis flow to an unnamed ALMA data cube. See:

• cpropstoo_example : a documented rich example application

More examples forthcoming as papers using the code are accepted.

User Tasks

These are high level tasks are intended to be accessed by the user. A normal cube analysis path calls them in sequency. They are described in approximate order of the workflow for a normal application of CPROPS.

Units and Book Keeping

• cprops_check_header : verify that a cube is appropriate for cprops analysis: units are K, km/s, and has beam info in header. Note that failing this check does not indicate a poorly-formed cube.

• prep_cube : attempt to place a cube in correct units for cprops. This can be hit-or-miss but will save you some annoying work if it fires off correctly.

Signal Identification

• make_noise_cube : accept a cube and optionally a mask and return 0, 1, 2, or 3d noise estimates.

• make_cprops_mask : makes a mask based on joint thresholding.

• show_mask : visualize a mask.

Feature Identification

• find_local_max : accept a cube and mask and return a set of local maxima.

• assign_clfind : accept a list of kernels and a cube and use the CLUMPFIND approach (nearest neighbors) to generate an assignment cube. Alternatively, if a set of kernels is not supplied, generate an assignment cube following the "classic" CLUMPFIND approach.

• assign_cprops : accept a list of kernels and a cube use the CPROPS approach (unique associated isocontours) to generate an assignment cube.

• assign_from_levelprops [documented] : accept a "level moments" style structure (generated by level_moments in the dendrogram work flow) combined with an array of flags and map this back to a cube assignment giving the largest "flagged" structures (e.g., the largest bound structures).

• make_merger_tree : generate a merger tree of the sort needed in the dendrogram or level moments calculation.

• mergefind_approx : find merger levels between peaks using brute force. "Approximate" because it assumes some contouring (e.g., steps of 0.25 sigma or similar) in the calculation.

Feature Characterization

The feature characterization distinguishes "moments" - which are defined loosely as values calculated from the cube with little awareness of metadata (e.g., sizes in pixels) - and "properties" - which are more physical values (e.g., deconvolved angular or linear sizes).

• cube_to_moments : extract moment measurements for a list of clouds given an assignment cube and a data cube.

• cube_to_level_moments : measure moments for each kernel plus contour combination in a cube. Feeds dendrogram analysis or other multiscale approaches.

• moments_to_props : calculate cloud properties based on moment measurements and other physical information.

• extract_dendro : extract a tree diagram from the level moments type structure.

Analysis of Results

Monte Carlo

• add_noise_to_cube : add correlated noise to a data cube. Useful for Monte Carlo calculations.

• realize_noise : take a noise estimate and produce a realistic cube of noise (convolved with the beam) for use in Monte Carlo calculations.

Cube Manipulation

• A variety of the IDLAstro astrometric routines are wrapped with to work with cubes instead of only two dimensional images. The general methodology is to simply loop plane by plane. These include cube_hastrom (alignment), cube_hextract (extraction), cube_hreverse (reverse direction of an axis), cube_hrot (rotate a cube). See the IDLAstro documentation for more details.

• conv_with_gauss : convolve a cube to a target resolution. Accepts elliptical aussian beams and works on cubes and images.

• extract_planes : extract a subset of planes from a cube as a new cube or FITS file.

Lower Level Routines

These programs are called by the higher level routines. They may still be of general use.

These are alphabetized by topic.

Astrophysical or Observational Calculations

We have found these widely useful.

• calc_jtok [documented] : convert from Janskies per beam to Kelvin.

• conv_with_gauss [documented] : convolve a data cube or image with an elliptical Gaussian beam to reach a target resolution. General purpose.

• deconvolve_gauss : deconvolve one Gaussian from another. Rigorously useful for interferometer beams. Approximately useful for clouds.

• make_axes [documented] : generate RA, Dec, and Velocity axes or images from FITS headers.

Cube Infrastructure

Note that these are potentially of general use for moving fluidly between cube data and vectorized analysis.

• cubify [documented] : convert a vector of {x,y,v,t} measurements into a cube

• ind_to_xyv : convert cube index to pixels

• vectorify [documented] : convert a subset of a cube into {x,y,v,t} vector

• xyv_to_ind : convert pixels to cube index

Display

A long term goal would be to deprecate these in favor the Coyote graphic libraries. But the overhead in getting the disp functionality from the cg routines may preclude ever actually doing that.

• counter [documented] : progress-bar style counter

• disp [documented] : two-d image display program.

• fasthist [documented] : quick histogram program.

• reversect [documented] : invert a color table.

• str : smart number to string conversion.

Feature Characterization Infrastructure

• calc_props_from_moments: convert moment measurements to properties.

Math

• bisection [documented] : bisection root finder

• erf0 [documented] : helper function allowing the root finder to solve for the error function at a particular x value.

• my_gauss2d [documented] : generate a rotated two dimensional gaussian (e.g., for use as a PDF).

Moment Calculation

• calc_gauss_corr : procedurally generated file that calculates the aperture corrections for a three dimensional Gaussian. Created by gauss_model.

• ellfit [documented] : fit a two dimensional ellipse to data, solving for the principle axes.

• extrap [documented] : use a curve-of-growth analysis to derive the correction needed to extrapolate a moment to perfect sensitivity.

• gauss_model [documented] : generates a program or IDL file recording the aperture corrections appropriate for a 3-d Gaussian as a function of peak-to-edge ratio.

• measure_moments : given a vector x, y, v, and t calculate a structure containing moments, wrapping the extrapolation

• pa_moment : use PCA to find suggest the major and minor axis

Peak Identification

• alllocmax : find all candidate local maxima via rolling a cube.

• decimate_kernels : reject candidate local maxima

• mergefind_approx : solve for merger levels among a set of kernels

• write_kernels : write a set of kernels to a text or IDL file

Properties and Moment "Packages"

Feature characterization is grouped into "packages" that calculate families of related moments and properties. These packages each do three things: return an empty structure of moments/properties, calculate moments, and convert moments to properties given proper metadta.

• moments_area : properties calculated using area as a size metric.

• moments_classic : the original Rosolowsky & Leroy '06 moments.

• moments_gausscor : properties calculated using Gaussian extrapolation.

• moments_template [documented] : an example / template file demonstrating how to put together one of the moment packages. Not intended to be run.

Signal Identification

These routines are of general use dealing with binary masks.

• grow_mask [documented] : manipulate masks.

• stat_mask : extract statistics (volume, area, and extent along the v axis) on regions inside a mask.

Structure Handling

• add_props_fields [documented] : add fields to a structure related to property measurements

• alphabetize_struct [documented] : alphabetize the fields in a structure.

• empty_moment_struct [documented] : initialize an empty moment structure.

Vector Analysis

Note that these are potentially of wide general use.

• contour_values : return contours given data and some criteria.

• mad [documented] : median absolute deviation. Cheap, robust noise estimate.