0
# Table Operations
1

2
Complete interface to casacore's table system including table creation, data access, querying with TaQL (Table Query Language), and MeasurementSet operations. The table system provides SQL-like functionality for radio astronomy data with support for n-dimensional arrays in table cells.
3

4
## Core Imports
5

6
```python
7
from casacore.tables import table, taql, tablecommand
8
from casacore.tables import tablecolumn, tablerow, tableiter, tableindex
9
from casacore.tables import default_ms, default_ms_subtable
10

11
# Table utilities
12
from casacore.tables import tablefromascii
13
from casacore.tables import makescacoldesc, makearrcoldesc, makecoldesc, maketabdesc
14

15
# MeasurementSet utilities
16
from casacore.tables import (addImagingColumns, removeImagingColumns, 
17
                             addDerivedMSCal, removeDerivedMSCal,
18
                             msconcat, msregularize,
19
                             required_ms_desc, complete_ms_desc)
20
```
21

22
## Capabilities
23

24
### Table Access and Creation
25

26
Open existing tables or create new ones with support for various access modes and table types including MeasurementSets.
27

28
```python { .api }
29
def table(tablename, readonly=True, ack=True, **kwargs):
30
    """
31
    Open or create a casacore table.
32
    
33
    Parameters:
34
    - tablename: str, path to table
35
    - readonly: bool, open in read-only mode (default True)  
36
    - ack: bool, acknowledge table opening (default True)
37
    - lockoptions: str, locking options ('auto', 'user', 'usernoread')
38
    - endian: str, endianness ('big', 'little', 'local', 'aipsrc')
39
    - memorytable: bool, create in-memory table
40
    - concurrency: str, concurrency options
41
    
42
    Returns:
43
    table object
44
    """
45

46
def default_ms(name, tabdesc=None, dminfo=None):
47
    """
48
    Create a default MeasurementSet structure.
49
    
50
    Parameters:
51
    - name: str, MeasurementSet name
52
    - tabdesc: dict, optional table description overrides
53
    - dminfo: dict, optional data manager info
54
    
55
    Returns:
56
    table object representing MeasurementSet
57
    """
58

59
def default_ms_subtable(subtable, name=None, tabdesc=None, dminfo=None):
60
    """
61
    Create a MeasurementSet subtable.
62
    
63
    Parameters:
64
    - subtable: str, subtable type ('ANTENNA', 'SPECTRAL_WINDOW', etc.)
65
    - name: str, optional path (defaults to subtable name)
66
    - tabdesc: dict, optional table description overrides
67
    - dminfo: dict, optional data manager info
68
    
69
    Returns:
70
    table object representing subtable
71
    """
72
```
73

74
### Table Query Language (TaQL)
75

76
Execute SQL-like queries on tables with TaQL, supporting complex selection criteria, joins, and aggregations.
77

78
```python { .api }
79
def taql(command, style='Python', tables=[], globals={}, locals={}):
80
    """
81
    Execute a TaQL (Table Query Language) command.
82
    
83
    Parameters:
84
    - command: str, TaQL query string
85
    - style: str, result style ('Python' or 'Glish')
86
    - tables: list, additional tables to make available
87
    - globals: dict, global variables for query
88
    - locals: dict, local variables for query
89
    
90
    Returns:
91
    table object with query results
92
    """
93

94
# Alias for taql
95
tablecommand = taql
96
```
97

98
### Data Access Methods
99

100
Retrieve and modify table data at cell, column, and row levels with support for slicing and partial reads.
101

