wsprpool 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
wsprpool/__init__.py ADDED
@@ -0,0 +1,15 @@
1
+ """Decode WSPR by adding the soft decisions of several receivers.
2
+
3
+ ::
4
+
5
+ from wsprpool import decode_slot
6
+ slot = decode_slot({"rx1": window1, "rx2": window2})
7
+ for spot in slot.combined:
8
+ print(spot.message, spot.snr)
9
+ """
10
+
11
+ from ._decode import Slot, Spot, decode_slot
12
+ from ._version import __version__
13
+ from ._wspr import Message, pack, symbols, unpack
14
+
15
+ __all__ = ["__version__", "Message", "Slot", "Spot", "decode_slot", "pack", "symbols", "unpack"]
wsprpool/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from ._cli import main
4
+
5
+ sys.exit(main())
wsprpool/_cli.py ADDED
@@ -0,0 +1,241 @@
1
+ """Command line: sim, record and decode."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import csv
7
+ import os
8
+ import sys
9
+ import zipfile
10
+ from datetime import datetime, timezone
11
+ from pathlib import Path
12
+ from urllib.error import URLError
13
+
14
+ import numpy as np
15
+
16
+ from ._version import __version__
17
+ from ._decode import Slot, Spot, decode_slot
18
+ from ._kiwi import Receiver, record, status, unusable
19
+ from ._session import load, save, slots
20
+ from ._sim import decode_rate, threshold
21
+ from ._spots import Row, confirm, fetch
22
+ from ._wspr import callhash, resolve
23
+
24
+
25
+ def _floats(text: str) -> list[float]:
26
+ lo, _, hi = text.partition(":")
27
+ return [float(lo)] if not hi else list(np.arange(float(lo), float(hi) + 1e-9, 1.0))
28
+
29
+
30
+ def cmd_sim(a: argparse.Namespace) -> int:
31
+ ns = [int(n) for n in a.receivers.split(",")]
32
+ snrs = _floats(a.snr)
33
+ rng = np.random.default_rng(a.seed)
34
+ print(f"decode rate over {a.trials} slots per cell, doppler {a.doppler} Hz")
35
+ print("snr dB " + "".join(f"{f'N={n}':>8}" for n in ns))
36
+ rates: dict[int, list[float]] = {n: [] for n in ns}
37
+ for s in snrs:
38
+ for n in ns:
39
+ rates[n].append(decode_rate(n, s, a.trials, a.doppler, rng))
40
+ print(f"{s:6.1f} " + "".join(f"{rates[n][-1]:8.2f}" for n in ns), flush=True)
41
+ print()
42
+ print("50% threshold and gain over the first column (ideal is 10 log10 N)")
43
+ base = threshold(snrs, rates[ns[0]])
44
+ for n in ns:
45
+ t = threshold(snrs, rates[n])
46
+ if t is None:
47
+ print(f" N={n:<3} threshold outside the SNR range")
48
+ continue
49
+ gain = f"gain {base - t:4.1f} dB, ideal {10 * np.log10(n / ns[0]):4.1f}" if base else ""
50
+ print(f" N={n:<3} {t:6.1f} dB {gain}")
51
+ return 0
52
+
53
+
54
+ def cmd_record(a: argparse.Namespace) -> int:
55
+ tool = a.kiwirecorder or os.environ.get("WSPRPOOL_KIWIRECORDER")
56
+ if not tool or not Path(tool).is_file():
57
+ print("need the path to kiwirecorder.py: pass --kiwirecorder or set "
58
+ "WSPRPOOL_KIWIRECORDER (see the README)", file=sys.stderr)
59
+ return 2
60
+ ok = []
61
+ for text in a.receivers:
62
+ rx = Receiver.parse(text)
63
+ try:
64
+ why = unusable(status(rx))
65
+ except (URLError, OSError, ValueError) as e:
66
+ why = f"status check failed: {e}"
67
+ if why:
68
+ print(f"skipping {rx.host}:{rx.port}: {why}", file=sys.stderr)
69
+ else:
70
+ ok.append(rx)
71
+ if not ok:
72
+ print("no usable receivers", file=sys.stderr)
73
+ return 1
74
+ work = a.output.with_name(a.output.stem + "-wav")
75
+ print(f"recording {len(ok)} receiver(s) at {a.freq} kHz for {a.minutes} min, "
76
+ f"starting at the next even minute")
77
+ files = record(ok, a.freq, a.minutes, work, Path(tool))
78
+ if not files:
79
+ print("every receiver failed to record", file=sys.stderr)
80
+ return 1
81
+ save(a.output, a.freq, files)
82
+ print(f"wrote {a.output} ({len(files)} receivers); the raw wavs are in {work}")
83
+ return 0
84
+
85
+
86
+ HEADER = (f"{'UTC':<16} {'MHz':>9} {'SNR':>5} {'dt':>5} {'drift':>5} {'metric':>6} "
87
+ f"{'message':<20} {'found by':<14} receivers alone / wspr.live reporters")
88
+
89
+
90
+ def _row(when: float, freq_hz: float, spot: Spot, alone: list[str], tag: str,
91
+ others: set[str] | None) -> str:
92
+ t = datetime.fromtimestamp(when, timezone.utc).strftime("%Y-%m-%d %H:%M")
93
+ heard = ",".join(alone) if alone else "-"
94
+ check = "" if others is None else f" / {len(others)}"
95
+ return (f"{t} {(freq_hz + spot.freq) / 1e6:9.6f} {max(spot.snr.values()):5.1f} "
96
+ f"{spot.dt:5.2f} {spot.drift:5.1f} {spot.metric:6.1f} {str(spot.message):<20} "
97
+ f"{tag:<14} {heard}{check}")
98
+
99
+
100
+ def _tag(receivers: int, alone: list[str], in_comb: bool) -> str:
101
+ if receivers == 1:
102
+ return "alone"
103
+ if in_comb:
104
+ return "both" if alone else "combined only"
105
+ return "alone only"
106
+
107
+
108
+ def _resolve_hashes(results: list[tuple[float, Slot]]) -> None:
109
+ """Name type 3 calls from any type 1 or 2 message heard in the session."""
110
+ every = [s for _, res in results for s in res.combined + sum(res.alone.values(), [])]
111
+ calls = {callhash(s.message.call): s.message.call for s in every if s.message.kind != 3}
112
+ for s in every:
113
+ s.message = resolve(s.message, calls)
114
+
115
+
116
+ def _write_csv(path: Path, rows: list[tuple[float, Spot, list[str], str, set[str] | None]],
117
+ freq_hz: float) -> None:
118
+ with open(path, "w", newline="", encoding="utf-8") as f:
119
+ w = csv.writer(f)
120
+ w.writerow(["utc", "mhz", "snr", "dt", "drift", "metric", "call", "grid", "power",
121
+ "found_by", "receivers_alone", "wspr_live_reporters"])
122
+ for minute, spot, alone, tag, others in rows:
123
+ m = spot.message
124
+ w.writerow([
125
+ datetime.fromtimestamp(minute, timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
126
+ f"{(freq_hz + spot.freq) / 1e6:.6f}", f"{max(spot.snr.values()):.1f}",
127
+ f"{spot.dt:.2f}", f"{spot.drift:.1f}", f"{spot.metric:.1f}",
128
+ m.call or f"<{m.callhash}>", m.grid, m.power, tag, " ".join(alone),
129
+ "" if others is None else len(others),
130
+ ])
131
+
132
+
133
+ def cmd_decode(a: argparse.Namespace) -> int:
134
+ if a.csv and not a.csv.resolve().parent.is_dir():
135
+ raise ValueError(f"can't write {a.csv}: {a.csv.resolve().parent} is not a directory")
136
+ freq_khz, streams = load(a.file)
137
+ freq_hz = freq_khz * 1000
138
+ print(f"{a.file}: {len(streams)} receivers at {freq_khz:g} kHz")
139
+
140
+ results = []
141
+ for minute, windows in slots(streams):
142
+ res = decode_slot(windows)
143
+ print(f"{datetime.fromtimestamp(minute, timezone.utc):%H:%M} "
144
+ + " ".join(f"{n}={len(s)}" for n, s in res.alone.items())
145
+ + f" combined={len(res.combined)}", file=sys.stderr, flush=True)
146
+ results.append((minute, res))
147
+ _resolve_hashes(results)
148
+
149
+ # (slot, message) -> best spot, receivers that decoded it alone, in the combination,
150
+ # and how many receivers covered that slot
151
+ found: dict[tuple[float, str], tuple[Spot, list[str], bool, int]] = {}
152
+ for minute, res in results:
153
+ live = len(res.alone)
154
+ best: dict[str, Spot] = {}
155
+ for spot in [s for spots in res.alone.values() for s in spots] + res.combined:
156
+ key = str(spot.message)
157
+ if key not in best or best[key].metric < spot.metric:
158
+ best[key] = spot
159
+ comb = {str(s.message) for s in res.combined} if live > 1 else set()
160
+ for key, spot in best.items():
161
+ alone = [n for n, spots in res.alone.items() if key in {str(s.message) for s in spots}]
162
+ found[(minute, key)] = (spot, alone, key in comb, live)
163
+
164
+ seen: dict[float, list[Row]] | None = None
165
+ if a.check:
166
+ try:
167
+ seen = fetch([m for m, _ in found], [s.message for s, _, _, _ in found.values()],
168
+ freq_hz)
169
+ except (URLError, OSError, ValueError) as e:
170
+ print(f"wspr.live check failed: {e}", file=sys.stderr)
171
+
172
+ print()
173
+ print(HEADER)
174
+ combined = combined_only = confirmed = 0
175
+ table = []
176
+ for (minute, _), (spot, alone, in_comb, live) in sorted(found.items()):
177
+ tag = _tag(live, alone, in_comb)
178
+ others = None
179
+ if seen is not None:
180
+ spot.message, others = confirm(spot.message, seen.get(minute, []))
181
+ combined += in_comb
182
+ if tag == "combined only":
183
+ combined_only += 1
184
+ confirmed += bool(others)
185
+ print(_row(minute, freq_hz, spot, alone, tag, others))
186
+ table.append((minute, spot, alone, tag, others))
187
+ if a.csv:
188
+ _write_csv(a.csv, table, freq_hz)
189
+
190
+ print()
191
+ for st in streams:
192
+ n = sum(st.label in alone for _, alone, _, _ in found.values())
193
+ print(f"{st.label:<32} {n:5d} alone")
194
+ print(f"{'any receiver alone':<32} {sum(bool(al) for _, al, _, _ in found.values()):5d}")
195
+ if len(streams) > 1:
196
+ print(f"{'combined':<32} {combined:5d}")
197
+ line = f"{'combined only':<32} {combined_only:5d}"
198
+ if seen is not None:
199
+ line += f" ({confirmed} also reported to wspr.live by other stations)"
200
+ print(line)
201
+ return 0
202
+
203
+
204
+ def main(argv: list[str] | None = None) -> int:
205
+ p = argparse.ArgumentParser(prog="wsprpool", description="Decode WSPR by pooling the soft "
206
+ "decisions of several KiwiSDRs.")
207
+ p.add_argument("--version", action="version", version=f"wsprpool {__version__}")
208
+ sub = p.add_subparsers(dest="cmd", required=True)
209
+
210
+ s = sub.add_parser("sim", help="measure combining gain on synthetic signals")
211
+ s.add_argument("--receivers", default="1,2,4,8", help="comma-separated receiver counts")
212
+ s.add_argument("--snr", default="-36:-26", help="SNR or LO:HI range in dB (1 dB steps)")
213
+ s.add_argument("--trials", type=int, default=20)
214
+ s.add_argument("--doppler", type=float, default=0.0,
215
+ help="Rayleigh fading spread in Hz, independent per receiver (0 = none)")
216
+ s.add_argument("--seed", type=int, default=1)
217
+ s.set_defaults(fn=cmd_sim)
218
+
219
+ r = sub.add_parser("record", help="record several KiwiSDRs at once")
220
+ r.add_argument("receivers", nargs="+", metavar="HOST[:PORT]")
221
+ r.add_argument("-o", "--output", type=Path, required=True, help="session .londopy file")
222
+ r.add_argument("--freq", type=float, default=14097.1, help="centre in kHz (20 m WSPR)")
223
+ r.add_argument("--minutes", type=int, default=10)
224
+ r.add_argument("--kiwirecorder", help="path to kiwiclient's kiwirecorder.py")
225
+ r.set_defaults(fn=cmd_record)
226
+
227
+ d = sub.add_parser("decode", help="decode a session alone and combined")
228
+ d.add_argument("file", type=Path)
229
+ d.add_argument("--no-check", dest="check", action="store_false",
230
+ help="skip looking spots up on wspr.live")
231
+ d.add_argument("--csv", type=Path, help="also write the spots to this CSV file")
232
+ d.set_defaults(fn=cmd_decode)
233
+
234
+ a = p.parse_args(argv)
235
+ try:
236
+ return int(a.fn(a))
237
+ except (ValueError, OSError, zipfile.BadZipFile) as e:
238
+ print(f"wsprpool: {e}", file=sys.stderr)
239
+ return 1
240
+ except KeyboardInterrupt:
241
+ return 130
wsprpool/_decode.py ADDED
@@ -0,0 +1,238 @@
1
+ """Joint search and soft-combined decoding of one 2-minute WSPR slot across receivers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+
7
+ import numpy as np
8
+
9
+ from ._demod import (
10
+ FS,
11
+ SIGN,
12
+ noise_power,
13
+ peaks,
14
+ soft_bits,
15
+ spectrum,
16
+ subtract,
17
+ sync_score,
18
+ tone_sums,
19
+ )
20
+ from ._fano import fano
21
+ from ._wspr import NSYM, Message, deinterleave, symbols, unpack
22
+
23
+ # windows start this long before the even minute, so early transmitters are still caught
24
+ LEAD = 1.0
25
+ COARSE_DF = np.arange(-1.0, 1.01, 0.1)
26
+ COARSE_LAGS = np.arange(0, int(5 * FS), 16)
27
+ FINE_DF = np.arange(-0.1, 0.101, 0.025)
28
+ # total frequency change over the transmission
29
+ DRIFTS = np.arange(-4.0, 4.01, 1.0)
30
+
31
+
32
+ @dataclass
33
+ class Spot:
34
+ message: Message
35
+ freq: float
36
+ dt: float
37
+ metric: float
38
+ snr: dict[str, float] = field(default_factory=dict)
39
+ drift: float = 0.0
40
+
41
+ @property
42
+ def combined_snr(self) -> float:
43
+ return float(10 * np.log10(sum(10 ** (s / 10) for s in self.snr.values())))
44
+
45
+
46
+ @dataclass
47
+ class Slot:
48
+ alone: dict[str, list[Spot]]
49
+ combined: list[Spot]
50
+
51
+
52
+ def _scores(
53
+ xs: list[np.ndarray], sig2: list[float], fs: np.ndarray, lags: np.ndarray, drift: float = 0.0
54
+ ) -> np.ndarray:
55
+ """Sync scores with shape (receiver, frequency, lag)."""
56
+ return np.array([[sync_score(tone_sums(x, f, lags, drift), s) for f in fs]
57
+ for x, s in zip(xs, sig2)])
58
+
59
+
60
+ def _coarse(x: np.ndarray, sigma2: float, fs: np.ndarray, lags: np.ndarray) -> np.ndarray:
61
+ """Sync scores with shape (drift, frequency, lag).
62
+
63
+ Symbol powers are worked out once on the frequency grid. A drifting signal is a path
64
+ that moves across that grid symbol by symbol, so each drift is scored by reading its
65
+ path off the grid instead of mixing the samples down again.
66
+ """
67
+ p = np.array([np.abs(tone_sums(x, f, lags)) ** 2 for f in fs]) / sigma2
68
+ diff = ((p[:, 1] + p[:, 3]) - (p[:, 0] + p[:, 2])) * SIGN
69
+ k = np.arange(NSYM)
70
+ rows = np.arange(len(fs))[:, None]
71
+ out = np.empty((len(DRIFTS), len(fs), len(lags)))
72
+ for t, drift in enumerate(DRIFTS):
73
+ shift = np.round(drift * (k - (NSYM - 1) / 2) / NSYM / (fs[1] - fs[0])).astype(int)
74
+ out[t] = diff[np.clip(rows + shift, 0, len(fs) - 1), :, k].sum(axis=1)
75
+ return out / np.sqrt(4 * NSYM)
76
+
77
+
78
+ def _refine(
79
+ xs: list[np.ndarray], sig2: list[float], f: float, lag: int, drift: float
80
+ ) -> tuple[float, int, float]:
81
+ fs = f + FINE_DF
82
+ lags = np.clip(np.arange(lag - 16, lag + 17, 2), 0, COARSE_LAGS[-1])
83
+ score = _scores(xs, sig2, fs, lags, drift).sum(axis=0)
84
+ i, j = np.unravel_index(int(np.argmax(score)), score.shape)
85
+ f, lag = float(fs[i]), int(lags[j])
86
+ # the coarse grid only knows drift to the nearest hertz
87
+ drift = max((drift - 0.5, drift, drift + 0.5), key=lambda d: float(
88
+ _scores(xs, sig2, np.array([f]), np.array([lag]), d).sum()))
89
+ return f, lag, drift
90
+
91
+
92
+ def _decode(
93
+ xs: list[np.ndarray], names: list[str], f: float, lag: int, drift: float,
94
+ min_metric: float, max_cycles: int,
95
+ ) -> Spot | None:
96
+ llr = np.zeros(162)
97
+ snr = {}
98
+ for n, x in zip(names, xs):
99
+ bits, s = soft_bits(tone_sums(x, f, np.array([lag]), drift)[:, 0, :])
100
+ llr += bits
101
+ snr[n] = s
102
+ out = fano(deinterleave(llr), max_cycles=max_cycles)
103
+ if out is None or out[1] < min_metric:
104
+ return None
105
+ msg = unpack(out[0])
106
+ if msg is None:
107
+ return None
108
+ return Spot(msg, f, lag / FS - LEAD - 1.0, out[1], snr, drift)
109
+
110
+
111
+ def _distinct(points: list[tuple[float, int, float]]) -> list[tuple[float, int, float]]:
112
+ out: list[tuple[float, int, float]] = []
113
+ for f, lag, drift in points:
114
+ if all(abs(f - g) > 0.05 or abs(lag - m) > 8 or d != drift for g, m, d in out):
115
+ out.append((f, lag, drift))
116
+ return out
117
+
118
+
119
+ def _keep(spots: dict[str, Spot], spot: Spot | None) -> bool:
120
+ """Add or improve a spot; True when its message is new."""
121
+ if spot is None:
122
+ return False
123
+ key = str(spot.message)
124
+ new = key not in spots
125
+ if new or spots[key].metric < spot.metric:
126
+ spots[key] = spot
127
+ return new
128
+
129
+
130
+ def _residual(x: np.ndarray, spots: list[Spot]) -> np.ndarray:
131
+ # strongest first, so each fit sees as little of the others as possible
132
+ for s in sorted(spots, key=lambda s: -max(s.snr.values())):
133
+ x = subtract(x, symbols(s.message), s.freq, round((s.dt + LEAD + 1.0) * FS), s.drift)
134
+ return x
135
+
136
+
137
+ def decode_slot(
138
+ windows: dict[str, np.ndarray],
139
+ min_metric: float = 10.0,
140
+ max_cycles: int = 10000,
141
+ alone: bool = True,
142
+ passes: int = 2,
143
+ ) -> Slot:
144
+ """Decode one slot from each receiver alone and from all of them combined.
145
+
146
+ Each window is 375 Hz baseband starting LEAD seconds before the even minute. With
147
+ alone=False and several receivers, only the combination is decoded. After each pass,
148
+ every decoded signal is subtracted and the rest decoded again, so a weak station
149
+ beside a strong one gets its turn. Each receiver alone, and the combination, only
150
+ subtract what they decoded themselves, so neither borrows the other's results.
151
+ """
152
+ # an all-zero window is a receiver that dropped out mid-slot
153
+ live = {n: x for n, x in windows.items() if noise_power(x) > 0}
154
+ if not live:
155
+ return Slot({}, [])
156
+ first = _decode_pass(live, min_metric, max_cycles, alone)
157
+ by_rx = {n: {str(s.message): s for s in v} for n, v in first.alone.items()}
158
+ comb = {str(s.message): s for s in first.combined} if len(live) > 1 else {}
159
+
160
+ for _ in range(passes - 1):
161
+ grew = False
162
+ for n, found in by_rx.items():
163
+ if found:
164
+ res = _decode_pass(
165
+ {n: _residual(live[n], list(found.values()))}, min_metric, max_cycles, True
166
+ )
167
+ for s in res.combined:
168
+ grew |= _keep(found, s)
169
+ if comb:
170
+ rest = {n: _residual(x, list(comb.values())) for n, x in live.items()}
171
+ for s in _decode_pass(rest, min_metric, max_cycles, False).combined:
172
+ grew |= _keep(comb, s)
173
+ if not grew:
174
+ break
175
+
176
+ _drop_shadows([*by_rx.values(), comb])
177
+ alone_out = {n: _ordered(d) for n, d in by_rx.items()}
178
+ return Slot(alone_out, _ordered(comb) if len(live) > 1 else alone_out[next(iter(live))])
179
+
180
+
181
+ def _drop_shadows(tracks: list[dict[str, Spot]]) -> None:
182
+ """Remove spots sitting on a better decode of a different message, in any track.
183
+
184
+ What a subtraction leaves of a transmission can decode as a second, wrong message at
185
+ the same frequency and time. Two real stations can't share both that closely.
186
+ """
187
+ every = [s for t in tracks for s in t.values()]
188
+ for t in tracks:
189
+ for key, s in list(t.items()):
190
+ if any(o.message != s.message and o.metric > s.metric
191
+ and abs(o.freq - s.freq) <= 0.05 and abs(o.dt - s.dt) <= 8 / FS
192
+ for o in every):
193
+ del t[key]
194
+
195
+
196
+ def _ordered(d: dict[str, Spot]) -> list[Spot]:
197
+ return sorted(d.values(), key=lambda s: s.freq)
198
+
199
+
200
+ def _decode_pass(
201
+ windows: dict[str, np.ndarray], min_metric: float, max_cycles: int, alone: bool
202
+ ) -> Slot:
203
+ names = list(windows)
204
+ xs = [windows[n] for n in names]
205
+ sig2 = [noise_power(x) for x in xs]
206
+ freqs, spec = spectrum(xs[0])
207
+ for x in xs[1:]:
208
+ spec = spec + spectrum(x)[1]
209
+ # each receiver gets its own peak list too, so a strong local signal is never missed
210
+ cands = set(peaks(freqs, spec / len(xs)))
211
+ if len(xs) > 1:
212
+ for x in xs:
213
+ cands.update(peaks(*spectrum(x)))
214
+
215
+ each = alone or len(xs) == 1
216
+ found: dict[str, dict[str, Spot]] = {n: {} for n in names} if each else {}
217
+ combined: dict[str, Spot] = {}
218
+ for f0 in sorted(cands):
219
+ fs = f0 + COARSE_DF
220
+ grid = np.array([_coarse(x, s, fs, COARSE_LAGS) for x, s in zip(xs, sig2)])
221
+ own = []
222
+ for r in range(len(xs)):
223
+ t, i, j = np.unravel_index(int(np.argmax(grid[r])), grid[r].shape)
224
+ own.append(_refine([xs[r]], [sig2[r]], float(fs[i]), int(COARSE_LAGS[j]),
225
+ float(DRIFTS[t])))
226
+ for r, n in enumerate(names if each else []):
227
+ _keep(found[n], _decode([xs[r]], [n], *own[r], min_metric, max_cycles))
228
+ if len(xs) > 1:
229
+ total = grid.sum(axis=0)
230
+ t, i, j = np.unravel_index(int(np.argmax(total)), total.shape)
231
+ joint = _refine(xs, sig2, float(fs[i]), int(COARSE_LAGS[j]), float(DRIFTS[t]))
232
+ # two stations a hertz apart can each dominate a different receiver, so the
233
+ # joint peak may belong to the other one; try every receiver's peak as well
234
+ for f, lag, drift in _distinct([joint, *own]):
235
+ _keep(combined, _decode(xs, names, f, lag, drift, min_metric, max_cycles))
236
+
237
+ alone_out = {n: _ordered(d) for n, d in found.items()}
238
+ return Slot(alone_out, _ordered(combined) if len(xs) > 1 else alone_out[names[0]])