MetaPulsar API Reference

Core Classes

MetaPulsar

Main class for combining pulsar timing data from multiple PTAs.

class MetaPulsar:
    def __init__(self, pulsars: Dict[str, Any], combination_strategy: str = "composite"):
        """Initialize MetaPulsar.
        
        Args:
            pulsars: Dictionary of pulsar data from different PTAs
            combination_strategy: "composite" or "consistent"
        """

MetaPulsarFactory

Factory for creating MetaPulsars.

class MetaPulsarFactory:
    def __init__(self):
        """Initialize factory."""
    
    def create_metapulsar(
        self,
        file_data: Dict[str, Dict[str, Any]],
        combination_strategy: str = "consistent",
        reference_pta: str = None,
        combine_components: List[str] = None,
        add_dm_derivatives: bool = True
    ) -> MetaPulsar:
        """Create MetaPulsar from file data."""
    
    def list_available_pulsars(self, pta_names: List[str] = None) -> List[str]:
        """List available pulsars in specified PTAs."""

FileDiscoveryService

Handles file discovery and PTA configuration management.

class FileDiscoveryService:
    def __init__(self, pta_data_releases: Dict = None):
        """Initialize file discovery service."""

    def list_ptas(self) -> List[str]:
        """List all available PTA names."""

    def discover_all_files_in_ptas(
        self,
        pta_names: List[str] = None
    ) -> Dict[str, List[Dict[str, Any]]]:
        """Discover all file pairs in selected PTAs."""

    def discover_patterns_in_pta(self, pta_name: str) -> List[str]:
        """Discover all file patterns in a single PTA."""

    def add_pta(self, name: str, data_release: Dict) -> None:
        """Add a new PTA configuration."""

ParameterManager

Manages parameter consistency across PTAs.

class ParameterManager:
    def __init__(
        self,
        file_data: Dict[str, Dict[str, Any]],
        reference_pta: str,
        combine_components: List[str],
        add_dm_derivatives: bool = True
    ):
        """Initialize parameter manager."""

    def build_parameter_mappings(
        self,
        merge_astrometry: bool = True,
        merge_spin: bool = True,
        merge_binary: bool = True,
        merge_dm: bool = True
    ) -> ParameterMapping:
        """Build parameter mappings for consistency."""

MockPulsar

Creates synthetic pulsar data for testing.

class MockPulsar:
    def __init__(
        self,
        toas: np.ndarray,
        residuals: np.ndarray,
        errors: np.ndarray,
        freqs: np.ndarray,
        flags: Dict[str, np.ndarray],
        telescope: str,
        name: str
    ):
        """Initialize mock pulsar."""

TimFileAnalyzer

Analyzes TIM files for metadata.

class TimFileAnalyzer:
    def __init__(self, tim_file_path: str):
        """Initialize analyzer with TIM file path."""

    def analyze(self) -> Dict[str, Any]:
        """Analyze TIM file and return metadata."""

Utility Functions

create_staggered_selection

Creates Enterprise-compatible selection functions.

def create_staggered_selection(
    flags: Dict[str, np.ndarray],
    freqs: np.ndarray,
    primary_flag: str,
    fallback_flags: List[str] = None,
    freq_bands: Dict[str, Tuple[float, float]] = None
) -> List[Callable]:
    """Create staggered selection functions for Enterprise."""

Exceptions

PINTDiscoveryError

Raised when PINT component discovery fails.

class PINTDiscoveryError(Exception):
    """Exception raised when PINT component discovery fails."""

ParameterInconsistencyError

Raised when parameter consistency checks fail.

class ParameterInconsistencyError(Exception):
    """Exception raised when parameter consistency checks fail."""

Data Structures

ParameterMapping

Contains parameter mapping information.

class ParameterMapping:
    def __init__(self):
        self.merged_parameters: List[str]
        self.pta_specific_parameters: Dict[str, List[str]]
        self.fitparameters: Dict[str, Any]