102
```python { .api }
103
class table:
104
    def getcell(self, columnname, rownr):
105
        """
106
        Get value from a single table cell.
107
        
108
        Parameters:
109
        - columnname: str, column name
110
        - rownr: int, row number (0-based)
111
        
112
        Returns:
113
        Cell value (type depends on column)
114
        """
115
    
116
    def putcell(self, columnname, rownr, value):
117
        """
118
        Set value in a single table cell.
119
        
120
        Parameters:
121
        - columnname: str, column name  
122
        - rownr: int, row number (0-based)
123
        - value: cell value to set
124
        """
125
    
126
    def getcol(self, columnname, startrow=0, nrow=-1, rowincr=1):
127
        """
128
        Get entire column or column slice.
129
        
130
        Parameters:
131
        - columnname: str, column name
132
        - startrow: int, starting row (default 0)
133
        - nrow: int, number of rows (-1 for all, default -1)
134
        - rowincr: int, row increment (default 1)
135
        
136
        Returns:
137
        numpy array with column data
138
        """
139
    
140
    def putcol(self, columnname, value, startrow=0, nrow=-1, rowincr=1):
141
        """
142
        Set entire column or column slice.
143
        
144
        Parameters:
145
        - columnname: str, column name
146
        - value: numpy array with values to set
147
        - startrow: int, starting row (default 0)
148
        - nrow: int, number of rows (-1 for all, default -1)  
149
        - rowincr: int, row increment (default 1)
150
        """
151
    
152
    def getcolslice(self, columnname, blc, trc, inc=[], startrow=0, nrow=-1):
153
        """
154
        Get slice of array column.
155
        
156
        Parameters:
157
        - columnname: str, array column name
158
        - blc: list, bottom-left corner indices
159
        - trc: list, top-right corner indices  
160
        - inc: list, increment per axis (default [])
161
        - startrow: int, starting row (default 0)
162
        - nrow: int, number of rows (-1 for all, default -1)
163
        
164
        Returns:
165
        numpy array with sliced data
166
        """
167
```
168

169
### Table Structure and Metadata
170

171
Access table properties, column information, and metadata including table description and data manager information.
172

173
```python { .api }
174
class table:
175
    def nrows(self):
176
        """Get number of rows in table."""
177
        
178
    def ncols(self):
179
        """Get number of columns in table."""
180
        
181
    def colnames(self):
182
        """Get list of column names."""
183
        
184
    def coldesc(self, columnname=""):
185
        """
186
        Get column description(s).
187
        
188
        Parameters:
189
        - columnname: str, specific column (empty for all columns)
190
        
191
        Returns:
192
        dict with column description information
193
        """
194
        
195
    def info(self):
196
        """Get table information and properties."""
197
        
198
    def summary(self, header=True, columns=True, dataman=False, subtables=False):
199
        """
200
        Get table summary.
201
        
202
        Parameters:
203
        - header: bool, include header info
204
        - columns: bool, include column info  
205
        - dataman: bool, include data manager info
206
        - subtables: bool, include subtable info
207
        
208
        Returns:
209
        dict with summary information
210
        """
211
```
212

213
### Table Operations
214

215
Perform table operations including copying, selection, sorting, and joining.
216

217
```python { .api }
218
class table:
219
    def copy(self, newtablename, deep=True, valuecopy=False, dminfo={}):
220
        """
221
        Copy table to new location.
222
        
223
        Parameters:
224
        - newtablename: str, new table name
225
        - deep: bool, deep copy (default True)
226
        - valuecopy: bool, copy values not references (default False)
227
        - dminfo: dict, data manager info for new table
228
        
229
        Returns:
230
        table object for new table
231
        """
232
    
233
    def select(self, columnnames="", offset=0, limit=0):
234
        """
235
        Select subset of columns and rows.
236
        
237
        Parameters:
238
        - columnnames: str or list, column names to select (empty for all)
239
        - offset: int, starting row offset (default 0)
240
        - limit: int, maximum rows to return (0 for all, default 0)
241
        
242
        Returns:
243
        table object with selection
244
        """
245
    
246
    def sort(self, sortlist, unique=False):
247
        """
248
        Sort table by specified columns.
249
        
250
        Parameters:
251
        - sortlist: str or list, column names for sorting
252
        - unique: bool, remove duplicate rows (default False)
253
        
254
        Returns:
255
        table object with sorted data
256
        """
257
    
258
    def query(self, query, sortlist="", columns="", offset=0, limit=0):
259
        """
260
        Query table with selection criteria.
261
        
262
        Parameters:
263
        - query: str, selection expression
264
        - sortlist: str, sort specification (default "")
265
        - columns: str, columns to select (default "")
266
        - offset: int, starting row offset (default 0)
267
        - limit: int, maximum rows (default 0)
268
        
269
        Returns:
270
        table object with query results
271
        """
272
```
273

274
### Table Management
275

276
Low-level table management including locking, flushing, and resource cleanup.
277

