Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGES.rst
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,17 @@ API changes to ``MosaicSelfRef`` and ``MosaicToRef``
which took the *first* iteration's order -- bootstrapping a rising-order
schedule at the loose starting order rather than the one the fit converged
with -- and dropped every other key.
- ``matching`` now defaults to ``'chi2'`` everywhere: ``MosaicSelfRef``,
``MosaicToRef``, ``match.match``, ``match.match_name_override``,
``transform_and_match`` and ``generic_match``. The last two now take
``matching``, ``dchi2_tol`` and the chi^2 scales too. A star with several
candidates inside the tolerances takes the candidate with the lowest
:math:`\chi^2` (position, plus magnitude when ``dm_tol`` is set), if the pair
is reciprocal and wins by ``dchi2_tol``; otherwise it is left unmatched as
ambiguous. The old default, ``'legacy'``, matched such a star only if its
nearest candidate in position was also its nearest in magnitude, which in
crowded fields discarded good matches and split one star into several
reference rows. Pass ``matching='legacy'`` to reproduce earlier results.

0.1.0 (2026-08-26)
==================
Expand Down
24 changes: 11 additions & 13 deletions docs/alignment.rst
Original file line number Diff line number Diff line change
Expand Up @@ -154,9 +154,9 @@ Matching
- Default
- What it does
* - ``matching``
- ``'legacy'``
- ``'chi2'``
- How a star with several candidates inside the tolerances is resolved.
See the section above; use ``'chi2'`` in crowded fields.
See the section above.
* - ``dchi2_tol``
- ``9.0``
- ``'chi2'`` only. How much better the winner must be than the runner-up,
Expand Down Expand Up @@ -475,24 +475,22 @@ Matching
The ``matching`` keyword selects how a star with more than one candidate inside
the tolerances is resolved.

``'legacy'`` (default)
The historical rule: a multi-candidate star is matched only if its nearest
candidate in position is also its nearest in magnitude. In a crowded field
this discards good matches -- a candidate 20x closer in position loses to
one a few hundredths of a magnitude nearer -- and each discarded star then
becomes a duplicate reference row that makes the next star list ambiguous in
turn, so one split seeds the next.

``'chi2'``
``'chi2'`` (default)
Candidates are scored as ``(dr/sigma_pos)**2 + (dm/sigma_mag)**2`` and only
reciprocal best pairs winning by ``dchi2_tol`` (default 9.0, a 3-sigma
margin) are kept; below that margin the star is treated as genuinely
ambiguous and left unmatched. The scales are measured from the star lists'
own unambiguous pairs by default, so no error columns are required. See
:func:`~flystar.match.match_chi2`.

If you are aligning a crowded field and seeing single stars split into several
rows, ``matching='chi2'`` is the fix.
``'legacy'``
The historical rule: a multi-candidate star is matched only if its nearest
candidate in position is also its nearest in magnitude. In a crowded field
this discards good matches -- a candidate 20x closer in position loses to
one a few hundredths of a magnitude nearer -- and each discarded star then
becomes a duplicate reference row that makes the next star list ambiguous in
turn, so one split seeds the next. Use it to reproduce alignments made
before ``'chi2'`` became the default.

