All About Antennas

Antenna index, positions, orientations, and antenna pairing. More...

Functions
pl.DataFrame	read_global_channel_mapping ()
	Generates a Polars DataFrame from map.dat in the pueo-data repository.
pl.DataFrame	read_antenna_geometry (Path qrh_dot_dat, ant_type='MI')
	Reads in antenna positions (Cartesian coordinates, meters) and attitudes (degrees) from qrh.dat in the pueo-data repository.
pl.DataFrame	get_nominal_phase_center (pl.DataFrame face_centers, str coordinates=None, ant_type='MI')
	Takes the antenna face centers and returns the (nominal) antenna phase centers
pl.DataFrame	generate_MI_antenna_pairs (pl.DataFrame antennas, int phi_sector_group_size=3)
	Pairs up neighboring antennas in the main instrument.

Variables
tuple	ALL_PUEO_ANTENNA_NAMES
	All possible AntNums.
	ANTENNA_POLARIZATION_TYPE = pl.Enum(["H", "V"])
	Enum that specifies either the horizontally or the vertically polarized channel.
	PUEO_ANTENNA_TYPE = pl.Enum(["MI", "LF"])
	Can be either the main instrument (MI) or the low frequency instrument (LF)
int	NUM_PHI_SECTORS = 24
	Number of azimuthal angle ( \(\phi\)) groups.
int	ASSUMED_PHI_SECTOR_APERTURE_WIDTH = 50
	How "wide" an antenna can see in degrees.

Detailed Description

Antenna index, positions, orientations, and antenna pairing.

Function Documentation

read_global_channel_mapping()

pl.DataFrame read_global_channel_mapping

(

)

Generates a Polars DataFrame from map.dat in the pueo-data repository.

• map.dat contains the channel mapping between the indices GlobalChan, AntNum and AntIdx for all channels
• That is, the dataframe contains both polarizations (V and H) of both instruments (MI and LF).
• GlobalChan is the index used by the pueoEvent repository to access the waveforms, see its example script.
• The relevant line is

  chan = pueo.GeomTool.Instance().getChanIndexFromRingPhiPol(
      pueo.ring.ring_t.kTopRing, 10, pueo.pol.pol_t.kVertical
  )

• chan in the line above comes from the column GlobalChan in the DataFrame.
• Sample output:

  shape: (208, 10)
  ┌────────────┬────────┬────────┬──────┬─────────┬─────────┬─────────────┬───────────┬──────┬─────────┐
  │ GlobalChan ┆ AntNum ┆ AntIdx ┆ Pol  ┆ AntType ┆ SurfNum ┆ SurfChanNum ┆ PhiSector ┆ Ring ┆ Comment │
  │ ---        ┆ ---    ┆ ---    ┆ ---  ┆ ---     ┆ ---     ┆ ---         ┆ ---       ┆ ---  ┆ ---     │
  │ u32        ┆ enum   ┆ u32    ┆ enum ┆ enum    ┆ u8      ┆ u8          ┆ u8        ┆ u8   ┆ str     │
  ╞════════════╪════════╪════════╪══════╪═════════╪═════════╪═════════════╪═══════════╪══════╪═════════╡
  │ 0          ┆ 101    ┆ 0      ┆ H    ┆ MI      ┆ 0       ┆ 0           ┆ 1         ┆ 1    ┆ null    │
  │ 1          ┆ 201    ┆ 1      ┆ H    ┆ MI      ┆ 0       ┆ 1           ┆ 1         ┆ 2    ┆ null    │
  │ 2          ┆ 301    ┆ 2      ┆ H    ┆ MI      ┆ 0       ┆ 2           ┆ 1         ┆ 3    ┆ null    │
  │ 3          ┆ 401    ┆ 3      ┆ H    ┆ MI      ┆ 0       ┆ 3           ┆ 1         ┆ 4    ┆ null    │
  │ 4          ┆ 102    ┆ 4      ┆ H    ┆ MI      ┆ 0       ┆ 4           ┆ 2         ┆ 1    ┆ null    │
  │ …          ┆ …      ┆ …      ┆ …    ┆ …       ┆ …       ┆ …           ┆ …         ┆ …    ┆ …       │
  │ 203        ┆ 609    ┆ 99     ┆ V    ┆ LF      ┆ 25      ┆ 3           ┆ 9         ┆ 6    ┆ null    │
  │ 204        ┆ 713    ┆ 100    ┆ V    ┆ LF      ┆ 25      ┆ 4           ┆ 13        ┆ 7    ┆ null    │
  │ 205        ┆ 813    ┆ 101    ┆ V    ┆ LF      ┆ 25      ┆ 5           ┆ 13        ┆ 8    ┆ null    │
  │ 206        ┆ 817    ┆ 102    ┆ V    ┆ LF      ┆ 25      ┆ 6           ┆ 17        ┆ 8    ┆ null    │
  │ 207        ┆ 821    ┆ 103    ┆ V    ┆ LF      ┆ 25      ┆ 7           ┆ 21        ┆ 8    ┆ null    │
  └────────────┴────────┴────────┴──────┴─────────┴─────────┴─────────────┴───────────┴──────┴─────────┘