278
```python { .api }
279
class table:
280
    def lock(self, mode="write", nattempts=0):
281
        """
282
        Lock table for exclusive access.
283
        
284
        Parameters:
285
        - mode: str, lock mode ('read' or 'write')
286
        - nattempts: int, number of lock attempts (0 for infinite)
287
        
288
        Returns:
289
        bool, True if lock acquired
290
        """
291
    
292
    def unlock(self):
293
        """Release table lock."""
294
    
295
    def haslock(self, mode="write"):
296
        """
297
        Check if table is locked.
298
        
299
        Parameters:
300
        - mode: str, lock mode to check
301
        
302
        Returns:
303
        bool, True if locked in specified mode
304
        """
305
    
306
    def flush(self, recursive=True):
307
        """
308
        Flush table changes to disk.
309
        
310
        Parameters:
311
        - recursive: bool, flush subtables too (default True)
312
        """
313
    
314
    def close(self):
315
        """Close table and release resources."""
316
        
317
    def done(self):
318
        """Close table (alias for close)."""
319
```
320

321
### MeasurementSet Utilities
322

323
Specialized utilities for working with MeasurementSets including concatenation, column management, and structure descriptions.
324

325
```python { .api }
326
def msconcat(names, newname, concatTime=False):
327
    """
328
    Concatenate multiple MeasurementSets into a single MeasurementSet.
329
    
330
    Parameters:
331
    - names: list of str, paths to MeasurementSets to concatenate
332
    - newname: str, path for output concatenated MeasurementSet
333
    - concatTime: bool, concatenate in time rather than frequency (default False)
334
    
335
    Returns:
336
    None (creates new MeasurementSet file)
337
    """
338

339
def msregularize(msname, newname):
340
    """
341
    Regularize a MeasurementSet by removing duplicate rows and fixing inconsistencies.
342
    
343
    Parameters:
344
    - msname: str, input MeasurementSet path
345
    - newname: str, output regularized MeasurementSet path
346
    
347
    Returns:
348
    None (creates new MeasurementSet file)
349
    """
350

351
def addImagingColumns(msname, ack=True):
352
    """
353
    Add standard imaging columns to MeasurementSet.
354
    
355
    Adds MODEL_DATA and CORRECTED_DATA columns needed for imaging and calibration.
356
    
357
    Parameters:
358
    - msname: str, MeasurementSet path
359
    - ack: bool, acknowledge operation (default True)
360
    
361
    Returns:
362
    None (modifies MeasurementSet in place)
363
    """
364

365
def removeImagingColumns(msname):
366
    """
367
    Remove imaging columns from MeasurementSet.
368
    
369
    Removes MODEL_DATA and CORRECTED_DATA columns to save disk space.
370
    
371
    Parameters:
372
    - msname: str, MeasurementSet path
373
    
374
    Returns:
375
    None (modifies MeasurementSet in place)
376
    """
377

378
def addDerivedMSCal(msname):
379
    """
380
    Add derived calibration columns to MeasurementSet.
381
    
382
    Adds computed columns for calibration purposes like UVW coordinates.
383
    
384
    Parameters:
385
    - msname: str, MeasurementSet path
386
    
387
    Returns:
388
    None (modifies MeasurementSet in place)
389
    """
390

391
def removeDerivedMSCal(msname):
392
    """
393
    Remove derived calibration columns from MeasurementSet.
394
    
395
    Parameters:
396
    - msname: str, MeasurementSet path
397
    
398
    Returns:
399
    None (modifies MeasurementSet in place)
400
    """
401

402
def required_ms_desc(table=None):
403
    """
404
    Get required table description for MeasurementSet or subtable.
405
    
406
    Parameters:
407
    - table: str, table type (None/'MAIN' for main table, or subtable name)
408
    
409
    Returns:
410
    dict, table description with required columns only
411
    """
412

413
def complete_ms_desc(table=None):
414
    """
415
    Get complete table description for MeasurementSet or subtable.
416
    
417
    Parameters:
418
    - table: str, table type (None/'MAIN' for main table, or subtable name)
419
    
420
    Returns:
421
    dict, complete table description with all standard columns
422
    """
423
```
424

425
### Table Description Utilities
426

427
Functions for creating table and column descriptions programmatically for table creation.
428

