DataClass¶

class sbpy.data.DataClass[source]¶

Bases: object

DataClass serves as the base class for all data container classes in sbpy in order to provide consistent functionality. Classes derived from DataClass have the following properties:

The core of DataClass is an QTable object(referred to as the data table below) - a type of Table object that supports the units formalism on a per-column base - which already provides most of the required functionality. DataClass objects can be manually generated from dictionaries (from_dict), list-like objects on a per-column basis(from_columns) or a per-row basis(from_rows), or directly from another QTable object. It is possible to write DataClass objects to a file and from a file.

DataClass objects can hold meta data that are stored as QTable meta data and can be accessed as a DataClass property. Furthermore, DataClass objects have the ability to recognize alternative names for properties stored in the data table and even do transformations.

A few high-level functions for table data access or modification are provided; other, more complex modifications can be applied to the underlying table object(table) directly.

Attributes Summary

`field_names`	Return a list of all field names in the data table.
`meta`	Enables access to the meta data of the underlying data table.
`table`	Return `QTable` object containing all data.

Methods Summary

`add_row`(vals[, names, units])	Add a new row to the end of DataClass.
`apply`(data, name[, unit])	Apply an arbitrarily shaped sequence as additional column to a `DataClass` object and reshape it accordingly.
`from_columns`(columns, names[, units, meta])	Create `DataClass` object from a sequence.
`from_dict`(data[, meta])	Create `DataClass` object from dictionary.
`from_file`(filename[, meta])	Create `DataClass` object from a file using `read`.
`from_rows`(rows, names[, units, meta])	Create `DataClass` object from a sequence.
`from_table`(table[, meta])	Create `DataClass` object from `Table` or `QTable` object.
`to_file`(filename[, format])	Write object to a file using `write`.
`verify_fields`([field])	Verify that the fields have the expected units or object types.
`vstack`(data, **kwargs)	Stack another DataClass object to the end of DataClass

Attributes Documentation

field_names¶: Return a list of all field names in the data table.

meta¶

Enables access to the meta data of the underlying data table.

Examples

>>> from sbpy.data import DataClass
>>> import astropy.units as u
>>> data = DataClass.from_columns([[1, 2, 3, 4]*u.kg,
...                                [5, 6, 7, 8]*u.m],
...                               names=['b', 'c'],
...                               meta={'origin': 'measured'})
>>> data.meta  # meta data access
{'origin': 'measured'}
>>> data.meta['date'] = '2019-06-27'  # meta data modification
>>> data.meta['date']
'2019-06-27'

table¶: Return QTable object containing all data.

Methods Documentation

add_row(vals, names=None, units=None)[source]¶

Add a new row to the end of DataClass.

This is similar to astropy.table.Table.add_row, but allows for a set of different columns in the new row from the original DataClass object. It also allows for aliases of column names.

Parameters:

valsRow, tuple, list, dict: Row to be added
namesiterable of strings, optional: The names of columns if not implicitly specified in vals. Takes precedence over the column names in vals if any.
unitsstr or list-like, optional: Unit labels (as provided by Unit) in which the data provided in rows will be stored in the underlying table. If None, the units as provided by rows are used. If the units provided in units differ from those used in rows, rows will be transformed to the units provided in units. Must have the same length as names and the individual data rows in rows. Default: None

Notes

If a time is included in vals, it can either be an explicit Time object, or a number, Quantity object, or string that can be inferred to be a time by the existing column of the same name or by its position in the sequence. In this case, the type of time values must be valid to initialize an Time object with format=’jd’ or ‘isot’, and the scale of time is default to the scale of the corresponding existing column of time.

Examples

>>> import astropy.units as u
>>> from sbpy.data import DataClass
>>>
>>> data = DataClass.from_dict(
...         {'rh': [1, 2, 3] * u.au, 'delta': [1, 2, 3] * u.au})
>>> row = {'rh': 4 * u.au, 'delta': 4 * u.au, 'phase': 15 * u.deg}
>>> data.add_row(row)

apply(data, name, unit=None)[source]¶

Apply an arbitrarily shaped sequence as additional column to a DataClass object and reshape it accordingly.

Parameters:

datalist or iterable Quantity object: Data to be added in a new column in form of a one-dimensional list or a two-dimensional nested sequence. Each element in data corresponds to one of the rows in the existing data table. If an element of data is a list, the corresponding data table row is repeated the same the number of times as there are elements in this sublist. If data is provided as a flat list and has the same length as the current data table, data will be simply added as a column to the data table and the length of the data table will not change. If data is provided as a Quantity object (only possible for flat lists), its unit is adopted, unless unit is specified (not None).
namestr: Name of the new data column.
unitunits object or str, optional: Unit to be applied to the new column. Default: None

Returns:

None

Notes

As a result of this method, the length of the underlying data table will be the same as the length of the flattened data parameter.

Examples

Imagine the following scenario: you obtain photometric measurements of the same asteroid over a number of nights. The following Ephem object summarizes the observations:

>>> from sbpy.data import Ephem
>>> import astropy.units as u
>>> obs = Ephem.from_columns([[2451223, 2451224, 2451226]*u.d,
...                           [120.1, 121.3, 124.9]*u.deg,
...                           [12.4, 12.2, 10.8]*u.deg],
...                          names=('JD', 'RA', 'DEC'))
>>> obs
<QTable length=3>
    JD       RA     DEC
    d       deg     deg
 float64  float64 float64
--------- ------- -------
2451223.0   120.1    12.4
2451224.0   121.3    12.2
2451226.0   124.9    10.8

After analyzing the observations, you would like to add the measured apparent V-band magnitudes to this object. You have one observation from the first night, two from the second night, and three from the third night. Instead of re-creating obs, apply offers a convenient way to supplement obs:

>>> obs.apply([[12.1], [12.5, 12.6], [13.5, 13.4, 13.5]],
...           name='V', unit='mag')
>>> obs
<QTable length=6>
    JD       RA     DEC      V
    d       deg     deg     mag
 float64  float64 float64 float64
--------- ------- ------- -------
2451223.0   120.1    12.4    12.1
2451224.0   121.3    12.2    12.5
2451224.0   121.3    12.2    12.6
2451226.0   124.9    10.8    13.5
2451226.0   124.9    10.8    13.4
2451226.0   124.9    10.8    13.5

Note how the data table has been re-arranged and rows have been duplicated in order to provide the expected shape.

classmethod from_columns(columns, names, units=None, meta={}, **kwargs)[source]¶

Create DataClass object from a sequence. If that sequence is one-dimensional, it is interpreted as a single column; if the sequence is two-dimensional, it is interpreted as a sequence of columns.

Parameters:

columns: list, `~numpy.ndarray`, tuple, or `~astropy.units.Quantity`: Data that will be ingested in DataClass object. A one-dimensional sequence is interpreted as a single column. A two-dimensional sequence is interpreted as a sequence of columns, each of which must have the same length.
names: str or list-like: Field names, must have the same number of names as data columns. Please note that in order to make use of Alternative field names and to ensure compatibility with sbpy functionality, the field names chosen must be in the list of Data Container Field Name Reference.
units: str or list-like, optional: Unit labels (as provided by Unit) in which the data provided in columns will be stored in the underlying table. If None, the units as provided by columns are used. If the units provided in units differ from those used in columns, columns will be transformed to the units provided in units. Must have the same length as names and the individual data columns in columns. Default: None
meta: dictionary, optional: Meta data that will be stored in the data table. Default: empty dictionary
kwargs: additional keyword arguments, optional: Additional keyword arguments that will be passed on to QTable in the creation of the underlying data table.

Returns:

DataClass object

Examples

The following example creates a single-column Ephem object.

>>> from sbpy.data import Ephem
>>> import astropy.units as u
>>> eph = Ephem.from_columns([1, 2, 3, 4]*u.au,
...                          names='a')
>>> eph
<QTable length=4>
   a
   AU
float64
-------
    1.0
    2.0
    3.0
    4.0

This example creates a two-column Ephem object in which units are assigned using the optional units keyword argument.

>>> eph = Ephem.from_columns([[1, 2, 3, 4],
...                           [90, 50, 30, 10]],
...                          names=['r', 'alpha'],
...                          units=['au', 'deg'])
>>> eph
<QTable length=4>
   r     alpha
   AU     deg
float64 float64
------- -------
    1.0    90.0
    2.0    50.0
    3.0    30.0
    4.0    10.0

If units are provided in columns and units, those units in columns will be transformed into those units in units on a per-column basis.

>>> eph = Ephem.from_columns([[1, 2, 3, 4]*u.au,
...                           [90, 50, 30, 10]*u.deg],
...                           names=['r', 'alpha'],
...                           units=['km', 'rad'])
>>> eph
<QTable length=4>
        r                 alpha
        km                 rad
     float64             float64