The initial guess for the first transformation comes from
``init_guess_mode='miracle'`` (:func:`~flystar.match.miracle_match_briteN`,
Expand Down
74 changes: 50 additions & 24 deletions flystar/align.py
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ def __init__(
ref_index=0,
dm_tol=None,
outlier_tol=None,
matching='legacy',
matching='chi2',
dchi2_tol=9.0,
match_sigma_pos=None,
match_sigma_mag=None,
Expand Down Expand Up @@ -197,18 +197,18 @@ def __init__(
All single values therefore means a single iteration.
matching : str, optional
How a star with more than one candidate inside the tolerances is
resolved, and how one-to-one is enforced. 'legacy' (default) keeps
the historical behavior: a multi-candidate star is matched only if
its nearest candidate in position is also its nearest in
magnitude. In a crowded field that discards good matches -- a
resolved, and how one-to-one is enforced. 'chi2' (default) scores
candidates as (dr/sigma_pos)^2 + (dm/sigma_mag)^2, with the scales
measured from the starlists themselves, and keeps reciprocal best
pairs that win by dchi2_tol. See match.match_chi2 for the details.
'legacy' keeps the historical behavior: a multi-candidate star
is matched only if its nearest candidate in position is also its
nearest in magnitude. In a crowded field that discards good matches -- a
candidate 20x closer loses to one a few hundredths of a magnitude
nearer -- and each discarded star then becomes a duplicate
reference row that makes the next starlist ambiguous in turn, so
one split seeds the next. 'chi2' scores candidates as
(dr/sigma_pos)^2 + (dm/sigma_mag)^2, with the scales measured from
the starlists themselves, and keeps reciprocal best pairs that win
by dchi2_tol. See match.match_chi2 for the details.
By default 'legacy'.
one split seeds the next.
By default 'chi2'.
dchi2_tol : float, optional
matching='chi2' only. How much better the best candidate must be
than the runner-up, in chi^2. Default 9.0, a 3-sigma margin. Below
Expand Down Expand Up @@ -2861,7 +2861,7 @@ def __init__(
# Alignment parameters
dm_tol=None,
outlier_tol=None,
matching='legacy',
matching='chi2',
dchi2_tol=9.0,
match_sigma_pos=None,
match_sigma_mag=None,
Expand Down Expand Up @@ -2959,17 +2959,18 @@ def __init__(
All single values therefore means a single iteration.
matching : str, optional
How a star with more than one candidate inside the tolerances is
resolved, and how one-to-one is enforced. 'legacy' (default) keeps
the historical behavior: a multi-candidate star is matched only if
its nearest candidate in position is also its nearest in
magnitude. In a crowded field that discards good matches -- a
resolved, and how one-to-one is enforced. 'chi2' (default) scores
candidates as (dr/sigma_pos)^2 + (dm/sigma_mag)^2, with the scales
measured from the starlists themselves, and keeps reciprocal best
pairs that win by dchi2_tol. See match.match_chi2 for the details.
'legacy' keeps the historical behavior: a multi-candidate star
is matched only if its nearest candidate in position is also its
nearest in magnitude. In a crowded field that discards good matches -- a
candidate 20x closer loses to one a few hundredths of a magnitude
nearer -- and each discarded star then becomes a duplicate
reference row that makes the next starlist ambiguous in turn, so
one split seeds the next. 'chi2' scores candidates as
(dr/sigma_pos)^2 + (dm/sigma_mag)^2, with the scales measured from
the starlists themselves, and keeps reciprocal best pairs that win
by dchi2_tol. See match.match_chi2 for the details.
one split seeds the next.
By default 'chi2'.
dchi2_tol : float, optional
matching='chi2' only. How much better the best candidate must be
than the runner-up, in chi^2. Default 9.0, a 3-sigma margin. Below
Expand Down Expand Up @@ -4411,7 +4412,8 @@ def initial_align(table1, table2, briteN=100, transformModel=transforms.PolyTran



def transform_and_match(table1, table2, transform, dr_tol=1.0, dm_tol=None, workers=1, verbose=True):
def transform_and_match(table1, table2, transform, dr_tol=1.0, dm_tol=None, workers=1, verbose=True,
matching='chi2', dchi2_tol=9.0, sigma_pos=None, sigma_mag=None):
"""
apply transformation to starlist1 and
match stars to given radius and magnitude tolerance.
Expand Down Expand Up @@ -4440,6 +4442,15 @@ def transform_and_match(table1, table2, transform, dr_tol=1.0, dm_tol=None, work
By default 1.
verbose : bool, optional
Prints on screen information on the matching, by default True.
matching : {'chi2', 'legacy'}, optional
How a star with more than one candidate inside the tolerances is
resolved. See match.match() for details. By default 'chi2'.
dchi2_tol : float, optional
matching='chi2' only. Required chi^2 margin over the runner-up,
by default 9.0.
sigma_pos, sigma_mag : float or None, optional
matching='chi2' only. Position and magnitude scales for the chi^2.
None (default) measures them from the unambiguous pairs.

Returns
-------
Expand All @@ -4461,7 +4472,9 @@ def transform_and_match(table1, table2, transform, dr_tol=1.0, dm_tol=None, work
x1t, y1t = transform.evaluate(x1, y1)

# Match starlist 1 and 2
idx1, idx2, dr, dm = match.match(x1t, y1t, m1, x2, y2, m2, dr_tol, dm_tol, workers=workers, verbose=verbose)
idx1, idx2, dr, dm = match.match(x1t, y1t, m1, x2, y2, m2, dr_tol, dm_tol, workers=workers, verbose=verbose,
matching=matching, dchi2_tol=dchi2_tol, sigma_pos=sigma_pos,
sigma_mag=sigma_mag)

if verbose:
print(( '{0} of {1} stars matched'.format(len(idx1), len(x1t))))
Expand Down Expand Up @@ -5999,7 +6012,8 @@ def generic_match(sl1, sl2, init_mode='triangle',
dr_final=1.0,
xy_match=(None, None, None, None, None, None, None, None),
m_match=(None, None, None, None), sigma_match=None,
n_bright=100, verbose=True, **kwargs):
n_bright=100, verbose=True, matching='chi2', dchi2_tol=9.0,
match_sigma_pos=None, match_sigma_mag=None, **kwargs):
"""
Finds the transformation between two starlists using the first one
as reference frame. Different matching methods can be used. If no
Expand Down Expand Up @@ -6049,6 +6063,16 @@ def generic_match(sl1, sl2, init_mode='triangle',
init_mode. Passed through ``**kwargs``.
verbose : bool, optional
Prints on screen information on the matching, by default True.
matching : {'chi2', 'legacy'}, optional
How a star with more than one candidate inside the search radius is
resolved, in every matching step. See match.match() for details.
By default 'chi2'.
dchi2_tol : float, optional
matching='chi2' only. Required chi^2 margin over the runner-up,
by default 9.0.
match_sigma_pos, match_sigma_mag : float or None, optional
matching='chi2' only. Position and magnitude scales for the chi^2.
None (default) measures them from the unambiguous pairs.

Returns
-------
Expand All @@ -6065,6 +6089,8 @@ def generic_match(sl1, sl2, init_mode='triangle',
# does -- so normalize to 2D. Without this, len(order_dr) is 2 for a flat
# pair and the refinement loop runs twice for one requested pass.
order_dr = np.atleast_2d(order_dr)
match_kwargs = dict(matching=matching, dchi2_tol=dchi2_tol,
sigma_pos=match_sigma_pos, sigma_mag=match_sigma_mag)

# Check the input StarLists and transform them into astropy Tables
if not isinstance(sl1, starlists.StarList):
Expand Down Expand Up @@ -6130,7 +6156,7 @@ def generic_match(sl1, sl2, init_mode='triangle',
# Transform and match the catalog to the reference frame
sl2_idx, sl1_idx = transform_and_match(sl2_match, sl1_match, transf,
dr_tol=order_dr[i_loop][1],
verbose=verbose)
verbose=verbose, **match_kwargs)

# Transform the catalog to the reference frame
sl2_transf_match = transform_from_object(sl2_match, transf)
Expand Down Expand Up @@ -6200,7 +6226,7 @@ def generic_match(sl1, sl2, init_mode='triangle',
transf.py._parameters = transf.py._parameters * c_corr"""

# Do the final transformation and matching using
sl2_idx, sl1_idx = transform_and_match(sl2, sl1, transf, dr_tol=dr_final, verbose=verbose)
sl2_idx, sl1_idx = transform_and_match(sl2, sl1, transf, dr_tol=dr_final, verbose=verbose, **match_kwargs)
# StarTable output
sl2_transf = transform_from_object(sl2, transf)
unames = np.array(range(len(sl1_idx)))
Expand Down
26 changes: 13 additions & 13 deletions flystar/match.py
Original file line number Diff line number Diff line change
Expand Up @@ -708,7 +708,7 @@ def match_chi2(x1, y1, m1, x2, y2, m2, i2_match, dr_tol, dm_tol,

def match_name_override(x1, y1, m1, x2, y2, m2, dr_tol, names1, names2,
name_dr_tol, name_exclude=('star',),
dm_tol=None, workers=1, verbose=True, matching='legacy',
dm_tol=None, workers=1, verbose=True, matching='chi2',
dchi2_tol=9.0, sigma_pos=None, sigma_mag=None):
"""
Pair same-name stars first, then match the rest by position.
Expand Down Expand Up @@ -775,7 +775,7 @@ def match_name_override(x1, y1, m1, x2, y2, m2, dr_tol, names1, names2,


def match(x1, y1, m1, x2, y2, m2, dr_tol, dm_tol=None, workers=1, verbose=True,
matching='legacy', dchi2_tol=9.0, sigma_pos=None, sigma_mag=None,
matching='chi2', dchi2_tol=9.0, sigma_pos=None, sigma_mag=None,
names1=None, names2=None, name_dr_tol=None, name_exclude=('star',),
name_mode='override'):
"""
Expand All @@ -784,10 +784,10 @@ def match(x1, y1, m1, x2, y2, m2, dr_tol, dm_tol=None, workers=1, verbose=True,
and magnitude system.

For two stars to be matched, they must be within a specified radius (dr_tol) and
delta-magnitude (dm_tol). For stars with more than 1 neighbor (within the tolerances),
if one is found that is the best match in both brightness and positional offsets
(closest in both), then the match is made.
Otherwise, their is a conflict and no match is returned for the star.
delta-magnitude (dm_tol). A star with more than 1 neighbor (within the tolerances)
is resolved as set by ``matching``: by default, the pair with the lowest chi^2 is
kept if each star prefers the other and it wins by dchi2_tol; otherwise the star
is ambiguous and no match is returned for it.


Parameters
Expand All @@ -806,8 +806,7 @@ def match(x1, y1, m1, x2, y2, m2, dr_tol, dm_tol=None, workers=1, verbose=True,
Magnitude in the second catalog. Must have the same shape as x2.
dr_tol : float
How close (in units of the first catalog) a match has to be to count as a match.
For stars with more than one nearest neighbor, the delta-magnitude is checked
and the closest in delta-mag is chosen.
Stars with more than one neighbor inside it are resolved as set by ``matching``.
dm_tol : float or None, optional
How close in delta-magnitude a match has to be to count as a match.
If None, then any delta-magnitude is allowed, by default None.
Expand All @@ -821,17 +820,18 @@ def match(x1, y1, m1, x2, y2, m2, dr_tol, dm_tol=None, workers=1, verbose=True,
How to resolve a star with more than one candidate, and how to enforce
one-to-one.

'legacy' (default) keeps the historical rules: a multi-candidate star
'chi2' (default) scores each candidate as (dr/sigma_pos)^2 +
(dm/sigma_mag)^2 and keeps reciprocal best pairs that win by
dchi2_tol. See match_chi2().

'legacy' keeps the historical rules: a multi-candidate star
is matched only if its nearest candidate in position is also its
nearest in magnitude, and duplicates are arbitrated afterwards by the
same both-must-agree test. In a crowded field this discards good
matches -- a candidate 20x closer loses to one a few hundredths of a
magnitude nearer in brightness -- and every discarded star then becomes
a duplicate reference entry that makes the next catalog ambiguous too.

'chi2' scores each candidate as (dr/sigma_pos)^2 + (dm/sigma_mag)^2 and
keeps reciprocal best pairs that win by dchi2_tol. See match_chi2().
By default 'legacy'.
By default 'chi2'.
dchi2_tol : float, optional
matching='chi2' only. Required chi^2 margin over the runner-up.
Default 9.0, a 3-sigma margin, by default 9.0.
Expand Down
Loading
Loading