429
```python { .api }
430
def tablefromascii(tablename, asciifile, headerfile='', autoheader=False, 
431
                   autoshape=[], columnnames=[], datatypes=[], sep=' ',
432
                   commentmarker='', firstline=1, lastline=-1, readonly=True,
433
                   lockoptions='default', ack=True):
434
    """
435
    Create table from ASCII file with automatic or manual column type detection.
436
    
437
    Parameters:
438
    - tablename: str, output table path
439
    - asciifile: str, input ASCII data file path
440
    - headerfile: str, optional header file path (default '')
441
    - autoheader: bool, automatically detect column types (default False)
442
    - autoshape: list, automatic array shape detection (default [])
443
    - columnnames: list, explicit column names (default [])
444
    - datatypes: list, explicit data types (default [])
445
    - sep: str, field separator (default ' ')
446
    - commentmarker: str, comment line marker (default '')
447
    - firstline: int, first line to read (default 1)
448
    - lastline: int, last line to read (-1 for all, default -1)
449
    - readonly: bool, open result table readonly (default True)
450
    - lockoptions: str, locking options (default 'default')
451
    - ack: bool, acknowledge operation (default True)
452
    
453
    Returns:
454
    table object for created table
455
    """
456

457
def makescacoldesc(columnname, value, option=0, comment=''):
458
    """
459
    Create scalar column description.
460
    
461
    Parameters:
462
    - columnname: str, column name
463
    - value: default value (determines data type)
464
    - option: int, column options (default 0)
465
    - comment: str, column comment (default '')
466
    
467
    Returns:
468
    dict, column description
469
    """
470

471
def makearrcoldesc(columnname, value, ndim=0, shape=[], option=0, comment=''):
472
    """
473
    Create array column description.
474
    
475
    Parameters:
476
    - columnname: str, column name
477
    - value: default value (determines data type)
478
    - ndim: int, number of dimensions (0 for variable, default 0)
479
    - shape: list, fixed shape specification (default [])
480
    - option: int, column options (default 0)
481
    - comment: str, column comment (default '')
482
    
483
    Returns:
484
    dict, column description
485
    """
486

487
def makecoldesc(columnname, desc, datamanager='', datamanagertype='', 
488
                datamanagergroup='', option=0, maxlen=0, comment='', 
489
                valuetype='', shape=[], ndim=-1):
490
    """
491
    Create general column description with full control.
492
    
493
    Parameters:
494
    - columnname: str, column name
495
    - desc: value type descriptor or default value
496
    - datamanager: str, data manager name (default '')
497
    - datamanagertype: str, data manager type (default '')
498
    - datamanagergroup: str, data manager group (default '')
499
    - option: int, column options (default 0)
500
    - maxlen: int, maximum string length (default 0)
501
    - comment: str, column comment (default '')
502
    - valuetype: str, explicit value type (default '')
503
    - shape: list, array shape specification (default [])
504
    - ndim: int, number of dimensions (-1 for scalar, default -1)
505
    
506
    Returns:
507
    dict, column description
508
    """
509

510
def maketabdesc(descs, **kwargs):
511
    """
512
    Create table description from column descriptions.
513
    
514
    Parameters:
515
    - descs: list of dict, column descriptions
516
    - **kwargs: additional table description parameters
517
    
518
    Returns:
519
    dict, complete table description
520
    """
521
```
522

523
### Column-Specific Access
524

525
Convenient column-oriented interface that eliminates need to repeatedly specify column names.
526

527
```python { .api }
528
class tablecolumn:
529
    def __init__(self, table, columnname):
530
        """
531
        Create column interface.
532
        
533
        Parameters:
534
        - table: table object
535
        - columnname: str, column name
536
        """
537
    
538
    def getcell(self, rownr):
539
        """Get single cell value from this column."""
540
    
541
    def putcell(self, rownr, value):
542
        """Set single cell value in this column."""
543
    
544
    def getcol(self, startrow=0, nrow=-1, rowincr=1):
545
        """Get column data."""
546
    
547
    def putcol(self, value, startrow=0, nrow=-1, rowincr=1):
548
        """Set column data."""
549
    
550
    def name(self):
551
        """Get column name."""
552
    
553
    def datatype(self):
554
        """Get column data type."""
555
    
556
    def ndim(self, rownr=-1):
557
        """Get number of dimensions (for array columns)."""
558
    
559
    def shape(self, rownr=-1):
560
        """Get shape (for array columns)."""
561
```
562

563
### Row-Based Access
564

565
Access table data in row-oriented fashion with support for row iteration and bulk row operations.
566