------------------ -------------------
       149597870.7  1.5707963267948966
       299195741.4  0.8726646259971648
448793612.09999996  0.5235987755982988
       598391482.8 0.17453292519943295

classmethod from_dict(data, meta={}, **kwargs)[source]¶

Create DataClass object from dictionary.

Parameters:

data: `~collections.OrderedDict` or dictionary: Data that will be ingested in DataClass object. Each item in the dictionary will form a column in the data table. The item key will be used as column name, the item value, which must be list-like or a Quantity vector, will be used as data. All columns, i.e., all item values, must have the same length. Please note that in order to make use of Alternative field names and to ensure compatibility with sbpy functionality, the field names chosen must be in the list of Data Container Field Name Reference.
meta: dictionary, optional: Meta data that will be stored in the data table. Default: empty dictionary
kwargs: additional keyword arguments, optional: Additional keyword arguments that will be passed on to QTable in the creation of the underlying data table.

Returns:

DataClass object

Examples

The following example creates a single-row Orbit object (the other DataClass objects work the exact same way).

>>> import astropy.units as u
>>> from sbpy.data import Orbit
>>> orb = Orbit.from_dict({'a': 2.7674*u.au,
...                        'e': 0.0756,
...                        'i': 10.59321*u.deg})
>>> orb  
<QTable length=1>
   a       e       i
   AU             deg
float64 float64 float64
------- ------- --------
 2.7674  0.0756 10.59321

A double-row Orbit example would look like this:

>>> orb = Orbit.from_dict({'a': [2.7674, 3.123]*u.au,
...                        'e': [0.0756, 0.021],
...                        'i': [10.59321, 3.21]*u.deg})
>>> orb  
<QTable length=2>
   a       e       i
   AU             deg
float64 float64 float64
------- ------- --------
 2.7674  0.0756 10.59321
  3.123   0.021     3.21

Note how in this case a list is passed to each key of the dictionary; if a unit is provided for either element in the dictionary, the corresponding Unit has to be multiplied to this list, forming a Quantity vector.

Since dictionaries have no specific order, the ordering of the column in the example above is not defined. If your data table requires a specific order, use OrderedDict. This example also shows the use of meta data.

>>> from collections import OrderedDict
>>> orb = Orbit.from_dict(OrderedDict([('a', [2.7674, 3.123]*u.au),
...                                    ('e', [0.0756, 0.021]),
...                                    ('i', [10.59, 3.21]*u.deg)]),
...                                   meta={'targetname': 'asteroid'})
>>> orb  
<QTable length=2>
   a       e       i
   AU             deg
float64 float64 float64
------- ------- -------
 2.7674  0.0756   10.59
  3.123   0.021    3.21
>>> orb.meta
{'targetname': 'asteroid'}
>>> orb.meta['targetname']
'asteroid'

classmethod from_file(filename, meta={}, **kwargs)[source]¶

Create DataClass object from a file using read.

Parameters:

filenamestr: Name of the file that will be read and parsed.
metadictionary, optional: Meta data that will be stored in the data table. If the data to be read already holds meta data, meta will be added. Default: empty dictionary
kwargsadditional parameters: Optional parameters that will be passed on to read.

Returns:

DataClass object

Notes

This function is merely a wrapper around read. Please note that the file formats available (see here for a list of available formats) provide varying support for units and meta data. For instance, basic, csv, html, and latex do not provide unit or meta data information. However, fits, cds, daophot, ecsv, and ipac do support units and meta data.

Examples

>>> from sbpy.data import DataClass

>>> dat = DataClass.from_file('data.txt',
...                           format='ascii') 

classmethod from_rows(rows, names, units=None, meta={}, **kwargs)[source]¶

Create DataClass object from a sequence. If that sequence is one-dimensional, it is interpreted as a single row; if the sequence is two-dimensional, it is interpreted as a sequence of rows.

Parameters:

rowslist, ndarray, or tuple: Data that will be ingested in DataClass object. A one-dimensional sequence is interpreted as a single row. A two-dimensional sequence is interpreted as a sequence of rows, each of which must have the same length.
namesstr or list: Column names, must have the same number of names as data columns in each row. Please note that in order to make use of Alternative field names and to ensure compatibility with sbpy functionality, the field names chosen must be in the list of Data Container Field Name Reference.
unitsstr or list-like, optional: Unit labels (as provided by Unit) in which the data provided in rows will be stored in the underlying table. If None, the units as provided by rows are used. If the units provided in units differ from those used in rows, rows will be transformed to the units provided in units. Must have the same length as names and the individual data rows in rows. Default: None
metadictionary, optional: Meta data that will be stored in the data table. Default: empty dictionary
kwargsadditional keyword arguments, optional: Additional keyword arguments that will be passed on to QTable in the creation of the underlying data table.

