Module: results

Results is a column-based data structure for tracking results with additional global data and helper functions for filtering and maintaining consistency between different attributes in each row.

class kbmod.results.Results(data=None, track_filtered=False, wcs=None)

This class stores a collection of related data from all of the kbmod results.

At a minimum it contains columns for the trajectory information: (x, y, vx, vy, likelihood, flux, obs_count) but additional columns can be added as needed.

Attributes:

tableastropy.table.Table

The stored results data.

wcsastropy.wcs.WCS

A global WCS for all the results. This is optional and primarily used when saving the results to a file so as to preserve the WCS for future analysis.

mjd_midnp.ndarray

An array of the times (mid-MJD) for each observation in UTC. This is optional and primarily used when saving the results to a file so as to preserve the times for future analysis.

track_filteredbool

Whether to track (save) the filtered trajectories. This will use more memory and is recommended only for analysis.

filtereddict

A dictionary mapping a string of filtered name to a table of the results removed by that filter.

filtered_statsdict

A dictionary mapping a string of filtered name to a count of how many results were removed by that filter. This is maintained even if track_filtered is False.

Methods

add_psi_phi_data(psi_array, phi_array[, ...])	Append columns for the psi and phi data and use this to update the relevant trajectory information.
compute_likelihood_curves([filter_obs, ...])	Create a matrix of likelihood curves where each row has a likelihood curve for a single trajectory.
copy()	Return a deep copy of the current Results object.
extend(results2)	Append the results in a second Results object to the current one.
filter_rows(rows[, label])	Filter the rows in the Results to only include those indices that are provided in a list of row indices (integers) or marked True in a mask.
from_trajectories(trajectories[, track_filtered])	Extract data from a list of Trajectory objects.
from_trajectory_file(filename[, track_filtered])	Load the results from a saved Trajectory file.
get_filtered([label])	Get the results filtered at a given stage or all stages.
get_num_times()	Get the number of observations times in the data as computed from the lightcurves or the marked valid observations.
is_empty_value(colname)	Create a Boolean vector indicating whether the entry in each row is an 'empty' value (None or anything of length 0).
load_column(filename, colname)	Read in a file containing a single column as numpy data and join it into the table.
make_trajectory_list()	Create a list of Trajectory objects.
mask_based_on_invalid_obs(input_mat, mask_value)	Mask the entries in a given input matrix based on the invalid observations in the results.
read_table(filename[, track_filtered])	Read the ResultList from a table file.
remove_column(colname)	Remove a column from the results table.
revert_filter([label, add_column])	Revert the filtering by re-adding filtered ResultRows.
set_mjd_utc_mid(times)	Set the midpoint times in UTC MJD.
update_obs_valid(obs_valid[, drop_empty_rows])	Updates or appends the 'obs_valid' column.
write_column(colname, filename)	Save a single column's data as a numpy data file.
write_filtered_stats(filename)	Write out the filtering statistics to a human readable CSV file.
write_table(filename[, overwrite, ...])	Write the unfiltered results to a single (ecsv) file.

add_psi_phi_data(psi_array, phi_array, obs_valid=None)

Append columns for the psi and phi data and use this to update the relevant trajectory information.

Parameters:

psi_arraynumpy.ndarray

An array of psi_curves with one for each row.

phi_arraynumpy.ndarray

An array of psi_curves with one for each row.

obs_validnumpy.ndarray, optional

An optional array of obs_valid arrays with one for each row.

Returns:

selfResults

Returns a reference to itself to allow chaining.

Raises:

Raises a ValueError if the input arrays are not the same size as the table

or a given pair of rows in the arrays are not the same length.

compute_likelihood_curves(filter_obs=True, mask_value=0.0)

Create a matrix of likelihood curves where each row has a likelihood curve for a single trajectory.

Parameters:

filter_obsbool

Filter any indices marked as invalid in the ‘obs_valid’ column. Substitutes the value of mask_value in their place.

mask_valuefloat

A floating point value to substitute into the masked entries. Commonly used values are 0.0 and np.NAN, which allows filtering for some numpy operations.

Returns:

lh_matrixnumpy.ndarray

The likleihood curves for each trajectory.

Raises:

Raises an IndexError if the necessary columns are missing.

copy()

Return a deep copy of the current Results object.

extend(results2)

Append the results in a second Results object to the current one.

Parameters:

results2Results

The data structure containing additional results to add.

Returns:

selfResults

Returns a reference to itself to allow chaining.

Raises:

Raises a ValueError if the columns of the results do not match.

filter_rows(rows, label='')

Filter the rows in the Results to only include those indices that are provided in a list of row indices (integers) or marked True in a mask.

Parameters:

rowsnumpy.ndarray

Either a Boolean array of the same length as the table or list of integer row indices to keep.

labelstr

The label of the filtering stage to use.

Returns:

selfResults

