0
# Python-Casacore
1

2
Python-casacore provides comprehensive Python bindings for the CASACORE radio astronomy library, enabling radio astronomy applications to access core functionality including table operations, image processing, coordinate systems, and measurement sets through a Python interface. It offers high-performance astronomical data handling capabilities with support for FITS files, coordinate transformations, and specialized radio astronomy data structures.
3

4
## Package Information
5

6
- **Package Name**: python-casacore
7
- **Language**: Python (with C++ extensions)
8
- **Installation**: `pip install python-casacore`
9
- **Minimum Python Version**: 3.8+
10
- **Dependencies**: numpy, boost-python, casacore C++ library
11

12
## Core Imports
13

14
Main package import:
15

16
```python
17
import casacore
18
```
19

20
Common submodule imports:
21

22
```python
23
# Table system
24
from casacore.tables import table, taql
25
from casacore.tables import default_ms, default_ms_subtable
26

27
# Table utilities
28
from casacore.tables import tablefromascii, msconcat, msregularize
29
from casacore.tables import makescacoldesc, makearrcoldesc, makecoldesc, maketabdesc
30

31
# Image processing
32
from casacore.images import image
33

34
# Coordinate systems and measures
35
from casacore.measures import measures
36

37
# Quantities with units
38
from casacore.quanta import quantity
39

40
# Mathematical functionals
41
from casacore.functionals import gaussian1d, poly, compiled
42

43
# Least squares fitting
44
from casacore.fitting import fitserver
45

46
# Utilities  
47
from casacore.util import substitute, getlocals, getvariable
48
```
49

50
Backwards compatibility imports (pyrap):
51

52
```python
53
# Legacy pyrap compatibility
54
import pyrap.tables as pt
55
import pyrap.measures as pm
56
import pyrap.quanta as pq
57
```
58

59
## Basic Usage
60

61
### Working with Tables
62

63
```python
64
from casacore.tables import table, taql
65

66
# Open an existing table
67
t = table('my_table.ms', readonly=True)
68

69
# Get basic table information
70
print(f"Table has {t.nrows()} rows and {t.ncols()} columns")
71
print("Columns:", t.colnames())
72

73
# Access cell data
74
value = t.getcell('DATA', 0)  # Get first row of DATA column
75
column_data = t.getcol('TIME')  # Get entire TIME column
76

77
# Query with TaQL (Table Query Language)
78
result = taql("SELECT TIME, DATA FROM my_table.ms WHERE ANTENNA1 < 10")
79
print(f"Query returned {result.nrows()} rows")
80

81
# Close table
82
t.close()
83
```
84

85
### Working with Images
86

87
```python
88
from casacore.images import image
89

90
# Open an image
91
img = image('my_image.fits')
92

93
# Get image information
94
print("Image shape:", img.shape())
95
print("Image coordinates:", img.coordinates())
96

97
# Get image data
98
data = img.getdata()
99

100
# Get image statistics
101
stats = img.statistics()
102
print("Max:", stats['max'], "Min:", stats['min'])
103

104
# Create a subimage
105
subimg = img.subimage(blc=[10, 10], trc=[100, 100])
106
```
107

108
### Working with Quantities and Measures
109

110
```python
111
from casacore.quanta import quantity
112
from casacore.measures import measures
113

114
# Create quantities with units
115
freq = quantity('1.4GHz')
116
time = quantity('2023-01-01/12:00:00')
117
pos = quantity([10.0, 20.0, 30.0], 'm')
118

119
# Create measures server
120
dm = measures()
121

122
# Set reference frame
123
dm.doframe(dm.epoch('utc', 'today'))
124
dm.doframe(dm.observatory('VLA'))
125

126
# Create direction measure
127
source = dm.direction('j2000', '12h30m00s', '-30d00m00s')
128

129
# Convert between coordinate systems
130
azel = dm.measure(source, 'azel')
131
```
132

133
## Architecture
134

135
Python-casacore consists of two main packages with six core functional areas:
136

137
### Package Structure
138

139
- **casacore**: Primary package with modern Python interfaces
140
- **pyrap**: Backwards compatibility package that re-exports casacore modules
141

142
### Core Submodules
143

144
- **Tables**: Complete table system with SQL-like query language (TaQL)
145
- **Images**: Multi-dimensional image processing with coordinate systems  
146
- **Measures**: Astronomical reference frames and coordinate conversions
147
- **Quanta**: Physical quantities with units and constants
148
- **Functionals**: Mathematical functions with parameters for fitting
149
- **Fitting**: Linear and non-linear least squares fitting algorithms
150

