Documentation updates

オープン
#1,743 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 3 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
35/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
活発
技術スタック
python

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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

主要言語
Python
スター
103
フォーク
40
平均マージ
4日 11時間
マージ済み PR(30日)
13

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

RadioAstronomySoftwareGroup/pyuvdata のほかの issue

RadioAstronomySoftwareGroup/pyuvdata の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。