Read Input

Module to read user input from files and create standardized input for orbitize

orbitize.read_input.read_file(filename)

Reads data from any file for use in orbitize readable by astropy.io.ascii.read(), including csv format. See the astropy docs.

There are two ways to provide input data to orbitize.

The first way is to provide astrometric measurements, shown with the following example.

Example of an orbitize-readable .csv input file:

epoch,object,raoff,raoff_err,decoff,decoff_err,radec_corr,sep,sep_err,pa,pa_err,rv,rv_err
1234,1,0.010,0.005,0.50,0.05,0.025,,,,,,
1235,1,,,,,,1.0,0.005,89.0,0.1,,
1236,1,,,,,,1.0,0.005,89.3,0.3,,
1237,0,,,,,,,,,,10,0.1

Each row must have epoch (in MJD=JD-2400000.5) and object. Objects are numbered with integers, where the primary/central object is 0. If you have, for example, one RV measurement of a star and three astrometric measurements of an orbiting planet, you should put 0 in the object column for the RV point, and 1 in the columns for the astrometric measurements.

Each line must also have at least one of the following sets of valid measurements:

• RA and DEC offsets [mas], or

• sep [mas] and PA [degrees East of NCP], or

• RV measurement [km/s]

Note

Columns with no data can be omitted (e.g. if only separation and PA are given, the raoff, deoff, and rv columns can be excluded).

If more than one valid set is given (e.g. RV measurement and astrometric measurement taken at the same epoch), read_file() will generate a separate output row for each valid set.

For RA/Dec and Sep/PA, you can also specify a correlation term. This is useful when your error ellipse is tilted with respect to the RA/Dec or Sep/PA. The correlation term is the Pearson correlation coefficient (ρ), which corresponds to the normalized off diagonal term of the covariance matrix. Let’s define the covariance matrix as C = [[C_11, C_12], [C_12, C_22]]. Here C_11 = quant1_err^2 and C_22 = quant2_err^2 and C_12 is the off diagonal term. Then ρ = C_12/(sqrt(C_11)sqrt(C_22)). Essentially it is the covariance normalized by the variance. As such, -1 ≤ ρ ≤ 1. You can specify either as radec_corr or seppa_corr. By definition, both are dimensionless, but one will correspond to RA/Dec and the other to Sep/PA. An example of real world data that reports correlations is this GRAVITY paper where table 2 reports the correlation values and figure 4 shows how the error ellipses are tilted.

Alternatively, you can also supply a data file with the columns already corresponding to the orbitize format (see the example in description of what this method returns). This may be useful if you are wanting to use the output of the write_orbitize_input method.

Note

RV measurements of objects that are not the primary should be relative to the barycenter RV. For example, if the barycenter has a RV of 20 +/- 1 km/s, and you’ve measured an absolute RV for the secondary of 15 +/- 2 km/s, you should input an RV of -5.0 +/- 2.2 for object 1.

Note

When providing data with columns in the orbitize format, there should be no empty cells. As in the example below, when quant2 is not applicable, the cell should contain nan.

Parameters

filename (str or astropy.table.Table) – Input filename or the actual table object

Returns

Table containing orbitize-readable input for given object. For the example input above:

 epoch  object  quant1 quant1_err  quant2 quant2_err quant12_corr quant_type
float64  int   float64  float64   float64  float64     float64       str5
------- ------ ------- ---------- ------- ---------- ------------ ----------
1234.0      1    0.01      0.005     0.5       0.05      0.025        radec
1235.0      1     1.0      0.005    89.0        0.1        nan        seppa
1236.0      1     1.0      0.005    89.3        0.3        nan        seppa
1237.0      0    10.0        0.1     nan        nan        nan           rv

where quant_type is one of “radec”, “seppa”, or “rv”.

If quant_type is “radec” or “seppa”, the units of quant are mas and degrees, if quant_type is “rv”, the units of quant are km/s

Return type

astropy.Table

Written: Henry Ngo, 2018

Updated: Vighnesh Nagpal, Jason Wang (2020-2021)

orbitize.read_input.write_orbitize_input(table, output_filename, file_type='csv')

Writes orbitize-readable input as an ASCII file

Parameters

• table (astropy.Table) – Table containing orbitize-readable input for given object, as generated by the read functions in this module.

• output_filename (str) – csv file to write to

• file_type (str) –

  Any valid write format for astropy.io.ascii. See the astropy docs. Defaults to csv.

(written) Henry Ngo, 2018