567
```python { .api }
568
class tablerow:
569
    def __init__(self, table, columnnames=[], exclude=False):
570
        """
571
        Create row interface.
572
        
573
        Parameters:
574
        - table: table object
575
        - columnnames: list, columns to include (empty for all)
576
        - exclude: bool, exclude specified columns instead
577
        """
578
    
579
    def get(self, rownr):
580
        """Get row data as dictionary."""
581
    
582
    def put(self, rownr, value, matchingfields=True):
583
        """
584
        Set row data from dictionary.
585
        
586
        Parameters:
587
        - rownr: int, row number
588
        - value: dict, row data
589
        - matchingfields: bool, only update matching fields
590
        """
591
```
592

593
### Table Iteration
594

595
Iterate through table based on grouping criteria with automatic sorting and grouping by column values.
596

597
```python { .api }
598
class tableiter:
599
    def __init__(self, table, columnnames, order="", sort=True):
600
        """
601
        Create table iterator.
602
        
603
        Parameters:
604
        - table: table object
605
        - columnnames: list, columns to group by
606
        - order: str, sort order specification
607
        - sort: bool, sort before iterating (default True)
608
        """
609
    
610
    def next(self):
611
        """Get next group as table object."""
612
    
613
    def reset(self):
614
        """Reset iterator to beginning."""
615
```
616

617
### Table Indexing
618

619
Create and use indexes on tables for fast lookups and range queries.
620

621
```python { .api }
622
class tableindex:
623
    def __init__(self, table, columnnames, sort=True):
624
        """
625
        Create table index.
626
        
627
        Parameters:
628
        - table: table object
629
        - columnnames: list, columns to index
630
        - sort: bool, sort index (default True)
631
        """
632
    
633
    def find(self, key):
634
        """
635
        Find rows matching key.
636
        
637
        Parameters:
638
        - key: value or list of values to find
639
        
640
        Returns:
641
        list of row numbers
642
        """
643
    
644
    def findrows(self, key):
645
        """Find rows matching key (alias for find)."""
646
```
647

648
## Usage Examples
649

650
### Basic Table Operations
651

652
```python
653
from casacore.tables import table, taql
654

655
# Open table and get basic info
656
t = table('observation.ms')
657
print(f"Rows: {t.nrows()}, Columns: {t.ncols()}")
658
print("Column names:", t.colnames())
659

660
# Access specific data
661
times = t.getcol('TIME')
662
first_data = t.getcell('DATA', 0)
663

664
# Query with TaQL
665
selected = taql("SELECT TIME, ANTENNA1, ANTENNA2 FROM observation.ms WHERE ANTENNA1 < 5")
666
print(f"Selected {selected.nrows()} rows")
667

668
# Clean up
669
selected.close()  
670
t.close()
671
```
672

673
### MeasurementSet Creation
674

675
```python
676
from casacore.tables import default_ms, default_ms_subtable
677

678
# Create MeasurementSet with custom columns
679
desc = {
680
    'DATA': {'comment': 'Visibility data', 'shape': [4, 64]},
681
    'FLAG': {'comment': 'Flag data', 'shape': [4, 64]}
682
}
683

684
ms = default_ms('new_observation.ms', tabdesc=desc)
685

686
# Create subtables
687
ant_table = default_ms_subtable('ANTENNA', 'new_observation.ms/ANTENNA')
688
spw_table = default_ms_subtable('SPECTRAL_WINDOW', 'new_observation.ms/SPECTRAL_WINDOW')
689

690
ms.close()
691
ant_table.close()
692
spw_table.close()
693
```
694

695
### Advanced Queries
696

697
```python
698
# Complex TaQL query with joins and aggregation
699
query = """
700
SELECT ANTENNA1, ANTENNA2, mean(amplitude(DATA)) as avg_amp
701
FROM observation.ms  
702
WHERE TIME > mjd('2023-01-01') AND TIME < mjd('2023-01-02')
703
GROUP BY ANTENNA1, ANTENNA2
704
ORDER BY avg_amp DESC
705
"""
706

707
result = taql(query)
708
print("Average amplitudes by baseline:")
709
for i in range(result.nrows()):
710
    ant1 = result.getcell('ANTENNA1', i)
711
    ant2 = result.getcell('ANTENNA2', i) 
712
    avg_amp = result.getcell('avg_amp', i)
713
    print(f"  {ant1}-{ant2}: {avg_amp:.3f}")
714

715
result.close()
716
```