Returns:

DataClass object

Examples

The following example creates a single-row Phys object.

>>> from sbpy.data import Phys
>>> import astropy.units as u
>>> phys = Phys.from_rows([1*u.km, 0.05, 17*u.mag],
...                       names=['diam', 'pv', 'absmag'])
>>> phys
<QTable length=1>
  diam     pv    absmag
   km             mag
float64 float64 float64
------- ------- -------
    1.0    0.05    17.0

Providing units allows providing unit-less data in rows:

>>> phys = Phys.from_rows([[1, 0.05, 17],
...                        [2, 0.05, 16]],
...                       names=['diam', 'pv', 'absmag'],
...                       units=['km', None, 'mag'])
>>> phys
<QTable length=2>
  diam     pv    absmag
   km             mag
float64 float64 float64
------- ------- -------
    1.0    0.05    17.0
    2.0    0.05    16.0

classmethod from_table(table, meta={}, **kwargs)[source]¶

Create DataClass object from Table or QTable object.

Parameters:

tableTable object: Data that will be ingested in DataClass object. Must be a Table or QTable object. Please note that in order to make use of Alternative field names and to ensure compatibility with sbpy functionality, the field names chosen must be in the list of Data Container Field Name Reference.
metadictionary, optional: Meta data that will be stored in the data table. If table already holds meta data, meta will be added. Default: empty dictionary
kwargsadditional keyword arguments, optional: Additional keyword arguments that will be passed on to QTable in the creation of the underlying data table.

Returns:

DataClass object

Examples

>>> from astropy.table import QTable
>>> import astropy.units as u
>>> from sbpy.data import DataClass
>>> tab = QTable([[1,2,3]*u.kg,
...               [4,5,6]*u.m/u.s,],
...              names=['mass', 'velocity'])
>>> dat = DataClass.from_table(tab)
>>> dat
<QTable length=3>
  mass  velocity
   kg    m / s
float64 float64
------- --------
    1.0      4.0
    2.0      5.0
    3.0      6.0

to_file(filename, format='ascii', **kwargs)[source]¶

Write object to a file using write.

Parameters:

filenamestr: Name of the file that will be written.
formatstr, optional: Data format in which the file should be written. Default: ASCII
kwargsadditional parameters: Optional parameters that will be passed on to write.

Returns:

None

Notes

This function is merely a wrapper around write. Please note that the file formats available (see here for a list of available formats) provide varying support for units and meta data. For instance, basic, csv, html, and latex do not provide unit or meta data information. However, fits, cds, daophot, ecsv, and ipac do support units and meta data.

Examples

>>> from sbpy.data import DataClass
>>> import astropy.units as u
>>> dat = DataClass.from_columns([[1, 2, 3]*u.deg,
...                               [4, 5, 6]*u.km,
...                               ['aa', 'bb', 'cc']],
...                              names=('aa', 'bb', 'cc'))
>>> dat.to_file('test.txt')  

verify_fields(field=None)[source]¶

Verify that the fields have the expected units or object types.

See sbpy.data.Conf for field definitions.

Parameters:

fieldstring, optional: Only check this field.

Raises:

astropy.units.UnitsError on unit error, TypeError on object error.

vstack(data, **kwargs)[source]¶

Stack another DataClass object to the end of DataClass

Similar to vstack, the DataClass object to be stacked doesn’t have to have the same set of columns as the existing object. The join_type keyword parameter will be used to decide how to process the different sets of columns.

Joining will be in-place.

Parameters:

dataDataClass, dict, Table: Object to be joined with the current object
kwargsdict: Keyword parameters accepted by vstack.

Examples

>>> import astropy.units as u
>>> from sbpy.data import DataClass
>>>
>>> data1 = DataClass.from_dict(
...         {'rh': [1, 2, 3] * u.au, 'delta': [1, 2, 3] * u.au})
>>> data2 = DataClass.from_dict(
...         {'rh': [4, 5] * u.au, 'phase': [15, 15] * u.deg})
>>> data1.vstack(data2)

Navigation

DataClass¶