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).
is_image_like(colname)	Check whether the column contains image-like data (numpy arrays with at least 2 dimensions).
load_column(filename[, colname])	Read in a file containing a single column as its own data file.
make_trajectory_list()	Create a list of Trajectory objects.
read_table(filename[, track_filtered, ...])	Read the Results 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.
sort(colname[, descending])	Sort the results by a given column.
update_obs_valid(obs_valid[, drop_empty_rows])	Updates or appends the 'obs_valid' column.
write_column(colname, filename[, overwrite])	Save a single column's data as its own data file.
write_filtered_stats(filename)	Write out the filtering statistics to a human readable CSV file.
write_table(filename[, overwrite, extra_meta])	Write the unfiltered results to a single 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.

is_image_like(colname)

Check whether the column contains image-like data (numpy arrays with at least 2 dimensions).

Parameters:

colnamestr

The name of the column to check.

load_column(filename, colname=None)

Read in a file containing a single column as its own data file. The file type is inferred from the filename suffix. Supported formats include numpy (.npy), ecsv (.ecsv), parquet (.parq or .parquet), or fits (.fits).

Parameters:

filenamestr or Path

The file name for the ouput file. Must have a suffix matching one of “.npy”, “.ecsv”, “.parquet”, “.parq”, or “.fits”.

colnamestr

The name of the column to save. If None this is automatically inferred from 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.

classmethod read_table(filename, track_filtered=False, load_aux_files=False)

Read the Results from a table file. The file format is automatically determined from the file name’s suffix which must be one of “.ecsv”, “.parquet”, “.parq”, or “.hdf5”.

Parameters:

filenamestr

The name of the file to load.

track_filteredbool

Indicates whether the object should track future filtered points.

load_aux_filesbool

If True the code will check the file path for any auxiliary files that share the same base name as the main file and load them. Default: False

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.

sort(colname, descending=True)

Sort the results by a given column.

Parameters:

colnamestr

The name of the column to sort by.

reversdescendingebool

Whether to sort in descending order. By default this is true, so that the highest likelihoods and num obs are the the top. Default: True.

Returns:

selfResults

Returns a reference to itself to allow chaining.

Raises:

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

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, overwrite=True)

Save a single column’s data as its own data file. The file type is inferred from the filename suffix. Supported formats include numpy (.npy), ecsv (.ecsv), parquet (.parq or .parquet), or fits (.fits).

Parameters:

colnamestr

The name of the column to save.

filenamestr or Path

The file name for the ouput file. Must have a suffix matching one of “.npy”, “.ecsv”, “.parquet”, “.parq”, or “.fits”.

overwritebool

Overwrite the file if it already exists. Default: True

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, extra_meta=None)

Write the unfiltered results to a single file. The file format is automatically determined from the file name’s suffix which must be one of “.ecsv”, “.parquet”, “.parq”, or “.hdf5”. We recommend “.parquet”.

Parameters:

filenamestr

The name of the result file. Must have a suffix matching one of “.ecsv”, “.parquet”, “.parq”, or “.hdf5”.

overwritebool

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

extra_metadict, optional

Any additional meta data to save with the table.

kbmod.results.write_results_to_files_destructive(filename, results, extra_meta=None, separate_col_files=None, drop_columns=None, overwrite=True)

Write the results to one or more files.

Parameters:

filenamestr or Path

The name of the file to output the results to.

resultsResults

The results to output. These results are modified in-place to drop columns as they are written out.

extra_metadict, optional

Any additional meta data to save with the table. This is saved in the table’s meta data and can be retrieved later.

separate_col_fileslist of str, optional

A list of column names to write to separate files. If None, no separate files are written.

drop_columnslist of str, optional

A list of column names to skip when outputting results. If None, no columns are skipped.

overwritebool, optional

If True, overwrite existing files. If False, do not overwrite existing files. Defaults to True.