Definition at line 94 of file antenna_attributes.py.

read_antenna_geometry()

pl.DataFrame read_antenna_geometry	(	Path	qrh_dot_dat,
			ant_type = 'MI' )

Reads in antenna positions (Cartesian coordinates, meters) and attitudes (degrees) from qrh.dat in the pueo-data repository.

Parameters

[in]

qrh_dot_dat

Path to qrh.dat

• Note that qrh.dat contains the face centers of all main-instrument (MI) antennas (quad-ridged horn antennas) and NOT the phase center.
• The function will error out if, although unlikely, qrh.dat contains an index that is not listed in ALL_PUEO_ANTENNA_NAMES.
• Sample output:

  shape: (96, 10)
  ┌────────┬──────┬───────────┬────────┬───────┬────────┬───────┬────────────┬──────────┬───────────┐
  │ AntNum ┆ Ring ┆ PhiSector ┆ AntIdx ┆ X[m]  ┆ Y[m]   ┆ Z[m]  ┆ Pitch[deg] ┆ Yaw[deg] ┆ Roll[deg] │
  │ ---    ┆ ---  ┆ ---       ┆ ---    ┆ ---   ┆ ---    ┆ ---   ┆ ---        ┆ ---      ┆ ---       │
  │ enum   ┆ u8   ┆ u8        ┆ u32    ┆ f64   ┆ f64    ┆ f64   ┆ f64        ┆ f64      ┆ f64       │
  ╞════════╪══════╪═══════════╪════════╪═══════╪════════╪═══════╪════════════╪══════════╪═══════════╡
  │ 101    ┆ 1    ┆ 1         ┆ 0      ┆ 1.488 ┆ 0.0    ┆ 5.114 ┆ -10.0      ┆ 0.0      ┆ 0.0       │
  │ 201    ┆ 2    ┆ 1         ┆ 1      ┆ 2.596 ┆ 0.0    ┆ 1.457 ┆ -10.0      ┆ 0.0      ┆ 0.0       │
  │ 301    ┆ 3    ┆ 1         ┆ 2      ┆ 2.596 ┆ 0.0    ┆ 0.728 ┆ -10.0      ┆ 0.0      ┆ 0.0       │
  │ 401    ┆ 4    ┆ 1         ┆ 3      ┆ 2.596 ┆ 0.0    ┆ 0.0   ┆ -10.0      ┆ 0.0      ┆ 0.0       │
  │ 102    ┆ 1    ┆ 2         ┆ 4      ┆ 1.33  ┆ 0.356  ┆ 4.476 ┆ -10.0      ┆ 15.0     ┆ 0.0       │
  │ …      ┆ …    ┆ …         ┆ …      ┆ …     ┆ …      ┆ …     ┆ …          ┆ …        ┆ …         │
  │ 423    ┆ 4    ┆ 23        ┆ 91     ┆ 2.248 ┆ -1.298 ┆ 0.0   ┆ -10.0      ┆ -30.0    ┆ 0.0       │
  │ 124    ┆ 1    ┆ 24        ┆ 92     ┆ 1.33  ┆ -0.357 ┆ 4.476 ┆ -10.0      ┆ -15.0    ┆ 0.0       │
  │ 224    ┆ 2    ┆ 24        ┆ 93     ┆ 2.507 ┆ -0.672 ┆ 1.457 ┆ -10.0      ┆ -15.0    ┆ 0.0       │
  │ 324    ┆ 3    ┆ 24        ┆ 94     ┆ 2.507 ┆ -0.672 ┆ 0.728 ┆ -10.0      ┆ -15.0    ┆ 0.0       │
  │ 424    ┆ 4    ┆ 24        ┆ 95     ┆ 2.507 ┆ -0.672 ┆ 0.0   ┆ -10.0      ┆ -15.0    ┆ 0.0       │
  └────────┴──────┴───────────┴────────┴───────┴────────┴───────┴────────────┴──────────┴───────────┘