151
### C++ Integration
152

153
The package includes six C++ extension modules that provide high-performance implementations:
154
- `_tables`, `_images`, `_measures`, `_quanta`, `_functionals`, `_fitting`
155

156
This hybrid architecture ensures both Python convenience and C++ performance for computationally intensive radio astronomy operations.
157

158
## Capabilities
159

160
### Table System Operations
161

162
Complete interface to casacore's table system including table creation, data access, querying with TaQL (Table Query Language), and MeasurementSet operations. Provides both high-level convenience methods and low-level table manipulation.
163

164
```python { .api }
165
def table(tablename, readonly=True, ack=True, **kwargs): ...
166
def taql(command, style='Python', tables=[], globals={}, locals={}): ...
167
def default_ms(name, tabdesc=None, dminfo=None): ...
168
```
169

170
[Table Operations](./table-operations.md)
171

172
### Image Processing and Analysis
173

174
Multi-dimensional astronomical image processing with support for FITS, HDF5, MIRIAD, and casacore paged image formats. Includes coordinate system handling, image statistics, regridding, and subimage operations.
175

176
```python { .api }
177
def image(imagename, **kwargs): ...
178
class coordinatesystem: ...
179
```
180

181
[Image Processing](./image-processing.md)
182

183
### Coordinate Systems and Measures  
184

185
Astronomical reference frames, coordinate conversions, and measurement systems. Handles directions, positions, epochs, frequencies, Doppler shifts, and baseline/UVW coordinates with full support for reference frame transformations.
186

187
```python { .api }
188
class measures:
189
    def direction(self, rf='', v0='0..', v1='90..', off=None): ...
190
    def position(self, rf='', v0='0..', v1='90..', v2='0m', off=None): ...
191
    def epoch(self, rf='', v0='0.0d', off=None): ...
192
    def measure(self, v, rf, off=None): ...
193
```
194

195
[Coordinate Systems](./coordinate-systems.md)
196

197
### Quantities and Units
198

199
Physical quantities with units, unit conversions, and astronomical constants. Supports scalar and vector quantities with comprehensive unit system including SI, astronomical, and specialized radio astronomy units.
200

201
```python { .api }
202
def quantity(*args): ...  
203
def is_quantity(q): ...
204
class Quantity: ...
205
class QuantVec: ...
206
```
207

208
[Quantities and Units](./quantities-units.md)
209

210
### Mathematical Functionals
211

212
Parameterized mathematical functions including polynomials, Gaussians, and user-defined compiled expressions. These functionals can be used for data modeling and as input to the fitting system.
213

214
```python { .api }
215
class functional: ...
216
class gaussian1d: ...
217
class poly: ...
218
class compiled: ...
219
```
220

221
[Mathematical Functionals](./functionals.md)
222

223
### Least Squares Fitting
224

225
Linear and non-linear least squares fitting with constraint support. Handles both real and complex fitting problems with SVD solutions for rank-deficient systems and comprehensive error analysis.
226

227
```python { .api }
228
class fitserver:
229
    def linear(self, functional, x, y, **kwargs): ...
230
    def functional(self, functional, x, y, **kwargs): ...
231
    def solution(self, fid=None): ...
232
    def addconstraint(self, x=[], y=0.0, **kwargs): ...
233
```
234

235
[Fitting Operations](./fitting-operations.md)
236

237
## Types
238

239
### Common Types
240

241
```python { .api }
242
# Table-related types
243
class table:
244
    def nrows(self) -> int: ...
245
    def ncols(self) -> int: ...
246
    def colnames(self) -> list[str]: ...
247
    def getcell(self, columnname: str, rownr: int): ...
248
    def getcol(self, columnname: str, startrow: int = 0, nrow: int = -1): ...
249

250
# Quantity types  
251
class Quantity:
252
    def get_value(self): ...
253
    def get_unit(self) -> str: ...
254
    def convert(self, unit: str): ...
255

256
class QuantVec:
257
    def get_value(self): ...
258
    def get_unit(self) -> str: ...
259

260
# Measure types (all measures are dictionaries with 'type', 'refer', and 'm0'/'m1'/'m2' keys)
261
MeasureDict = dict[str, Any]  # Has keys: 'type', 'refer', 'm0', optionally 'm1', 'm2', 'offset'
262
```