Catalog¶

1 - Interface¶

This module is the interface for gravitational wave source catalogs. It is responsible for :

registering new catalog implementations as plugins

loading detections and source posterior samples

class lisacattools.catalog.GWCatalog[source]¶

Interface for handling a GW catalog.

abstract describe_source_samples(source_name: str) → DataFrame[source]¶

Statistical summary of the source posterior samples

Parameters:: source_name (str) – source name
Raises:: NotImplementedError – Not implemented
Returns:: statistics
Return type:: pd.DataFrame

abstract get_attr_detections() → List[str][source]¶

Returns the attributes of the catalog.

Raises:: NotImplementedError – Not implemented
Returns:: the list of attributes
Return type:: List[str]

abstract get_attr_source_samples(source_name: str) → List[str][source]¶

Returns the attributes of the source posterior samples

Parameters:: source_name (str) – source name
Raises:: NotImplementedError – Not implemented
Returns:: the attributes
Return type:: List[str]

abstract get_detections(attr: List[str] | str | None = None) → List[str] | DataFrame | Series[source]¶

Returns the GW detections.

When no argument is provided, the name of each detection is returned. When arguments are provided, each detection is returned with the attributes.

Parameters:

attr (Union[List[str], str], optional) – List of attributes or
None. (single attribute. Defaults to) –

Raises:

NotImplementedError – Not implemented

Returns:

the name of each detection or the requested attributes of each detection

Return type:

Union[List[str], pd.DataFrame, pd.Series]

abstract get_median_source(attr: str) → DataFrame[source]¶

Returns the source corresponding to the median of the specified attribute.

Parameters:: attr (str) – attribute name
Raises:: NotImplementedError – Not implemented
Returns:: the source for which the median is computed on the attribute
Return type:: pd.DataFrame

abstract get_source_samples(source_name: str, attr: List[str]) → DataFrame[source]¶

Returns the posterior samples of the source

Parameters:

source_name (str) – source name
attr (List[str]) – the list of attributes to return in the result

Raises:

NotImplementedError – [description]

Returns:

the posterior samples of the source

Return type:

pd.DataFrame

abstract property location: str¶

Returns the location of the GW catalog.

Raises:: NotImplementedError – Not implemented
Returns:: the location of the GW catalog
Return type:: str

abstract property name: str¶

Returns the name of the GW catalog.

Raises:: NotImplementedError – Not implemented
Returns:: name of the GW catalog
Return type:: str

class lisacattools.catalog.GWCatalogType[source]¶

GW catalog implementation.

New implementations can be added as an attribute using the register method of the GWCatalogs class.

class GWCatalogPlugin(module_name: str, class_name: str)[source]¶

Store information to load a plugin implementing the GW catalog.

The stored information is: - the module name - the class name

class lisacattools.catalog.GWCatalogs[source]¶

Interface fo handling time-evolving GW catalogs

abstract property count: int¶

Count the number of catalogs in the catalog set.

Getter:: Returns the number of catalogs in the catalog set
Type:: int

static create(type: GWCatalogPlugin, directory: str, accepted_pattern: str | None = None, rejected_pattern: str | None = None, *args, **kwargs) → GWCatalogs[source]¶

Create a new object for handling a set of specific catalogs.

Catalogs are loaded according a set of filters : the accepted and rejected pattern.

Note:¶

The extra_directories parameter can be given as input in order to load catalogs in other directories. a list of directories is expected for extra_directories parameter. For example:

``` GWCatalogs.create(

GWCatalogType.UCB, “/tmp”, “.h5”, “*chain”, extra_direcories=[“.”, “./tutorial”]

)¶

param type:: Type of catalog
type type:: GWCatalogType.GWCatalogPlugin
param directory:: Directory where the data are located
type directory:: str
param accepted_pattern:: pattern to select files in the
type accepted_pattern:: str, optional
param directory:
type directory:: e.g. ‘*.h5’
param rejected_pattern:: pattern to reject from the list
type rejected_pattern:: str, optional
param built using accepted_pattern. Default None:
returns:: the object implementing a set of specific catalogs
rtype:: GWCatalogs

abstract property files: List[str]¶

Returns the list of files matching the accepted and rejected pattern.

Getter:: Returns the number of catalogs in the catalog set
Type:: List[str]

abstract get_catalog(idx: int) → GWCatalog[source]¶

Returns a catalog based on its position in the catalog set

Parameters:: idx (int) – position of the catalog (first idx: 0)
Raises:: NotImplementedError – When the method is not implemented
Returns:: catalog
Return type:: GWCatalog

abstract get_catalog_by(name: str) → GWCatalog[source]¶

Returns a catalog based on its name in the catalog set

Parameters:: name (str) – name of the catalog
Raises:: NotImplementedError – When the method is not implemented
Returns:: the catalog
Return type:: GWCatalog

abstract get_catalogs_name() → List[str][source]¶

Returns the name of each catalog included in the catalog set

Raises:: NotImplementedError – When the method is not implemented
Returns:: name of each catalog
Return type:: List[str]

abstract get_first_catalog() → GWCatalog[source]¶

Returns the first catalog from the catalog set

Raises:: NotImplementedError – When the method is not implemented
Returns:: the fist catalog
Return type:: GWCatalog

abstract get_last_catalog() → GWCatalog[source]¶

Returns the last catalog from the catalog set.

Raises:: NotImplementedError – When the method is not implemented
Returns:: the last catalog
Return type:: GWCatalog

abstract get_lineage(cat_name: str, src_name: str) → DataFrame[source]¶

Returns the history of a source (src_name: str) including metadata and point estimates through a series of preceeding catalogs. Series starts at current catalog (cat_name: str) and traces a source’s history back.

Parameters:

cat_name (str) – catalog from which the lineage starts
src_name (str) – particular source

Raises:

NotImplementedError – When the method is not implemented

Returns:

history of a parituclar source including metadata and point estimates through a series of preceeding catalogs.

Return type:

pd.DataFrame

abstract get_lineage_data(lineage: DataFrame) → DataFrame[source]¶

Returns the posterior samples of a particular source at all different epochs of obervation in the DataFrame returned by get_lineage(). The samples are concatenated into a single DataFrame.

Parameters:

lineage (pd.DataFrame) – time-dependent catalog for the evolution
by (of a particular source in a series of catalogs returned) –
get_lineage() –

Raises:

NotImplementedError – When the method is not implemented

Returns:

posterior samples of a particular source at all different epochs of obervation in the DataFrame returned by get_lineage().

Return type:

pd.DataFrame

abstract property metadata: DataFrame¶

metadata.

Getter:: Returns the metadata of the catalog set
Type:: pd.DataFrame

static register(type: str, nodule_name: str, class_name: str)[source]¶

Register a new implementation of GWCatalogs

Parameters:

type (str) – name of the implementation
nodule_name (str) – nodule name where the implementation is done
class_name (str) – class name of the implementation

2 - MBH plugin¶

class lisacattools.plugins.mbh.MbhCatalogs(path: str, accepted_pattern: str | None = 'MBH_wk*C.h5', rejected_pattern: str | None = None, *args, **kwargs)[source]¶

Implementation of the MBH catalogs.

_read_cats(cat_file: str) → DataFrame[source]¶

Reads the metadata of a given catalog and the location of the file.

Parameters:: cat_file (str) – catalog to load
Returns:: pandas data frame
Return type:: pd.DataFrame

_search_directories(path: str, extra_directories: List[str]) → List[str][source]¶

Compute the list of directories on which the pattern will be applied.

Parameters:

path (str) – main path
extra_directories (List[str]) – others directories

Returns:

list of directories on which the pattern will be applied

Return type:

List[str]

_search_files(directories: List[str], accepted_pattern, rejected_pattern) → List[str][source]¶

Search files in directories according to a set of constraints : accepted and rejected patterns

Parameters:

directories (List[str]) – List of directories to scan
accepted_pattern ([type]) – pattern to get files
rejected_pattern ([type]) – pattern to reject files

Returns:

List of files

Return type:

List[str]

property count: int¶

Count the number of catalogs in the catalog set.

Getter:: Returns the number of catalogs in the catalog set
Type:: int

property files: List[str]¶

Returns the list of files matching the accepted and rejected pattern.

Getter:: Returns the number of catalogs in the catalog set
Type:: List[str]

get_catalog(idx: int) → GWCatalog[source]¶

Returns a catalog based on its position in the catalog set

Parameters:: idx (int) – position of the catalog (first idx: 0)
Raises:: NotImplementedError – When the method is not implemented
Returns:: catalog
Return type:: GWCatalog

get_catalog_by(name: str) → GWCatalog[source]¶

Returns a catalog based on its name in the catalog set

Parameters:: name (str) – name of the catalog
Raises:: NotImplementedError – When the method is not implemented
Returns:: the catalog
Return type:: GWCatalog

get_catalogs_name() → List[str][source]¶

Returns the name of each catalog included in the catalog set

Raises:: NotImplementedError – When the method is not implemented
Returns:: name of each catalog
Return type:: List[str]

get_first_catalog() → GWCatalog[source]¶

Returns the first catalog from the catalog set

Raises:: NotImplementedError – When the method is not implemented
Returns:: the fist catalog
Return type:: GWCatalog

get_last_catalog() → GWCatalog[source]¶

Returns the last catalog from the catalog set.

Raises:: NotImplementedError – When the method is not implemented
Returns:: the last catalog
Return type:: GWCatalog

get_lineage(cat_name: str, src_name: str) → DataFrame[source]¶

Returns the history of a source (src_name: str) including metadata and point estimates through a series of preceeding catalogs. Series starts at current catalog (cat_name: str) and traces a source’s history back.

Parameters:

cat_name (str) – catalog from which the lineage starts
src_name (str) – particular source

Raises:

NotImplementedError – When the method is not implemented

Returns:

history of a parituclar source including metadata and point estimates through a series of preceeding catalogs.

Return type:

pd.DataFrame

get_lineage_data(lineage: DataFrame) → DataFrame[source]¶

Returns the posterior samples of a particular source at all different epochs of obervation in the DataFrame returned by get_lineage(). The samples are concatenated into a single DataFrame.

Parameters:

lineage (pd.DataFrame) – time-dependent catalog for the evolution
by (of a particular source in a series of catalogs returned) –
get_lineage() –

Raises:

NotImplementedError – When the method is not implemented

Returns:

posterior samples of a particular source at all different epochs of obervation in the DataFrame returned by get_lineage().

Return type:

pd.DataFrame

property metadata: DataFrame¶

metadata.

Getter:: Returns the metadata of the catalog set
Type:: pd.DataFrame

class lisacattools.plugins.mbh.MbhCatalog(name: str, location: str)[source]¶

Implementation of the Mbh catalog.

property datasets¶

dataset.

Getter:: Returns the list of datasets
Type:: List

describe_source_samples(source_name: str) → DataFrame[source]¶

Statistical summary of the source posterior samples

Parameters:: source_name (str) – source name
Raises:: NotImplementedError – Not implemented
Returns:: statistics
Return type:: pd.DataFrame

get_attr_detections() → List[str][source]¶

Returns the attributes of the catalog.

Raises:: NotImplementedError – Not implemented
Returns:: the list of attributes
Return type:: List[str]

get_attr_source_samples(source_name: str) → List[str][source]¶

Returns the attributes of the source posterior samples

Parameters:: source_name (str) – source name
Raises:: NotImplementedError – Not implemented
Returns:: the attributes
Return type:: List[str]

get_dataset(name: str) → DataFrame[source]¶

Returns a dataset based on its name.

Parameters:: name (str) – name of the dataset
Returns:: the dataset
Return type:: pd.DataFrame

get_detections(attr: List[str] | str = None) → List[str] | DataFrame | Series[source]¶

Returns the GW detections.

When no argument is provided, the name of each detection is returned. When arguments are provided, each detection is returned with the attributes.

Parameters:

attr (Union[List[str], str], optional) – List of attributes or
None. (single attribute. Defaults to) –

Raises:

NotImplementedError – Not implemented

Returns:

the name of each detection or the requested attributes of each detection

Return type:

Union[List[str], pd.DataFrame, pd.Series]

get_median_source(attr: str) → DataFrame[source]¶

Returns the source corresponding to the median of the specified attribute.

Parameters:: attr (str) – attribute name
Raises:: NotImplementedError – Not implemented
Returns:: the source for which the median is computed on the attribute
Return type:: pd.DataFrame

get_source_samples(source_name: str, attr: List[str] = None) → DataFrame[source]¶

Returns the posterior samples of the source

Parameters:

source_name (str) – source name
attr (List[str]) – the list of attributes to return in the result

Raises:

NotImplementedError – [description]

Returns:

the posterior samples of the source

Return type:

pd.DataFrame

property location: str¶

Returns the location of the GW catalog.

Raises:: NotImplementedError – Not implemented
Returns:: the location of the GW catalog
Return type:: str

property name: str¶

Returns the name of the GW catalog.

Raises:: NotImplementedError – Not implemented
Returns:: name of the GW catalog
Return type:: str

3 - UCB plugin¶

class lisacattools.plugins.ucb.UcbCatalogs(path: str, accepted_pattern: str | None = '*.h5', rejected_pattern: str | None = '*chain*', *args, **kwargs)[source]¶

Implementation of the UCB catalogs.

_read_cats(cat_file: str) → DataFrame[source]¶

Reads the metadata of a given catalog and the location of the file.

Parameters:

cat_file (str) – catalog to load
pattern (str) – pattern to be used when the catalog is a tar

Returns:

pandas data frame

Return type:

pd.DataFrame

_search_directories(path: str, extra_directories: List[str]) → List[str][source]¶

Compute the list of directories on which the pattern will be applied.

Parameters:

path (str) – main path
extra_directories (List[str]) – others directories

Returns:

list of directories on which the pattern will be applied

Return type:

List[str]

_search_files(directories: List[str], accepted_pattern, rejected_pattern) → List[str][source]¶

Search files in directories according to a set of constraints : accepted and rejected patterns

Parameters:

directories (List[str]) – List of directories to scan
accepted_pattern ([type]) – pattern to get files
rejected_pattern ([type]) – pattern to reject files

Returns:

List of files

Return type:

List[str]

property count: int¶

Count the number of catalogs in the catalog set.

Getter:: Returns the number of catalogs in the catalog set
Type:: int

property files: List[str]¶

Returns the list of files matching the accepted and rejected pattern.

Getter:: Returns the number of catalogs in the catalog set
Type:: List[str]

get_catalog(idx: int) → GWCatalog[source]¶

Returns a catalog based on its position in the catalog set

Parameters:: idx (int) – position of the catalog (first idx: 0)
Raises:: NotImplementedError – When the method is not implemented
Returns:: catalog
Return type:: GWCatalog

get_catalog_by(name: str) → GWCatalog[source]¶

Returns a catalog based on its name in the catalog set

Parameters:: name (str) – name of the catalog
Raises:: NotImplementedError – When the method is not implemented
Returns:: the catalog
Return type:: GWCatalog

get_catalogs_name() → List[str][source]¶

Returns the name of each catalog included in the catalog set

Raises:: NotImplementedError – When the method is not implemented
Returns:: name of each catalog
Return type:: List[str]

get_first_catalog() → GWCatalog[source]¶

Returns the first catalog from the catalog set

Raises:: NotImplementedError – When the method is not implemented
Returns:: the fist catalog
Return type:: GWCatalog

get_last_catalog() → GWCatalog[source]¶

Returns the last catalog from the catalog set.

Raises:: NotImplementedError – When the method is not implemented
Returns:: the last catalog
Return type:: GWCatalog

get_lineage(cat_name: str, src_name: str) → DataFrame[source]¶

Returns the history of a source (src_name: str) including metadata and point estimates through a series of preceeding catalogs. Series starts at current catalog (cat_name: str) and traces a source’s history back.

Parameters:

cat_name (str) – catalog from which the lineage starts
src_name (str) – particular source

Raises:

NotImplementedError – When the method is not implemented

Returns:

history of a parituclar source including metadata and point estimates through a series of preceeding catalogs.

Return type:

pd.DataFrame

get_lineage_data(lineage: DataFrame) → DataFrame[source]¶

Returns the posterior samples of a particular source at all different epochs of obervation in the DataFrame returned by get_lineage(). The samples are concatenated into a single DataFrame.

Parameters:

lineage (pd.DataFrame) – time-dependent catalog for the evolution
by (of a particular source in a series of catalogs returned) –
get_lineage() –

Raises:

NotImplementedError – When the method is not implemented

Returns:

posterior samples of a particular source at all different epochs of obervation in the DataFrame returned by get_lineage().

Return type:

pd.DataFrame

property metadata: DataFrame¶

metadata.

Getter:: Returns the metadata of the catalog set
Type:: pd.DataFrame

class lisacattools.plugins.ucb.UcbCatalog(catalog_name: str, location: str)[source]¶

Implementation of the Ucb catalog.

_read_chain_file(source_name: str, chain_file: str) → DataFrame[source]¶

Read a source in a chain_file

Parameters:

source_name (str) – Name of the source to extract from the
chain_file (str) –
chain_file – file to load

Returns:

[description]

Return type:

pd.DataFrame

property datasets¶

dataset.

Getter:: Returns the list of datasets
Type:: List

describe_source_samples(source_name: str) → DataFrame[source]¶

Statistical summary of the source posterior samples

Parameters:: source_name (str) – source name
Raises:: NotImplementedError – Not implemented
Returns:: statistics
Return type:: pd.DataFrame

get_attr_detections() → List[str][source]¶

Returns the attributes of the catalog.

Raises:: NotImplementedError – Not implemented
Returns:: the list of attributes
Return type:: List[str]

get_attr_source_samples(source_name: str) → List[str][source]¶

Returns the attributes of the source posterior samples

Parameters:: source_name (str) – source name
Raises:: NotImplementedError – Not implemented
Returns:: the attributes
Return type:: List[str]

get_dataset(name: str) → DataFrame[source]¶

Returns a dataset based on its name.

Parameters:: name (str) – name of the dataset
Returns:: the dataset
Return type:: pd.DataFrame

get_detections(attr: List[str] | str = None) → List[str] | DataFrame | Series[source]¶

Returns the GW detections.

When no argument is provided, the name of each detection is returned. When arguments are provided, each detection is returned with the attributes.

Parameters:

attr (Union[List[str], str], optional) – List of attributes or
None. (single attribute. Defaults to) –

Raises:

NotImplementedError – Not implemented

Returns:

the name of each detection or the requested attributes of each detection

Return type:

Union[List[str], pd.DataFrame, pd.Series]

get_median_source(attr: str) → DataFrame[source]¶

Returns the source corresponding to the median of the specified attribute.

Parameters:: attr (str) – attribute name
Raises:: NotImplementedError – Not implemented
Returns:: the source for which the median is computed on the attribute
Return type:: pd.DataFrame

get_source_samples(source_name: str, attr: List[str] = None) → DataFrame[source]¶

Returns the posterior samples of the source

Parameters:

source_name (str) – source name
attr (List[str]) – the list of attributes to return in the result

Raises:

NotImplementedError – [description]

Returns:

the posterior samples of the source

Return type:

pd.DataFrame

property location: str¶

Returns the location of the GW catalog.

Raises:: NotImplementedError – Not implemented
Returns:: the location of the GW catalog
Return type:: str

property name: str¶

Returns the name of the GW catalog.

Raises:: NotImplementedError – Not implemented
Returns:: name of the GW catalog
Return type:: str