Documentation updates

Open
#1,743 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 3 days

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
python

Research direction

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.

Written by the indexing model from the issue text.

Description

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).

Dominant language
Python
Stars
103
Forks
40
Avg merge
4d 11h
Merged PRs (30d)
13

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from RadioAstronomySoftwareGroup/pyuvdata

All issues in RadioAstronomySoftwareGroup/pyuvdata

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.