Definition at line 160 of file antenna_attributes.py.

get_nominal_phase_center()

pl.DataFrame get_nominal_phase_center	(	pl.DataFrame	face_centers,
		str	coordinates = None,
			ant_type = 'MI' )

Takes the antenna face centers and returns the (nominal) antenna phase centers

Parameters

[in]	face_centers	The output of #read_MI_antenna_geometry
[in]	coordinates	can be "cylindrical" or default (Cartesian)

Return values

phase_centers

Same as face_centers except X[m], Y[m], and Z[m] now represent phase centers.

• Essential columns: face_centers must contain X[m] and Y[m]
• The nominal phase center is obtained by taking the face center and moving radially inward by 30 cm (cylindrical coordinates).
• If coordinates is not specified then Cartesian coordinates is used, and the output schema is

  $ AntNum     <enum>
  $ Ring         <u8>
  $ PhiSector    <u8>
  $ AntIdx      <u32>
  $ X[m]        <f64>
  $ Y[m]        <f64>
  $ Z[m]        <f64>
  $ Pitch[deg]  <f64>
  $ Yaw[deg]    <f64>
  $ Roll[deg]   <f64>

• If coordinates is cylindrical, then the ouput schema is

  $ AntNum     <enum>
  $ Ring         <u8>
  $ PhiSector    <u8>
  $ AntIdx      <u32>
  $ Z[m]        <f64>
  $ Pitch[deg]  <f64>
  $ Yaw[deg]    <f64>
  $ Roll[deg]   <f64>
  $ Rho[m]      <f64>
  $ Phi[rad]    <f64>

Definition at line 238 of file antenna_attributes.py.

generate_MI_antenna_pairs()

pl.DataFrame generate_MI_antenna_pairs	(	pl.DataFrame	antennas,
		int	phi_sector_group_size = 3 )

Pairs up neighboring antennas in the main instrument.

Parameters

[in]	antennas	Column AntIdx is required
[in]	phi_sector_group_size	(optional) Make sure \(\geq 1\)

Return values

antenna_pairs

See the sample output below.

• Parameters:
• antennas: The AntIdx column is required, all other columns are optional. See the following examples.
  1. A dataframe with placeholder integers as antenna phase center positions, or
  2. Directly from qrh.dat
• phi_sector_group_size: Actually this is (roughly) half the group size. Check out the plots in the file description to see what effect this parameter has on the number of pairs generated.

  Warning

  For non-default values, make sure phi_sector_group_size \(\geq 1\)

