flint.catalogue =============== .. py:module:: flint.catalogue .. autoapi-nested-parse:: Utilities around catalogues. Known reference catalogues are described by their ViZeR catalogue id, which are used to download and store the appropriately formed catalogues on disk. If the ViZeR service is down then attempts to download and form FITS catalgoues will fail. These only need to be downloaded once, provided they can be stored and retained on disk. Attributes ---------- .. autoapisummary:: flint.catalogue.KNOWN_REFERENCE_CATALOGUES flint.catalogue.PREFERRED_COLUMNS flint.catalogue.PREFERRED_DEC_COLUMN_NAMES flint.catalogue.PREFERRED_INT_COLUMN_NAMES flint.catalogue.PREFERRED_INT_ERR_COLUMN_NAMES flint.catalogue.PREFERRED_PEAK_COLUMN_NAMES flint.catalogue.PREFERRED_RA_COLUMN_NAMES Classes ------- .. autoapisummary:: flint.catalogue.Catalogue Functions --------- .. autoapisummary:: flint.catalogue._guess_catalogue_type flint.catalogue.cli flint.catalogue.download_reference_catalogues flint.catalogue.download_vizier_catalogue flint.catalogue.get_parser flint.catalogue.get_reference_catalogue flint.catalogue.guess_column_in_table flint.catalogue.list_known_reference_catalogues flint.catalogue.verify_reference_catalogues Module Contents --------------- .. py:class:: Catalogue Bases: :py:obj:`NamedTuple` A basic structure used to describe a known catalogue. .. py:attribute:: alpha_col :type: str | None :value: None Column name containing the spectral index, used to calculate the source SED. If None a default is used. .. py:attribute:: dec_col :type: str Column name containing the declination .. py:attribute:: file_name :type: str The file name of the known catalogue .. py:attribute:: flux_col :type: str Column name containing the flux density .. py:attribute:: freq :type: float Reference frequency of the catalogue, in Hertz .. py:attribute:: maj_col :type: str Column name containing the major-axis of the source gaussian component .. py:attribute:: min_col :type: str Column name containing the min-axis of the source gaussian component .. py:attribute:: name_col :type: str Column name containing the source/component name .. py:attribute:: pa_col :type: str Column name containing the pa of the source gaussian component .. py:attribute:: q_col :type: str | None :value: None Column name containing the curvature of the spectral index, used to calculate the source SED. If None a default is used. .. py:attribute:: ra_col :type: str Column name containing the right-ascension .. py:attribute:: survey :type: str Shorthand name of the sourcey catalogue .. py:attribute:: vizier_id :type: str | None :value: None The ID of the catalogue on Vizier that is used to download the catalogue .. py:function:: _guess_catalogue_type(table: astropy.table.Table | pathlib.Path, survey: str = 'askap', file_name: str = 'askap.fit', freq: float = -1) -> Catalogue This is a stub function that will be expanded in the future. It is intended to guess the appropriate source finder that constructed a component catalogue, resolving issues around the column names. This stub function will return a aegean catalogue description :param table: The table that will be inspected :type table: Union[Table, Path] :param survey: The name of the survey to use. Defaults to askap. :type survey: str, optional :param file_name: The file name that would be used for the catalogue. Defaults of askap.fits. :type file_name: str, optional :returns: Placeholder Catalogue representing Aegean catalogues :rtype: Catalogue .. py:function:: cli() -> None .. py:function:: download_reference_catalogues(reference_directory: pathlib.Path, dry_run: bool = False) -> tuple[pathlib.Path, Ellipsis] Download all of the expected reference catalogue data that flint relies on :param reference_directory: The parent directory catalgoues will be written to :type reference_directory: Path :param dry_run: If `True`, no downloading will take place. Defaults to False. :type dry_run: bool, optional :returns: Collection of paths of all the downloaded reference catalogues :rtype: Tuple[Path, ...] .. py:function:: download_vizier_catalogue(output_path: pathlib.Path, vizier_id: str, dry_run: bool = False) -> pathlib.Path Download a catalogue from the vizier catalogue service. The table will be obtained using astroquery and written out to the supplied `output_path`, from which the format is inferred. :param output_path: Where the table will be written to :type output_path: Path :param vizier_id: The catalogue ID that will be downloaded :type vizier_id: str :param dry_run: If `True`, no downloading will take place. Defaults to False. :type dry_run: bool, optional :returns: Path the file was written to :rtype: Path .. py:function:: get_parser() -> argparse.ArgumentParser .. py:function:: get_reference_catalogue(reference_directory: pathlib.Path, survey: str, verify: bool = True) -> tuple[astropy.table.Table, Catalogue] Load in a known reference catalogue If `verify` is `True` then the `Catalogue.flux_col`, if present, will have its units converted to Jy. :param reference_directory: The path to the directory where reference catalogues were downloaded to :type reference_directory: Path :param survey: The name of the survey to load. :type survey: str :param verify: If `True`, the table column names are inspected to ensure they are correct. Defaults to True. :type verify: bool, optional :raises ValueError: Raised when the requested survey is not known :returns: The loaded table and corresponding set of expected columns :rtype: Tuple[Table, Catalogue] .. py:function:: guess_column_in_table(table: astropy.table.Table, column: str, guess_column: str | None = None) -> str Attempt to deduce the appropriate column name from a set of column names in a table. A lookup of known column names for different contexts if consulted. Available modes are: #. ra #. dec #. peakflux #. intflux If `guess_column` is provided and is in the table this is returned :param table: The table with the column names to inspect :type table: Table :param column: The type of the column we are attempting to deduce. :type column: str :param guess_column: Consider whether this column exists first. Defaults to None. :type guess_column: Optional[str], optional :raises ValueError: Raised when either the RA or Dec columns could not be figured out :returns: The names of the peak flux column :rtype: str .. py:function:: list_known_reference_catalogues() -> None List the known reference catalogues that are expected/downloaded by flint .. py:function:: verify_reference_catalogues(reference_directory: pathlib.Path, load_catalogue: bool = True) -> bool Attempt to load the set of reference catalogues to ensure they are correctly formed :param reference_directory: The directory containing the reference catalogues :type reference_directory: Path :param load_catalogue: Load the catalogue as part of verification. If False only check to see if the file exists. Defaults to True. :type load_catalogue: bool, optional :returns: Indicates whether all catalogue files exist and are correctly formed :rtype: bool .. py:data:: KNOWN_REFERENCE_CATALOGUES :type: dict[str, Catalogue] .. py:data:: PREFERRED_COLUMNS .. py:data:: PREFERRED_DEC_COLUMN_NAMES :value: ['DEJ2000', 'dec'] .. py:data:: PREFERRED_INT_COLUMN_NAMES :value: ['int_flux', 'Sint'] .. py:data:: PREFERRED_INT_ERR_COLUMN_NAMES :value: ['local_rms'] .. py:data:: PREFERRED_PEAK_COLUMN_NAMES :value: ['peak_flux', 'Sp'] .. py:data:: PREFERRED_RA_COLUMN_NAMES :value: ['RAJ2000', 'ra']