The ALMA uv coverage assessment tool
Present status (2024-12-16)
Lastest version is assess_ms.py,v 2.24 2024/05/07.
Under construction.
Software layout
assess_ms.py and run_assess_ms.py
assess_ms.py is a Python 3 module for use within CASA. Tested CASA versions are 6.5.4, 6.6.1 .
The package is available from t.b.d.
The core method is
assess_ms.assess_ms()
For application in main-stream ALMA QA, a wrapper was added to simplify the usage:
assess_ms.run_assess_ms()
For use in batch mode, another wrapper was added with fixed parameters and comprehensive error handling:
run_assess_ms.py
It lives in the same repository directory as assess_ms.py .
Dependencies
mshistotools.py - Python module developed by the team of this development study to support uv coverage assessment. Same repository location as assess_ms.py.
Latest version is mshistotools.py,v 2.10 2024/04/24
(All other modules needed by assess_ms are part of the standard CASA 6.5.4 or 6.6.1 monolithic distribution.)
Usage of run_assess_ms.py
How to run the uv coverage assessment tool ("assess_ms") for a given MOUS after pipeline calibration has completed:
Preparations to be done only once
1) Obtain the assess_ms package and install it:
under construction
2) Copy the script "run_assess_ms.py" to the directory where you keep the production version of scripts to run.
3) Edit your copy of "run_assess_ms.py" to adapt it to your working environment. What settings you have to change is described in the detailed comments in the script text!
Running "run_assess_ms.py" for a given MOUS
1) Follow the detailed description in the header of the script text
cd <directory containing the MSs to be assessed, e.g. PL "working" dir>
casa --nologger -c "execfile('run_assess_ms.py')" > casa_stdout_stderr.txt 2>&1
2) Once the call to CASA has completed, your working directory should contain one new file "casa_stdout_stderr.txt" and one new directory "assess_ms_output"
3) "casa_stdout_stderr.txt" is only for debugging purposes and should not be delivered to ALMA users!
4) the directory "assess_ms_output" contains a variety of files which are described in the following:
Example content for MOUS "uid___A001_X2d20_X3f02":
assess_ms_output/ |-- assess_ms-binbounds_and_EFs.txt |-- assess_ms-casa.log |-- assess_ms-report.txt |-- uid___A001_X2d20_X3f02.obs_and_exp.png |-- uid___A001_X2d20_X3f02_L80__ar0.5.fillfracffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5.fillfracffbin_sectors.png |-- uid___A001_X2d20_X3f02_L80__ar0.5.rmsffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_2DEF.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_2DFF.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_2Dmissvis.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ0-45.obsexpffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ0-45.rmsffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ135-180.obsexpffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ135-180.rmsffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ45-90.obsexpffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ45-90.rmsffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ90-135.obsexpffbin.png |-- uid___A001_X2d20_X3f02_L80__ar0.5_AZ90-135.rmsffbin.png `-- uid___A001_X2d20_X3f02_L80__ar0.5_FFAZInhomogen.png
DESCRIPTION of the output file content
Overview
- assess_ms-binbounds_and_EFs.txt
- text file containing execution fraction (EF) matrix (observed/expected), i.e. the separate EF for each expected baseline length and azimuthal orientation range
- assess_ms-report.txt
- text file containing the details of the assessment result
- at the end it contains a "judgement" of the uv coverage which is either "GOOD" or "SUB-OPTIMAL"
- in any case, any defects of the uv coverage are enumerated with a one-line comment per defect
- png plots
- these plots illustrate the results in the assess_ms-report.txt file
- see description further below
- assess_ms-casa.log
- this is just the complete CASA log file
The uv coverage report
Example of a report from a dataset with good uv coverage
casa [QA] ['CODE', 'OBSPROJECT_UID', 'CYCLE', 'OBSERVING_CYCLE', 'GRADE', 'GOUS_STATUS_UID', 'MOUS_STATUS_UID', 'SB_UID', 'REQUESTED_EXECUTIONS', 'ARRAY_FAMILY', 'REPRESENTATIVE_FREQUENCY_GHZ', 'MIN_ANGULAR_RESOLUTION_ARCSEC', 'MAX_ANGULAR_RESOLUTION_ARCSEC', 'MRS_ARCSEC', 'FIELD_SOURCE_NAME', 'FIELD_REF', 'FIELD_INTEGRATION_TIME_SEC'] casa [QA] ['2022.1.01562.S', 'uid://A001/X15ba/X1836', '2022.1', 'cycle09', 'B', 'uid://A001/X2d20/X83e', 'uid://A001/X2d20/X83f', 'uid://A001/X2d20/X80a', '1', 'TWELVE-M', '342.0', '0.45', '1.139', '0.4', '2008-6610', 'X1502301963', '1209.5'] casa [QA] Version: $Id: assess_ms.py,v 2.22 2024/04/25 09:49:32 dpetry Exp $ casa [QA] assess_ms(vis=['uid___A002_Xff99e1_X8275.ms.split.cal', 'uid___A002_Xff294f_X684.ms.split.cal'], freq_ghz=342.0, ar_asec_range=[0.45, 1.139], las_asec=0.4, time_s=1209.5, ar_asec_to_test=[], targetid=2008-6610, repspwid=None, condition=c, pass_thresh=0.25, az_inhomogen_limit=2.0, storagedir=./assess_ms_output, binningversion=2, expcalcversion=0, relweighting=False, useL80=True, ffplotlim=0.0, nffradbins=10, nffazbins=4, mosfields=[], plotname=uid___A001_X2d20_X83f, ) casa [QA] Expected AR range is 0.45 arcsec - 1.139 arcsec. casa [QA] Will use L80 AR of observation for computing expectations. casa [QA] Expected LAS is 0.4 arcsec. casa [QA] MS uid___A002_Xff99e1_X8275.ms.split.cal has average Tsys 169.6865 K (approx. expected Tsys at 342.0 GHz: 157.398 K) casa [QA] The (Tsys_exp/Tsys_EB)^2 value is 0.8604 . casa [QA] MS uid___A002_Xff294f_X684.ms.split.cal has average Tsys 190.561 K (approx. expected Tsys at 342.0 GHz: 157.398 K) casa [QA] The (Tsys_exp/Tsys_EB)^2 value is 0.6822 . casa [QA] This dataset contains only ALMA 12M data. casa [QA] Total time on-source over all MSs (taking into account flagging) for field 2008-6610: 1939.0 s casa [QA] Total expected observation time is 1209.5 s. casa [QA] Assuming total of 43 antennas for expectation. casa [QA] Longest baseline: 463.3276 m (found in MS uid___A002_Xff99e1_X8275.ms.split.cal) casa [QA] Shortest baseline: 11.8981 m (found in MS uid___A002_Xff99e1_X8275.ms.split.cal) casa [QA] L80 = 202 m equivalent to AR = 0.51378 arcsec. casa [QA] L05 = 32 m equivalent to MRS = 5.55422 arcsec. casa [QA] Shortest and longest expected BL: 15 m, 525 m casa [QA] FF bin boundaries for AZ 0.0-45.0 deg = [6, 58, 110, 162, 214, 266, 318, 370, 422, 474, 526] casa [QA] FF bin filling fractions for AZ 0.0-45.0 deg = [5.0507, 1.6627, 0.9631, 0.747, 1.1869, 1.1804, 1.6006, 0.9112, 3.2016, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 5.5542 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.5093 arcsec . casa [QA] FF bin boundaries for AZ 45.0-90.0 deg = [6, 58, 110, 162, 214, 266, 318, 370, 422, 474, 526] casa [QA] FF bin filling fractions for AZ 45.0-90.0 deg = [4.3087, 1.8542, 0.9858, 1.0284, 0.8306, 1.5169, 1.0305, 2.8489, 0.0, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 5.5542 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.497 arcsec . casa [QA] FF bin boundaries for AZ 90.0-135.0 deg = [6, 58, 110, 162, 214, 266, 318, 370, 422, 474, 526] casa [QA] FF bin filling fractions for AZ 90.0-135.0 deg = [4.0276, 1.551, 0.9609, 0.8844, 0.7148, 1.0898, 1.2167, 1.3338, 2.7494, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 5.5542 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.512 arcsec . casa [QA] FF bin boundaries for AZ 135.0-180.0 deg = [6, 58, 110, 162, 214, 266, 318, 370, 422, 474, 526] casa [QA] FF bin filling fractions for AZ 135.0-180.0 deg = [4.4283, 1.6962, 0.928, 0.9087, 0.9794, 1.2977, 0.8964, 0.858, 0.0, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 5.5542 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.5481 arcsec . casa [QA] FF AZ Avg [4.4538, 1.691, 0.9594, 0.8921, 0.9279, 1.2712, 1.186, 1.488, 1.4878, 1.0] casa [QA] Estimated average MRS at level 2.0 from the sensitivity plot MRS_L = 5.5542 arcsec. casa [QA] Estimated average AR at level 2.0 from the sensitivity plot AR_L = 0.5166 arcsec. casa [QA] FF Chi2 of AZ const fit [0.0261, 0.0152, 0.0017, 0.0465, 0.134, 0.0586, 0.1849, 1.0896, 3.7465, 0.0] casa [QA] Baseline orientation is not homogeneous in BL range 8 = 422 m - 474 m casa [QA] Baseline orientation is not homogeneous in 1 BL ranges. casa [QA] FF bin exec fractions for AZ 0.0-45.0 deg = [1.8806, 1.6627, 1.1289, 0.8271, 1.437, 1.1804, 1.6006, 0.9112, 3.2016, 1.0] casa [QA] FF bin exec fractions for AZ 45.0-90.0 deg = [1.6043, 1.8542, 1.1554, 1.1387, 1.0056, 1.5169, 1.0305, 2.8489, 0.0, 1.0] casa [QA] FF bin exec fractions for AZ 90.0-135.0 deg = [1.4996, 1.551, 1.1263, 0.9792, 0.8654, 1.0898, 1.2167, 1.3338, 2.7494, 1.0] casa [QA] FF bin exec fractions for AZ 135.0-180.0 deg = [1.6488, 1.6962, 1.0877, 1.0061, 1.1858, 1.2977, 0.8964, 0.858, 0.0, 1.0] casa [QA] Dataset has mostly good uv coverage with only few defects for _L80_ AR=0.513784 arcsec, LAS=0.4arcsec casa [QA] Defects found: casa [QA] Filling fraction below 0.25 in range 80.0% - 90.0% for AZ 135.0-180.0 deg : 0.0 casa [QA] Baseline orientation is not homogeneous in BL range 8 = 422 m - 474 m casa [QA] Filling fraction below 0.25 in range 80.0% - 90.0% for AZ 45.0-90.0 deg : 0.0 casa [QA] Overall result = GOOD uv coverage
Example of a report from a dataset with suboptimal uv coverage
casa [QA] ['CODE', 'OBSPROJECT_UID', 'CYCLE', 'OBSERVING_CYCLE', 'GRADE', 'GOUS_STATUS_UID', 'MOUS_STATUS_UID', 'SB_UID', 'REQUESTED_EXECUTIONS', 'ARRAY_FAMILY', 'REPRESENTATIVE_FREQUENCY_GHZ', 'MIN_ANGULAR_RESOLUTION_ARCSEC', 'MAX_ANGULAR_RESOLUTION_ARCSEC', 'MRS_ARCSEC', 'FIELD_SOURCE_NAME', 'FIELD_REF', 'FIELD_INTEGRATION_TIME_SEC'] casa [QA] ['2022.1.01686.S', 'uid://A001/X15b9/X150e', '2022.1', 'cycle09', 'B', 'uid://A001/X2d20/X3d6', 'uid://A001/X2d20/X3d7', 'uid://A001/X2d20/X3bb', '1', 'TWELVE-M', '230.5471287307776', '0.46399999999999997', '0.696', '1.74', 'HD_165999', 'X1675206863', '1451.42'] casa [QA] Version: $Id: assess_ms.py,v 2.22 2024/04/25 09:49:32 dpetry Exp $ casa [QA] assess_ms(vis=['uid___A002_X1018459_X8716.ms.split.cal'], freq_ghz=230.5471287307776, ar_asec_range=[0.46399999999999997, 0.696], las_asec=1.74, time_s=1451.42, ar_asec_to_test=[], targetid=HD_165999, repspwid=None, condition=c, pass_thresh=0.25, az_inhomogen_limit=2.0, storagedir=./assess_ms_output, binningversion=2, expcalcversion=0, relweighting=False, useL80=True, ffplotlim=0.0, nffradbins=10, nffazbins=4, mosfields=[], plotname=uid___A001_X2d20_X3d7, ) casa [QA] Expected AR range is 0.464 arcsec - 0.696 arcsec. casa [QA] Will use L80 AR of observation for computing expectations. casa [QA] Expected LAS is 1.74 arcsec. casa [QA] MS uid___A002_X1018459_X8716.ms.split.cal has average Tsys 86.8822 K (approx. expected Tsys at 230.5471287307776 GHz: 100.4614 K) casa [QA] The (Tsys_exp/Tsys_EB)^2 value is 1.337 . casa [QA] This dataset contains only ALMA 12M data. casa [QA] Total time on-source over all MSs (taking into account flagging) for field HD_165999: 1450.1 s casa [QA] Total expected observation time is 1451.4 s. casa [QA] Assuming total of 43 antennas for expectation. casa [QA] Longest baseline: 499.6806 m (found in MS uid___A002_X1018459_X8716.ms.split.cal) casa [QA] Shortest baseline: 14.9339 m (found in MS uid___A002_X1018459_X8716.ms.split.cal) casa [QA] L80 = 235 m equivalent to AR = 0.65513 arcsec. casa [QA] L05 = 34 m equivalent to MRS = 7.75462 arcsec. casa [QA] Shortest and longest expected BL: 18 m, 612 m casa [QA] FF bin boundaries for AZ 0.0-45.0 deg = [6, 67, 128, 189, 250, 311, 372, 433, 494, 555, 616] casa [QA] FF bin filling fractions for AZ 0.0-45.0 deg = [5.0052, 1.7047, 0.9491, 0.8717, 0.8995, 1.6247, 1.6477, 1.2123, 6.4714, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 7.7546 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.6367 arcsec . casa [QA] FF bin boundaries for AZ 45.0-90.0 deg = [6, 67, 128, 189, 250, 311, 372, 433, 494, 555, 616] casa [QA] FF bin filling fractions for AZ 45.0-90.0 deg = [4.3001, 1.1407, 0.4757, 0.6609, 0.3597, 0.4923, 0.4956, 0.0, 0.0, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 7.7546 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.7323 arcsec . casa [QA] FF bin boundaries for AZ 90.0-135.0 deg = [6, 67, 128, 189, 250, 311, 372, 433, 494, 555, 616] casa [QA] FF bin filling fractions for AZ 90.0-135.0 deg = [5.2402, 1.1142, 0.6135, 0.8265, 0.8003, 0.577, 0.3108, 2.4413, 0.0, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 7.7546 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.6687 arcsec . casa [QA] FF bin boundaries for AZ 135.0-180.0 deg = [6, 67, 128, 189, 250, 311, 372, 433, 494, 555, 616] casa [QA] FF bin filling fractions for AZ 135.0-180.0 deg = [4.6973, 1.9909, 1.1936, 1.0062, 1.2701, 2.4384, 1.3839, 2.9969, 0.0, 1.0] casa [QA] Estimated MRS at level 2.0 from the sensitivity plot MRS_L = 7.0528 arcsec . casa [QA] Estimated AR at level 2.0 from the sensitivity plot AR_L = 0.6453 arcsec . casa [QA] FF AZ Avg [4.8107, 1.4876, 0.808, 0.8413, 0.8324, 1.2831, 0.9595, 1.6626, 1.6178, 1.0] casa [QA] Estimated average MRS at level 2.0 from the sensitivity plot MRS_L = 7.5792 arcsec. casa [QA] Estimated average AR at level 2.0 from the sensitivity plot AR_L = 0.6707 arcsec. casa [QA] FF Chi2 of AZ const fit [0.0198, 0.2344, 0.4495, 0.0796, 0.5621, 1.4484, 1.2971, 1.7933, 11.1111, 0.0] casa [QA] Baseline orientation is not homogeneous in BL range 8 = 494 m - 555 m casa [QA] Baseline orientation is not homogeneous in 1 BL ranges. casa [QA] FF bin exec fractions for AZ 0.0-45.0 deg = [1.812, 1.7047, 1.114, 0.9664, 1.0941, 1.6247, 1.6477, 1.2123, 6.4714, 1.0] casa [QA] FF bin exec fractions for AZ 45.0-90.0 deg = [1.5567, 1.1407, 0.5583, 0.7328, 0.4375, 0.4923, 0.4956, 0.0, 0.0, 1.0] casa [QA] FF bin exec fractions for AZ 90.0-135.0 deg = [1.8971, 1.1142, 0.7201, 0.9164, 0.9735, 0.577, 0.3108, 2.4413, 0.0, 1.0] casa [QA] FF bin exec fractions for AZ 135.0-180.0 deg = [1.7005, 1.9909, 1.401, 1.1156, 1.5449, 2.4384, 1.3839, 2.9969, 0.0, 1.0] casa [QA] Dataset has sub-optimal uv coverage for _L80_ AR=0.655134 arcsec, LAS=1.74arcsec casa [QA] Defects found: casa [QA] Filling fraction below 0.25 in range 80.0% - 90.0% for AZ 90.0-135.0 deg : 0.0 casa [QA] Filling fraction below 0.25 in range 80.0% - 90.0% for AZ 135.0-180.0 deg : 0.0 casa [QA] Baseline orientation is not homogeneous in BL range 8 = 494 m - 555 m casa [QA] Filling fraction below 0.25 in range 80.0% - 90.0% for AZ 45.0-90.0 deg : 0.0 casa [QA] Filling fraction below 0.25 in range 70.0% - 80.0% for AZ 45.0-90.0 deg : 0.0 casa [QA] Overall result = SUB-OPTIMAL uv coverage
Diagnostic plots
The 1D baseline length distribution (BLD): observed, expected
The plotted expectations are for max angular resolution (AR) value (worst resolution, black), and for min ang. res. value (best resolution, green).
The expectation optimises PSF shape, i.e. represents the most "Gaussian" PSF for the given angular resolution and overall sensitivity assuming 43 antennas for the 12M array.
It also tries to satisfy the LAS requirement but is not meant for verifying the achievement of the LAS.
Note that only in this plot, a special binning is used in which the bin width grows linearly with baseline length. This was done to have sufficient statistics in the bins for the longest baselines.
The 1D Filling Fraction (FF)
The FF is based on the expectation for the AR derived from the L80 (in 10 equidistant bins of baseline length (BL) between min and max BL).
The expectation used here has the same functional form as the ones shown in the BLD plot above, but is computed specifically for the AR derived from the L80 of the observation.
NOTE: we define the FF as the ratio observed/expected weighted sum of integration count in each BL bin.
The weights take into account Tsys differences between antennas within one EB and absolute average Tsys differences between EBs. In order to mimic the execution fraction calculation, the average Tsys of each EB is limited to a maximum of 1.5 times the expected Tsys for the representative observating frequecy from the ALMA sensitivity calculator.
NOTE: this plot is produced in two versions once for all azimuthal sectors combined and once as four overlayed per-sector plots 
The 2D Filling Fraction (FF)
... based on the same parameters as the 1D FF but calculated for 4 (four) azimuthal 45 degree sectors separately.
NOTE: since the "sign", i.e., the direction of the baseline vector can be ignored, the baseline orientation is an angle between 0 deg and 180 deg only. The other half of the plot is simply a mirror copy of the first half for convenience.
The plotted FF is capped at 2.5 so the color scale can show more details in the important range between 0 and 2.
Good sensitivity (for optimal PSF) is achieved in all green and blue regions. Pink regions are overexposed.
In red regions, the sensitivity is below the acceptable limit.
The 2D Execution Fraction (EF)
The Execution Fraction, computed in the same bins as used above for the FF, is similiar to the FF but uses a modified expectation which is closer to what the real ALMA C43 configurations deliver.
The modified expectation is higher at the shortest BLs and slightly lower at intermediate BLs.
It does not correspond to the best possible PSF but it achieves the requested LAS!
The EF is meant to be a generalized version of the single-number Execution Fraction which has been used in AQUA since some time.
The 4x10 = 40 independent EF numbers shown in this plot (the other half is just a copy) are also what is given in the assess_ms output file "assess_ms-binbounds_and_EFs.txt" .
The Azimuthal Inhomogeneity plot
In each of the ten BL bins, the value of the FF should ideally be the same in each of the four azimuthal sectors. This plot shows the chi2 of a fit of a constant function to the four values of the azimuthal bins for each BL range.
These values quantify what can be seen tentatively already from the inspection of the 2D FF and EF plots.
A chi2 value > 2.0 is a sign for strongly different values in different sectors which is equivalent to having a very asymmetric beam for the corresponding BL bin.
The relative sensitivity as a function of BL (a.k.a. "flat sensitivity" or "Loomis" plot)
For each of the ten BL bins, this plot shows the ratio of the achieved image RMS and the expected RMS assuming that the overall sensitivity is achieved evenly over the total expected angular scale (baseline length) range. On this plot "smaller is better". The naively expected value is unity (1.0) in all ten bins. A useful value for the max recoverable scale and the angular resolution can be defined as the largest and smallest angular scales (smallest and largest baseline lengths) where the entries in this plot rise above 2.0, i.e. where the RMS is twice as large as expected. If the RMS does not reach this value at one or both ends, the computation falls back to using the L05 for the MRS and the center of the upper-most BL bin for the AR.
NOTE: this plot is produced five times: once for all azimuthal sectors combined and one each for the four sectors.
The Missing Visibilities plot
This plot complements the 2D FF plot by showing in which areas of 2D BL plane additional observations would be required to achieve the most Gaussian PSF.
The requirement is shown in each bin in units of "visibility seconds" similar to the 1D BLD plot.
The Mosaic Field Check plot
If the observation is a mosaic, the PSF will be assessed for all fields (pointings) combined to produce the plots described above.
In addtion, the mosaic fields will also be assessed separately by creating 1D FF plots for each of them and overlaying them into one plot colorizing by field.
The expectation for ideal PSF will also be shown (in black).
Any mosaic fields which have a uv coverage which deviates significantly from the others will be immediately obvious.
Usually, the agreement among the fields is very good. If that is the case, all other diagnostics can be interpreted as if the observation had only a single field.
Usage of assess_ms.run_assess_ms()
(version assess_ms.py,v 2.22 2024/04/25 09:49:32 dpetry)
assess_ms and mshistotools have been under development since 2020. The method has acquired a large range of functionalities,
however, the recommended usage only needs some of them and can leave all other settings at their default.
The main user interface for standard usage is the function run_assess_ms():
run_assess_ms
Run the assess_ms tool on the given list (vis) of MSs with standard ALMA QA settings.
vis - the list of MSs to assess together as one dataset
outputdir - the directory where to write the output files
use_actual_parameters - if True, determine AR, LAS, representative freq, and on-source time
from the MS(s) themselves.
default: False - take the expected values from the file given by 'reference'
reference - the csv file containing the SB parameters for the ALMA Cycle in question
(provided by the ALMA Scheduling subsystem)
If the given file is not found in the given path, it is searched for in
the directory where the mshistotools module resides.
The expected format of the reference file is a csv file with the column names defined in row 0.
The following columns MUST be present under these exact names. The order can be arbitrary.
Other columns can optionally be present and are ignored.
['SB_UID', 'MOUS_STATUS_UID', 'REQUESTED_EXECUTIONS', 'REPRESENTATIVE_FREQUENCY_GHZ', 'MIN_ANGULAR_RESOLUTION_ARCSEC',
'MAX_ANGULAR_RESOLUTION_ARCSEC', 'MRS_ARCSEC', 'FIELD_SOURCE_NAME', 'FIELD_INTEGRATION_TIME_SEC']
pass_thresh, az_inhomogen_limit - the parameters controlling the QA decision, see help of assess_ms()
defaults: 0.25, 2.0
useL80 - for the case use_actual_parameters==False, this parameter is handed on to assess_ms(), see help of assess_ms()
default: True
mosfields - list of values describing which fields to assess in case the observation is a mosaic, see help of assess_ms()
default: [] - assess all fields
per_eb - if True, set the number of expected executions to the number of input MSs (per SB)
default: False - take the number of expected executions from the reference file
NOTE: only has an effect in the case that use_actual_parameters==False
Returns the return value of assess_ms().
Example:
sys.path.append('./AIV/science/ArrayConfiguration/beamWG')
import assess_ms as ams
ams.run_assess_ms(vis=['uid___A002_Xff99e1_X8275.ms', 'uid___A002_Xff294f_X684.ms'])
This will run for a few minutes and produce the directory "./assess_ms_output" containing the following diagnostic plots:
a) "1D" plots of values as a function of baseline length for all baselines
uid___A001_X2d20_X83f.obs_and_exp.png uid___A001_X2d20_X83f_L80__ar0.513784.fillfracffbin.png uid___A001_X2d20_X83f_L80__ar0.513784.fillfracffbin_sectors.png uid___A001_X2d20_X83f_L80__ar0.513784.rmsffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_FFAZInhomogen.png
b) "1D" plots of values as a function of baseline length for baselines in one of 4 azimuthal 45 degree sectors (i.e. sectors of baseline orientation)
uid___A001_X2d20_X83f_L80__ar0.513784_AZ0-45.obsexpffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_AZ0-45.rmsffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_AZ135-180.obsexpffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_AZ135-180.rmsffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_AZ45-90.obsexpffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_AZ45-90.rmsffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_AZ90-135.obsexpffbin.png uid___A001_X2d20_X83f_L80__ar0.513784_AZ90-135.rmsffbin.png
c) "2D" plots of values as function of the uv plane
uid___A001_X2d20_X83f_L80__ar0.513784_2DEF.png uid___A001_X2d20_X83f_L80__ar0.513784_2DFF.png uid___A001_X2d20_X83f_L80__ar0.513784_2Dmissvis.png
Furthermore, the output directory will contain other files which can be used for advanced features of the software,
e.g. to produce further plots without having to re-read the input MSs. These are mostly ".pkl" files, i.e. Python pickle files of histogram objects.
Obtaining the "uv coverage report"
Running assess_ms produces diagnostic messages which are printed to the CASA log and partially also to the terminal.
Most messages are for advanced users and will be described in the assess_ms manual in preparation.
The important log entries for main-stream users are tagged in the CASA log file with the string "::qa::casa".
By filtering for ("grepping") lines containing this string from the CASA log file and cutting away the leading date strings etc., a "uv coverage report" text file can be obtained
following this pattern:
grep "::qa::casa" <casa-logfile-name> | cut -d ":" -f 7- > assess_ms-report.txt
The parameters of the underlying "assess_ms" function
(for advanced users)
assess_ms
compare the BL length histo of a given observation with
the expectation from the PI parameters
return True if QA2_PASS is recommended
vis - the observed MS(s) or [] (empty list) if the observed histograms are to be taken from storagedir
(if a list of MSs is entered, they are combined)
Examples: [] - take the observed histograms from the files histo_*.pkl
in the directory provided by parameter storagedir
['uid___A002_Xe64b7b_X2ac81.ms.split.cal','uid___A002_Xe64b7b_X2ad02.ms.split.cal']
- extract the observed histogram from the combination of the two given MSs
using targetid and repspwid for field and SPW selection.
freq_ghz - the frequency at which the PI parameters are given (GHz)
If set to None, the central freq of the repspwid will be used.
And if repspwid is also None, the central freq of the first science SPW is used.
ar_asec_range - the angular resolution range (arcsec)
a list of two values: min and max of the expectation range
(Negative values are replaced by the angular scale corresponding to the L80
minus 20% for the min AR and +20% for the max AR).
las_asec - the largest angular scale (arcsec)
(A negative value is replaced by the angular scale corresponding to the L05.)
time_s - the estimated necessary exposure time (s)
(A negative value is replaced by the actual time on-source as derived for the
targetid taking into account flagging.)
ar_asec_to_test - the angular resolution(s) (arcsec)
the list of the angular resolutions to test in the QA assessment
default: [] - behaviour depends on value of parameter "useL80":
- if useL80==False:
determine best AR from a fit to the observation over five values covering
the range given by ar_asec_range
- if useL80==True: use L80 value of AR determined from observation
targetid - the representative target field id or field NAME.
Use the NAME in particular for mosaics to capture all mosaic pointings.
(only needed if vis != [], i.e. MSs are to be read)
default: the first science target will be used
repspwid - the representative SPW id
(only needed if vis != [], i.e. MSs are to be read)
default: the SPW containing the rep. freq, i.e. freq_ghz, will be used
condition - the condition for the calculation of the overall QA assessment
options:
'c' - determine filling fraction in nffradbins bins, filling fraction > pass_tresh in all bins,
>= 1 in uppermost 10% of the bins, average filling fraction > 0.9
2D inhomogeneity < az_inhomogen_limit in all radial bins.
default: 'c'
pass_thresh - the passing threshold used in the condition given by parameter "condition".
(This threshold is marked in the ten-bin filling fraction plots with a red line.)
default: 0.25
az_inhomogen_limit - the maximum accepted chi2 of a constant fit to the azimuthal bins of one radial bin
in the 2D FF. (This threshold is marked in the inhomogeneity plot with a red line.)
Has no effect if the number of azimuthal bins is < 2.
default: 2.0
storagedir - the directory into which to store all plots and histograms
The plots are stored as png files. The histograms are stored via the msh.save() method.
default: '.' (current working dir)
binningversion - the version of the "special" binning to be used for the result histograms: 1 or 2
default: 2
expcalcversion - choose between different options to calculate the expected base line distribution
0: ana_fill=True, rr=True
1: ana_fill=False, rr=True
2: ana_fill=True, rr=False
3: ana_fill=False, rr=False
10: use filldish.from_ex_1d for the 1D histos, rr=False
11: use filldish.from_ex_1d for the 1D histos, rr=True
default: 0
relweighting - True: apply only relative weighting when calculating the observed BLDs rather than absolute
False: apply relative weighting multiplied by the ratio (OT Tsys (for the given reference freq)/EB Tsys) squared
(capped at 1.5)
=> filling fractions are equivalent to ALMA Execution Fractions
default: True - apply only relative weighting
useL80 - if True: determine the L80 from the observation and the equivalent AR
and append it to the list of ARs to be evaluated for the QA2 decision
(see also parameter "ar_asec_to_test")
default: False
ffplotlim - the upper end of the filling fraction scale to plot in the ten bin plots
default: 0. - adapt to the actual values of the filling fractions
nffradbins - the number of equidistant radial (i.e. baseline length) bins in which the filling fractions
are calculated; number must be even.
default: 10 - i.e. use bins which have a width which is 10% of the total BL range
nffazbins - the number of equidistant azimuthal (i.e. baseline orientation) bins in which the filling
fractions are calculated; number must be 1 or an even number
NOTE: this is the number of bins over the range of 180 degrees!
default: 1 - i.e. don't distinguish different baseline orientations
mosfields - List of the mosaic fields to use in case the observation is a mosaic
NOTE: values other than the default are only supported for homogeneous datasets, i.e. using only one array
with one and the same mosaic setup for each EB.
NOTE: does not affect the "mosfieldcheck" plot, which is always done for all mosaic fields
default: [] - use all fields
Examples: [0] - use only the first field (counted from the lowest field ID in the mosaic)
[0,3] - use the first and the fourth field (if there is no fourth, use the last)
[0,'last'] - use the first and the last field
[0,'middle'] - use the first and the (n/2)-th field where n == number of mosaic fields
plotname - (optional) string to use in the title of the produced plots
default: '' - derive the label from the vis parameter
Example:
assess_ms(['uid___A002_Xe27761_X5551.ms.split.cal'], ar_asec_range=[0.24,0.36], las_asec=5.,
time_s=112., freq_ghz=336., ar_asec_to_test=[0.24,0.31,0.36], storagedir='SPT0109-47results')