AHELP for CIAO 4.15

# ciao_proptools

Context: contrib

## Synopsis

Experimental interface to the Chandra proposal tools (CIAO contributed package).

## Syntax

```import ciao_contrib.proptools as proptools
help(proptools)```

## Description

The ciao_contrib.proptools module provides an experimental Python interface to the following Chandra proposal tools: colden, precess, and dates. Not all the functionality of the command-line or web-based version of the tools is supported. This module is provided as part of the CIAO contributed scripts package.

The module can be loaded into Python by saying:

```import ciao_contrib.proptools import proptools
```

and help on the module, or one of the routines, can be accessed using the Python help command, for example

```help(proptools)
help(proptools.colden)
```

### Contents

The module currenly provides the following routines:

Routine Description
colden() Find the Galactic neutral Hydrogen column density, in units of 10^20 cm^-2, for one or more locations in equatorial coordinates (J2000).
dates() Convert between Chandra times, MJD, JD, and the Gregorian calendar.
precess() Convert between common coordinate systems.

Simple examples are provided below; please use the Python help command on each routine to find out details of how to use each one.

## Examples

### Example 1

```>>> proptools.colden(23, 40)
6.56
>>> proptools.colden(23, 40, dataset='bell')
6.66
>>> proptools.colden([2.1, 15.8, 356.2, 178.9], [43.5, -0.1, 83.4,
-76], dataset='bell')
[7.34, 3.35, 10.61, None]```

The colden routine takes in one or more positions - in equatorial coordinates (J2000) using decimal degrees - and returns the neutral Hydrogen column density, in units of 10^20 cm^-2. A value of None is returned for those locations which have no data.

For more help use:

`>>> help(proptools.colden)`

The precess routine and the coords.format Python module - ahelp coords_format - can be used to convert values to the coordinate system required by colden().

### Example 2

```>>> proptools.dates(268499019.5)
datetime.datetime(2006, 7, 5, 15, 3, 37, 500000)
>>> str(proptools.dates(268499019.5))
'2006-07-05 15:03:37.500000'
>>> proptools.dates('2006-07-05T15:03:37.5', fromcal="GREG",
tocal="CHANDRA")
268499019.5```

The dates routine can convert between a 'Chandra' time - that is, the system used in Chandra event files for the TIME column - and the Gregorian calendar, Modified Julian Date, or Julian Date. Unlike the colden and precess routines it can only convert one value at a time.

For more help use:

`>>> help(proptools.dates)`

### Example 3

```>>> proptools.precess(12.138, -0.001)
(12.778809, 0.270858)
>>> proptools.precess([12.138, 341.2342], [-0.001, 87.342],
fromsys="J", tofmt="HMS")
(['00 48 33.12', '22 44 56.21'], ['-00 00 03.60', '+87 20 31.20'])```

The precess routine can convert one or more locations between a range of coordinate systems (but not the full range supported by the command-line tool).

For more help use:

`>>> help(proptools.precess)`

The coords.format Python module - ahelp coords_format - provides conversion between sexagesimal and decimal formats.

## Bugs

See the bugs pages for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.