Returns a reference to itself to allow chaining.

classmethod from_trajectories(trajectories, track_filtered=False)

Extract data from a list of Trajectory objects.

Parameters:

trajectorieslist[Trajectory]

A list of trajectories to include in these results.

track_filteredbool

Indicates whether to track future filtered points.

classmethod from_trajectory_file(filename, track_filtered=False)

Load the results from a saved Trajectory file.

Parameters:

filenamestr

The file name for the input file.

track_filteredbool

Whether to track (save) the filtered trajectories. This will use more memory and is recommended only for analysis.

Raises:

Raises a FileNotFoundError if the file does not exist.

get_filtered(label=None)

Get the results filtered at a given stage or all stages.

Parameters:

labelstr

The filtering stage to use. If no label is provided, return all filtered rows.

Returns:

resultsastropy.table.Table or None

A table with the filtered rows or None if there are no entries.

get_num_times()

Get the number of observations times in the data as computed from the lightcurves or the marked valid observations. Returns 0 if there is no time series information.

Returns:

resultint

The number of time steps. Returns 0 if there is no such information.

is_empty_value(colname)

Create a Boolean vector indicating whether the entry in each row is an ‘empty’ value (None or anything of length 0). Used to mark or filter missing values.

Parameters:

colnamestr

The name of the column to check.

Returns:

resultnumpy.ndarray

An array of Boolean values indicating whether the result is one of the empty values.

load_column(filename, colname)

Read in a file containing a single column as numpy data and join it into the table. The column must be the same length as the current table.

Parameters:

filenamestr

The file name to read.

colnamestr

The name of the column in which to save the data.

Raises:

Raises a FileNotFoundError if the file does not exist.

Raises a ValueError if column is of the wrong length.

make_trajectory_list()

Create a list of Trajectory objects.

Returns:

trajectorieslist[Trajectory]

The Trajectory objects.

mask_based_on_invalid_obs(input_mat, mask_value)

Mask the entries in a given input matrix based on the invalid observations in the results. If an observation in result i, time t is invalid, then the corresponding entry input_mat[i][t] will be masked. This helper function is used when computing statistics on arrays of information.

The input should be N x T where N is the number of results and T is the number of time steps.

Parameters:

input_matnumpy.ndarray

An N x T input matrix.

mask_valueany

The value to subsitute into the input array.

Returns:

resultnumpy.ndarray

An N x T output matrix where result[i][j] is input_mat[i][j] if result i, timestep j is valid and mask_value otherwise.

Raises:

Raises a ValueError if the array sizes do not match.

classmethod read_table(filename, track_filtered=False)

Read the ResultList from a table file.

Parameters:

filenamestr

The name of the file to load.

track_filteredbool

Indicates whether the object should track future filtered points.

Raises:

Raises a FileNotFoundError if the file is not found.

Raises a KeyError if any of the columns are missing.

remove_column(colname)

Remove a column from the results table.

Parameters:

colnamestr

The name of column to drop.

Raises:

Raises a KeyError if the column does not exist or

is a required column.

revert_filter(label=None, add_column=None)

Revert the filtering by re-adding filtered ResultRows.

Parameters:

labelstr

The filtering stage to use. If no label is provided, revert all filtered rows.

add_columnstr

If not None, add a tracking column with the given name that includes the original filtering reason.

Returns:

selfResults

Returns a reference to itself to allow chaining.

Raises:

ValueError if filtering is not enabled.

KeyError if label is unknown.

Notes

Filtered rows are appended to the end of the list. Does not return the results to the original ordering.

set_mjd_utc_mid(times)

Set the midpoint times in UTC MJD.

update_obs_valid(obs_valid, drop_empty_rows=True)

Updates or appends the ‘obs_valid’ column.

Parameters:

obs_validnumpy.ndarray

An array with one row per results and one column per timestamp with Booleans indicating whether the corresponding observation is valid.

drop_empty_rowsbool

Filter the rows without any valid observations.

Returns:

selfResults

Returns a reference to itself to allow chaining.

Raises:

Raises a ValueError if the input array is not the same size as the table

or a given pair of rows in the arrays are not the same length.

write_column(colname, filename)

Save a single column’s data as a numpy data file.

Parameters:

colnamestr

The name of the column to save.

filenamestr

The file name for the ouput file.

Raises:

Raises a KeyError if the column is not in the data.

write_filtered_stats(filename)

Write out the filtering statistics to a human readable CSV file.

Parameters:

filenamestr

The name of the file to write.

write_table(filename, overwrite=True, cols_to_drop=(), extra_meta=None)

Write the unfiltered results to a single (ecsv) file.

Parameters:

filenamestr

The name of the result file.

overwritebool

Overwrite the file if it already exists. [default: True]

cols_to_droptuple

A tuple of columns to drop (to save space). [default: ()]

extra_metadict, optional

Any additional meta data to save with the table.