• Example input antennas:

  ┌────────┬──────┬───────────┬────────┬───────┬────────┬───────┬────────────┬──────────┬───────────┐
  │ AntNum ┆ Ring ┆ PhiSector ┆ AntIdx ┆ X[m]  ┆ Y[m]   ┆ Z[m]  ┆ Pitch[deg] ┆ Yaw[deg] ┆ Roll[deg] │
  │ ---    ┆ ---  ┆ ---       ┆ ---    ┆ ---   ┆ ---    ┆ ---   ┆ ---        ┆ ---      ┆ ---       │
  │ enum   ┆ u8   ┆ u8        ┆ u32    ┆ f64   ┆ f64    ┆ f64   ┆ f64        ┆ f64      ┆ f64       │
  ╞════════╪══════╪═══════════╪════════╪═══════╪════════╪═══════╪════════════╪══════════╪═══════════╡
  │ 101    ┆ 1    ┆ 1         ┆ 0      ┆ 1.488 ┆ 0.0    ┆ 5.114 ┆ -10.0      ┆ 0.0      ┆ 0.0       │
  │ 201    ┆ 2    ┆ 1         ┆ 1      ┆ 2.596 ┆ 0.0    ┆ 1.457 ┆ -10.0      ┆ 0.0      ┆ 0.0       │
  │ …      ┆ …    ┆ …         ┆ …      ┆ …     ┆ …      ┆ …     ┆ …          ┆ …        ┆ …         │
  │ 324    ┆ 3    ┆ 24        ┆ 94     ┆ 2.507 ┆ -0.672 ┆ 0.728 ┆ -10.0      ┆ -15.0    ┆ 0.0       │
  │ 424    ┆ 4    ┆ 24        ┆ 95     ┆ 2.507 ┆ -0.672 ┆ 0.0   ┆ -10.0      ┆ -15.0    ┆ 0.0       │
  └────────┴──────┴───────────┴────────┴───────┴────────┴───────┴────────────┴──────────┴───────────┘

• With default phi_sector_group_size and the example input above, the output schema looks like

  Rows: 912
  Columns: 20
  $ A1_AntNum     <enum>
  $ A1_Ring         <u8>
  $ A1_PhiSector    <u8>
  $ A1_AntIdx      <u32>
  $ A1_X[m]        <f64>
  $ A1_Y[m]        <f64>
  $ A1_Z[m]        <f64>
  $ A1_Pitch[deg]  <f64>
  $ A1_Yaw[deg]    <f64>
  $ A1_Roll[deg]   <f64>
  $ A2_AntNum     <enum>
  $ A2_Ring         <u8>
  $ A2_PhiSector    <u8>
  $ A2_AntIdx      <u32>
  $ A2_X[m]        <f64>
  $ A2_Y[m]        <f64>
  $ A2_Z[m]        <f64>
  $ A2_Pitch[deg]  <f64>
  $ A2_Yaw[deg]    <f64>
  $ A2_Roll[deg]   <f64>

Definition at line 44 of file antenna_pairs.py.

Variable Documentation

ALL_PUEO_ANTENNA_NAMES

tuple ALL_PUEO_ANTENNA_NAMES

All possible AntNums.

• Listing these as Polars Enums allows for invalid operation checks (e.g. if the user selects a non-existent antenna).
• Supposedly this is also more performant (?)
• This also allows you to "rank" the antennas based on AntNum within Polars.
  • for example, you can do

    my_dataframe.filter(pl.col("AntNum") <= "102")

    and it should filter out all other rows and leave you with antennas 101, 201, 301, 401, and 102.

Definition at line 29 of file antenna_attributes.py.

ANTENNA_POLARIZATION_TYPE

ANTENNA_POLARIZATION_TYPE = pl.Enum(["H", "V"])

Enum that specifies either the horizontally or the vertically polarized channel.

• Following the convention defined by pueoEvent, HPol is the first enumeration (H = 0, V = 1)

Definition at line 68 of file antenna_attributes.py.

NUM_PHI_SECTORS

int NUM_PHI_SECTORS = 24

Number of azimuthal angle ( \(\phi\)) groups.

• Each \(\phi\)-sector has 4 antennas currently, since there are 4 rings of antennas around the PUEO Payload.
• There are 24 \(\phi\)-sectors; each one takes up 15 degrees.

Definition at line 81 of file antenna_attributes.py.

ASSUMED_PHI_SECTOR_APERTURE_WIDTH

int ASSUMED_PHI_SECTOR_APERTURE_WIDTH = 50

How "wide" an antenna can see in degrees.

Warning

Note that if this angle is small, the masking function might produce a completely blank map if the antenna pair's fields of view do not overlap (related: antenna_pairs.generate_MI_antenna_pairs).

Todo

Determine a more realistic value using real data

Definition at line 91 of file antenna_attributes.py.