Skip to content

Commit 5317963

Browse files
committed
Merge pull request astropy#38 from taldcroft/update-whats-new-0.3
Add What's New content for Table, Table, ASCII Tables, and Unified I/O
2 parents 212975e + 188b62a commit 5317963

2 files changed

Lines changed: 115 additions & 2 deletions

File tree

‎docs/table/operations.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ table from one or more input tables. This includes:
3232
- `~astropy.table.operations.join`
3333

3434

35+
.. _grouped-operations:
36+
3537
Grouped operations
3638
^^^^^^^^^^^^^^^^^^
3739

@@ -355,6 +357,8 @@ either `True` or `False`. For example::
355357
return False
356358
return True
357359

360+
.. _stack-vertically:
361+
358362
Stack vertically
359363
^^^^^^^^^^^^^^^^^^^^
360364

@@ -435,6 +439,8 @@ attributes`_ for details on how these characteristics of the input tables are me
435439
the single output table. Note also that you can use a single table row instead of a
436440
full table as one of the inputs.
437441

442+
.. _stack-horizontally:
443+
438444
Stack horizontally
439445
^^^^^^^^^^^^^^^^^^^^^
440446

@@ -499,6 +505,8 @@ The metadata from the input tables is merged by the process described in the `Me
499505
metadata`_ section. Note also that you can use a single table row instead of a
500506
full table as one of the inputs.
501507

508+
.. _table-join:
509+
502510
Join
503511
^^^^^^^^^^^^^^
504512

‎docs/whatsnew/0.3.rst‎

Lines changed: 107 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,42 @@ them, use::
176176
Table
177177
-----
178178

179+
In addition to many bug fixes and usability improvements, the key new feature
180+
in the :ref:`astropy-table` package is the addition of high level
181+
:ref:`table_operations` that can be used to generate a new table from one or
182+
more input tables:
183+
184+
.. list-table::
185+
:header-rows: 1
186+
:widths: 28 52 20
187+
188+
* - Documentation
189+
- Description
190+
- Function
191+
* - :ref:`grouped-operations`
192+
- Group tables and columns by keys
193+
- `~astropy.table.table.Table.group_by`
194+
* - :ref:`stack-vertically`
195+
- Concatenate input tables along rows
196+
- `~astropy.table.operations.vstack`
197+
* - :ref:`stack-horizontally`
198+
- Concatenate input tables along columns
199+
- `~astropy.table.operations.hstack`
200+
* - :ref:`table-join`
201+
- Database-style join of two tables
202+
- `~astropy.table.operations.join`
203+
204+
Grouping is a useful concept that allows you to divide a table
205+
into sub-groups based on certain key values and create new tables based
206+
on computed properties of those sub-groups. As an example, if you
207+
have a table containing photometric observations of multiple sources
208+
over multiple epochs, it would be possible to compute a mean magnitude
209+
for each unique object.
210+
211+
Even more powerful is the ability to do database-style joins of tables. For
212+
instance, if you have distinct tables with photometry in different wavebands
213+
for a set of objects, you join these points into a single table with one row
214+
for each source.
179215

180216
Coordinates
181217
-----------
@@ -255,12 +291,81 @@ coordinates used above::
255291
Time
256292
----
257293

258-
.. TODO
294+
The :ref:`astropy-time` package has received attention in filling in
295+
the details from the initial release in astropy 0.2. This includes adding array
296+
indexing and supporting various arithmetic operations involving arrays,
297+
constants, and `~astropy.units.quantity.Quantity` objects with time units. In addition the initial
298+
infrastructure was added to allow use of `International Earth Rotation and
299+
Reference Systems Service
300+
<http://www.iers.org/>`_ tables so that automatic
301+
calculation of UT1 becomes possible.
302+
303+
One very significant improvement is an overhaul of the internal
304+
time manipulations so that arithmetic with `~astropy.time.core.Time` and
305+
`~astropy.time.core.TimeDelta` objects maintain sub-nanosecond precision over a time span
306+
longer than the age of the universe. This is done by carefully managing
307+
the way the time is represented and manipulated using two 64-bit floats.
308+
309+
Finally, three new time formats were added:
310+
311+
- ``datetime``: standard library `datetime.datetime` objects.
312+
- ``plot_date``: dates compatible with the `matplotlib.pyplot.plot_date` function.
313+
- ``gps``: seconds since 1980-01-01 00:00:00 UTC including leap seconds.
259314

260315
ASCII Tables
261316
------------
262317

263-
.. TODO
318+
The :ref:`io-ascii` package now includes functionality to write `IPAC format tables
319+
<http://irsa.ipac.caltech.edu/applications/DDGEN/Doc/ipac_tbl.html>`_.
320+
321+
The `~astropy.io.ascii.ui.read()` and `~astropy.io.ascii.ui.write()` functions now
322+
allow a ``format`` keyword argument for specifying the file format as a string.
323+
This replaces the deprecated ``Reader`` and ``Writer`` keywords which required
324+
supplying a fully-qualified class type. To convert existing code that uses
325+
``Reader`` or ``Writer``, change the class name to all lower case with
326+
underscores between words. For instance::
327+
328+
>>> from astropy.io import ascii
329+
>>> data = [' name age ',
330+
'----------- ----',
331+
'Jane Doe 31 ',
332+
'John Smith 45 ']
333+
>>> t = ascii.read(data, Reader=ascii.FixedWidthTwoLine) # OLD
334+
>>> t = ascii.read(data, format='fixed_width_two_line') # NEW
335+
336+
Unified File Read/Write Interface
337+
----------------------------------
338+
339+
FITS format tables can now be read and written via the :ref:`table_io`.
340+
All of the ASCII table formats are now supported as well. When using
341+
the unified file interface for ASCII tables the ``format`` defined in the :ref:`io-ascii`
342+
package is prefixed with ``'ascii.'``. Thus the previous example would be written::
343+
344+
>>> from astropy.table import Table
345+
>>> t = Table.read(data, format='ascii.fixed_width_two_line')
346+
347+
Some formats such as ``cds`` or ``latex`` will work without the ``'ascii.'``
348+
prefix but this is deprecated and will be removed in the next major release.
349+
350+
The full list of available formats is now available via the
351+
`~astropy.io.registry.get_formats` function::
352+
353+
>>> from astropy.io import registry
354+
>>> print registry.get_formats()
355+
Data class Format Read Write Auto-identify Deprecated
356+
---------- ------------ ---- ----- ------------- ----------
357+
Table ascii Yes Yes No
358+
Table ascii.aastex Yes Yes No
359+
Table ascii.basic Yes Yes No
360+
Table ascii.cds Yes No No
361+
... ... ... ... ... ...
362+
Table daophot Yes No No Yes
363+
Table ipac Yes Yes No Yes
364+
Table latex Yes Yes No Yes
365+
Table rdb Yes Yes No Yes
366+
367+
If you make a mistake and specify an unavailable or incorrect ``format``, the
368+
error message will now list all the available formats.
264369

265370
Convolution
266371
-----------

0 commit comments

Comments
 (0)