Skip to content

data_loader

Module for loading pulsar data.

LoadWidebandPulsarData 

LoadWidebandPulsarData(ds_psr)

A class to load and process pulsar data at a single frequency channel.

Attributes

toas : np.ndarray Times of arrival of the pulsar signals. toaerrs : np.ndarray Errors associated with the times of arrival. residuals : np.ndarray Residuals of the pulsar timing model. fitpars : dict Fitted parameters of the pulsar timing model. toa_diffs : np.ndarray Differences between consecutive times of arrival. toa_diff_errors : np.ndarray Errors associated with the differences between consecutive times of arrival. M_matrix : np.ndarray Design matrix for the pulsar timing model. name : str Name of the pulsar. RA : float or str Right Ascension of the pulsar. DEC : float or str Declination of the pulsar.

Methods

init(ds_psr) Initializes the LoadWidebandPulsarData object with pulsar data. read_par_tim(par_file, tim_file, **kwargs) Class method to load pulsar data from parameter and timing files. read_multiple_par_tim(par_files, tim_files, max_files=None) Class method to load multiple par/tim file pairs and return aggregated DataFrames and an angular separation matrix.

Parameters

ds_psr : object An object containing pulsar data (e.g., an instance of enterprise.pulsar.Pulsar) with attributes: toas, toaerrs, residuals, fitpars, Mmat, name, _raj, and _decj.

process_pulsar_residuals_by_epoch staticmethod 

process_pulsar_residuals_by_epoch(list_of_dfs)

Post-process the residuals from a list of pulsar DataFrames that share the same (or very similar)time sampling.

This function takes a list of DataFrames, each expected to have the same shape and contain 'toas', 'residuals', and 'error' columns. It assumes a perfect 1:1 correspondence between rows across all DataFrames, meaning each row index represents the same observation epoch across all DataFrames. It calculates the average 'toas' across all DataFrames and collects the 'residuals' and 'error' values into matrices.

IMPORTANT: This function is NOT suitable for processing collections of pulsars with uneven sampling or different observation epochs. It requires that all DataFrames have identical row indices representing the same epochs.

Parameters:

  • list_of_dfs –

    A list of pandas DataFrames. Each DataFrame must have the same shape and contain the columns 'toas', 'residuals', and 'error'.

Returns
A dictionary containing three NumPy arrays:
- 'toas': 1D array of average TOAs across all input DataFrames for each row index (shape: nrows).
- 'residuals': 2D array where each column corresponds to the 'residuals' from one input DataFrame (shape: nrows x num_dfs).
- 'errors': 2D array where each column corresponds to the 'error' from one input DataFrame (shape: nrows x num_dfs).
Raises
ValueError: If the input list `list_of_dfs` is empty.
ValueError: If not all DataFrames in the list have the same shape.
ValueError: If any DataFrame is missing one of the required columns
            ('toas', 'residuals', 'error').

get_processed_residuals staticmethod 

get_processed_residuals(directory, excluded_psrs=[])

Get the processed residuals from the data.

Returns

dict A dictionary containing: - 'processed_residuals': tuple of (average_toas_array, residuals_array, errors_array) - 'metadata': DataFrame containing pulsar metadata - 'design_matrices': list of design matrices for each pulsar - 'parameter_covariances': list of parameter covariance matrices - 'hd_correlation': matrix of Hellings-Downs correlations

get_par_value staticmethod 

get_par_value(filename: str, parameter: str) -> float | None

Get the value of a parameter from a parameter file.

Parameters:

  • filename (str) –

    Path to the parameter file

  • parameter (str) –

    Name of the parameter to retrieve

Returns
The parameter value as a float, or None if not found
Raises
FileNotFoundError: If the parameter file doesn't exist
ValueError: If the parameter value cannot be converted to float

read_par_tim classmethod 

read_par_tim(par_file: str, tim_file: str, **kwargs) -> LoadWidebandPulsarData

Load the pulsar data from the specified parameter and timing files.

Parameters

par_file : str Path to the parameter file. tim_file : str Path to the timing file. **kwargs : dict Additional keyword arguments to pass to enterprise.pulsar.Pulsar.

Returns

LoadWidebandPulsarData An instance of LoadWidebandPulsarData initialized with the loaded data.

read_multiple_par_tim classmethod 

read_multiple_par_tim(par_files: list[str], tim_files: list[str], max_files: int | None = None, **kwargs) -> tuple[list[pd.DataFrame], pd.DataFrame, list[np.ndarray], list[np.ndarray]]

Load multiple par/tim file pairs.

Parameters

par_files : list of str List of parameter file paths. tim_files : list of str List of timing file paths. max_files : int, optional If provided, only the first max_files pairs will be processed. **kwargs : dict Additional keyword arguments to pass to enterprise.pulsar.Pulsar.

Returns

pulsar_data_frames : list of pd.DataFrame List of DataFrames, each containing TOAs, residuals, and errors for a single pulsar. Each DataFrame has columns: 'toas', 'residuals', 'error'. metadata_combined : pd.DataFrame A DataFrame containing per-pulsar metadata such as name, RA, DEC, the dimension of the design matrix, and F0 (pulsar frequency). design_matrices : list of np.ndarray List of scaled design matrices (M_scaled) for each pulsar. parameter_covariances : list of np.ndarray List of parameter covariance matrices (P_eps) for each pulsar.

Notes

For standard RA/DEC in radians: - RA is treated as the azimuth (φ). - DEC is converted to co-latitude: θ = π/2 − DEC.