diff --git a/CHANGES.rst b/CHANGES.rst index 71306d7..e11bb38 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -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) ================== diff --git a/docs/alignment.rst b/docs/alignment.rst index ff80af5..c9c335a 100644 --- a/docs/alignment.rst +++ b/docs/alignment.rst @@ -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, @@ -475,15 +475,7 @@ 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 @@ -491,8 +483,14 @@ the tolerances is resolved. 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`, diff --git a/flystar/align.py b/flystar/align.py index 80c2413..1411524 100644 --- a/flystar/align.py +++ b/flystar/align.py @@ -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, @@ -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 @@ -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, @@ -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 @@ -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. @@ -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 ------- @@ -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)))) @@ -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 @@ -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 ------- @@ -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): @@ -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) @@ -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))) diff --git a/flystar/match.py b/flystar/match.py index a805312..0623b32 100644 --- a/flystar/match.py +++ b/flystar/match.py @@ -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. @@ -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'): """ @@ -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 @@ -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. @@ -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. diff --git a/flystar/tests/test_match.py b/flystar/tests/test_match.py index 2976a28..c16cc15 100644 --- a/flystar/tests/test_match.py +++ b/flystar/tests/test_match.py @@ -59,10 +59,12 @@ def test_match_duplicates(): ##### # Test 3: - # Test confused case. + # Test confused case. x1[1] is 3.5x closer to x2[0] in position than x1[0] + # (0.58 vs 2.06), but 0.04 mag farther in brightness. The legacy rule wants + # the nearest in both and leaves x2[0] unmatched. ##### m2[0] = -5.9 - idx1, idx2, dr, dm = match.match(x1, y1, m1, x2, y2, m2, dr_tol=5, dm_tol=None) + idx1, idx2, dr, dm = match.match(x1, y1, m1, x2, y2, m2, dr_tol=5, dm_tol=None, matching='legacy') # Correct indices: idx1_good = [2, 4, 6, 7, 10] @@ -79,7 +81,7 @@ def test_match_duplicates(): # Reverse test 3. ##### m2[0] = -5.9 - idx2, idx1, dr, dm = match.match(x2, y2, m2, x1, y1, m1, dr_tol=5, dm_tol=None) + idx2, idx1, dr, dm = match.match(x2, y2, m2, x1, y1, m1, dr_tol=5, dm_tol=None, matching='legacy') # Correct indices: idx1_good = [2, 4, 6, 7, 10] @@ -90,7 +92,21 @@ def test_match_duplicates(): assert len(dr) == len(dm) assert len(idx1) == len(idx2) assert len(dr) == len(idx2) - + + ##### + # Test 5: + # Confused case with the default chi2 matching, both ways: the position + # offset decides, and x1[1] is matched to x2[0]. + ##### + idx1_good = [1, 2, 4, 6, 7, 10] + idx2_good = [0, 1, 2, 3, 4, 8] + + idx1, idx2, dr, dm = match.match(x1, y1, m1, x2, y2, m2, dr_tol=5, dm_tol=None) + assert sorted(zip(idx1, idx2)) == list(zip(idx1_good, idx2_good)) + + idx2, idx1, dr, dm = match.match(x2, y2, m2, x1, y1, m1, dr_tol=5, dm_tol=None) + assert sorted(zip(idx1, idx2)) == list(zip(idx1_good, idx2_good)) + return @@ -179,27 +195,34 @@ def test_generic_match(): # hundreds of pixels away. dr_tol has to straddle that gap -- the original # 1.0 matched nothing at all, so the refinement fit 3 free parameters to 0 # stars and returned a NaN transformation. - transf, st = align.generic_match(starlist1, starlist2, init_mode='triangle', - model=transforms.PolyTransform, order_dr=[[1, 4.0]], - dr_final=4.0, - xy_match=(None, None, None, None, None, None, None, None), - m_match=(None, None, None, None), sigma_match=None, - n_bright=8, verbose=True) - - assert np.isfinite(transf.px.parameters).all(), \ - f'NaN in the x transformation parameters: {transf.px.parameters}' - assert np.isfinite(transf.py.parameters).all(), \ - f'NaN in the y transformation parameters: {transf.py.parameters}' - - # The six sl2 stars that have a counterpart in sl1, and only those. - assert len(st) == 6, f'expected 6 matches, got {len(st)}' - matched_sl1 = set(np.asarray(st['ep_name'][:, 0])) - assert matched_sl1 == {'S01', 'S02', 'S04', 'S06', 'S07', 'S10'}, \ - f'matched the wrong sl1 stars: {sorted(matched_sl1)}' - - # Every matched pair lands inside the final search radius. - resid = np.hypot(st['x'][:, 0] - st['x'][:, 1], st['y'][:, 0] - st['y'][:, 1]) - assert (resid < 4.0).all(), f'matched pairs beyond dr_final: {resid}' + # S01 and S00 are 1.8 pixels apart, and both lie within dr_final of S11: + # 0.61 and 1.17 pixels from it after the final transformation. The default + # chi2 matching leaves S11 unmatched as ambiguous (chi^2 margin about 6, below + # dchi2_tol = 9). The legacy rule takes S01, nearest in position and, by + # 0.04 mag, in magnitude. + expected = {'chi2': {'S02', 'S04', 'S06', 'S07', 'S10'}, + 'legacy': {'S01', 'S02', 'S04', 'S06', 'S07', 'S10'}} + for matching, matched_expected in expected.items(): + transf, st = align.generic_match(starlist1, starlist2, init_mode='triangle', + model=transforms.PolyTransform, order_dr=[[1, 4.0]], + dr_final=4.0, + xy_match=(None, None, None, None, None, None, None, None), + m_match=(None, None, None, None), sigma_match=None, + n_bright=8, verbose=True, matching=matching) + + assert np.isfinite(transf.px.parameters).all(), \ + f'{matching}: NaN in the x transformation parameters: {transf.px.parameters}' + assert np.isfinite(transf.py.parameters).all(), \ + f'{matching}: NaN in the y transformation parameters: {transf.py.parameters}' + + # Only sl2 stars that have a counterpart in sl1. + matched_sl1 = set(np.asarray(st['ep_name'][:, 0])) + assert matched_sl1 == matched_expected, \ + f'{matching}: matched the wrong sl1 stars: {sorted(matched_sl1)}' + + # Every matched pair lands inside the final search radius. + resid = np.hypot(st['x'][:, 0] - st['x'][:, 1], st['y'][:, 0] - st['y'][:, 1]) + assert (resid < 4.0).all(), f'{matching}: matched pairs beyond dr_final: {resid}' def test_generic_match_no_matches_raises():