Documentation updates

Aperta
#1,743 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 3 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
35/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
python

Direzione di ricerca

Start with the docs pages on polarization normalization and Measurement Set baseline conventions. The first item is a one-word fix: change the documented pol_convention option from "mean" to "avg", checking it against the accepted values in uvdata.py and uvcal.py. The second is a docs addition: note the casacore/DP3 ant2-ant1 exception and document the pyuvdata_flip_conj keyword, which ms.py reads around line 467. Done means both pages match the code, but the maintainers are still deciding on the gains convention, so leave that out.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Following a review of the docs (from Dev Null), a couple of items have been flagged as needing updates:

Polarization Normalization
“mean” should be "avg". The page says the two pol_convention options are "sum" and "mean", but UVData and UVCal accept only ["sum", "avg"] (uvdata.py:598, uvcal.py:614), and "avg" is what gets written to POLCONV / pyuvdata_polconv / MIRIAD polconv. Anyone writing files from the docs would write a value pyuvdata rejects.

Baseline conjugation
Measurement Sets aren't uniformly ant1-ant2, and pyuvdata_flip_conj isn't documented. The page says MeasurementSets use ant1-ant2. That holds for CASA's own writers (importevla, importuvfits) and for cotter/Birli. But casacore's UVW calculators (derivedmscal's MSCAL.UVWJ2000(), measures.to_uvw) and DP3 produce ant2-ant1 baselines. On pyuvdata's own day2_TDEM0003_10s_norx_1src_1spw.ms, the stored UVW is the negative of MSCAL.UVWJ2000(). pyuvdata flips any MS without a pyuvdata_flip_conj keyword, so it reads ant2-ant1 files with the wrong sign. The reader honours pyuvdata_flip_conj from any writer (ms.py:467), so external tools can declare their convention, but that keyword isn't mentioned in the docs. It would help to (a) note the casacore/DP3 exception and (b) document pyuvdata_flip_conj (and pyuvdata_polconv) as the way for non-pyuvdata writers to record these conventions.

Note on the last point, my response:
so for clarity here - the misreading was with regards to the mixed-format (which I think is still correct). The code I looked at in evaluating this was all stuff in CASA, but in doing a deeper dive I found this particular gem (inside of MSUVWGenerator.cc):
// Tony Willis supplied this crucial bit of history: the WSRT definition of
// phase is opposite to that of the VLA - the WSRT definition of the l,m
// direction cosines is that l increases toward decreasing RA, whereas the
// VLA definition is that l increases toward increasing RA. AIPS seems to
// understand this. (For a completely useless piece of trivia, the WSRT defn
// of phase is consistent with that of the Cambridge one-mile telescope as
// Wim Brouw set things up to be in agreement with the one-mile telescope ca
// 1968.)
// RR: It is not just l, v and w are flipped as well.
if(WSRTConvention)
antUVW_p = -antUVW_p;So I probably should have clarified that CASA needs ant1-ant2 — at least, it’s clear that several routines (i..e, gaincal, polcal) depend on it being in that order, and I don’t see any that require/prefer the ant2-ant1 convention. The MSCAL.UVWJ2000()  routine does exist and is flipped, but it looks like the only routine in the whole package that’s like that, and I’m wondering if thats a bug rather than a feature. The docs on MSv2 are definitely confusing/conflicting (which I think is part of why we’ve chased our own tails so lnog on this) — the idea of “publicizing” the keyword for controlling the flip behavior seems like a good one (and pyuvdata_flip_conj becoming part of a sort of de facto standard keyword for MSv2 is both amusing but also pointing to the fact the format needs something to mark the conjugation given the longstanding confusion/conflict)

Talking about this on a call, we're planning to record the pyuvdata_flip_conj keyword (possibly others?), as well as discuss at a high level the gains calibration convention (multiply vs divide).

Lingua principale
Python
Stelle
103
Fork
40
Merge medio
4g 11h
PR unite (30g)
13

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di RadioAstronomySoftwareGroup/pyuvdata

Tutte le issue di RadioAstronomySoftwareGroup/pyuvdata

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.