stilts_wrapper.matcher

class CatMatcher.matcher.StiltsMatcher(file_list, file_path, match_radius, match_values='RA DEC', output_mode='out', output_file_name='matched.csv', command_file_name='Nmatch_commands', cwd='CatMatcher_cwd', matcher='sky', multimode='group', join_mode='match', runner='parallel', progress='time', fixcols='dups', reference_file=None, suffix_list=None, iref=None, input_command=None, output_command=None, ifmt=None, ofmt=None)[source]

Bases: MatchConfigurator

This class is used build and execute the STILTS tmatchN function based on the provided matching configuration ( see MatchConfigurator).

It inherits from MatchConfigurator and automates the generation of STILTS commands used to perform multi-table astronomical catalog matching.

Note

It is important to note that the paths in the command file must be relative to the location of the script files. The folder structure is hardcoded as follows:

├── Data directory (where all the files are)
│   └── CatMatcher_cwd
│        ├── scripts
│            ├── match_commands.txt
│            └── stilts_execute.sh
│        ├── matches
│            └── match file(s)
Parameters:

  • file_list (list | str)

  • file_path (str)

  • match_radius (float)

  • match_values (str | list)

  • output_mode (str)

  • output_file_name (str)

  • command_file_name (str)

  • cwd (str)

  • matcher (Literal['sky', 'skyerr', 'exact'])

  • multimode (Literal['pairs', 'group'])

  • join_mode (Literal['default', 'match', 'nomatch', 'always'])

  • runner (Literal['parallel', 'parallel-all', 'sequential', 'classic', 'partest'])

  • progress (Literal['none', 'log', 'time', 'profile'])

  • fixcols (Literal['none', 'dups', 'all'])

  • reference_file (str | None)

  • suffix_list (list | None)

  • iref (str | None)

  • input_command (str | None)

  • output_command (str | None)

  • ifmt (Literal['colfits', 'csv', 'ecsv', 'fits', 'tst', 'votable'] | None)

  • ofmt (Literal['colfits', 'csv', 'ecsv', 'fits', 'tst', 'votable'] | None)

build_N_match(print_command=False)[source]

Builds the full STILTS tmatchn command for N-way matching of input catalogs and writes it to a shell-executable file.

This method uses the match attributes described in the MatchConfigurator dataclass, like input files, formats, suffixes, match values, to construct a command file for the STILTS software, which can be run via the terminal. It handles all combinations of match column and format configurations that the author could think of until now :P (e.g., one for all files or distinct per file).

The command is written to command_file_name inside the scripts/ directory and made executable. Note that, depending on the individual user system settings, the action of making the file executable might require root privileges.

Parameters:

print_command (bool) – If True, prints the final command to stdout for user inspection.

Returns:

  • Writes the constructed command string to a .txt file (and prints it if required).

  • Makes the command file executable via chmod.

Return type:

No direct output, but

perform_Nmatch(return_output=True, log_file=True)[source]

Executes the STILTS match command constructed by build_N_match.

This method calls build_N_match() to prepare the matching script, then executes it using a shell call. Optionally returns output logs and is intended to support future logging of match parameters and statistics.

Parameters:

  • return_output (bool) – If True, prints shell execution output and error to stdout.

  • log_file (bool) – Placeholder for future implementation of a match log generation function.

Returns:

  • Writes the constructed command string to a .txt file (and prints it if required).

  • Executes a shell script to perform the match.

  • (Planned) Generates a log file with match parameters and statistics.

Return type:

No direct output, but