hera-strip 1.0.1

HERA strip: A tool for simulating and visualizing diffuse sky models for HERA observations.

HERA Strip

HERA Strip is an interactive visualization tool for simulating and visualizing the observable sky strip for the Hydrogen Epoch of Reionization Array (HERA) radio telescope. It creates interactive Bokeh plots showing diffuse sky models, point source catalogs, and antenna beam patterns projected onto celestial coordinates.

Features

• Diffuse Sky Models: Visualize Global Sky Models (GSM2008, GSM2016, LFSS, Haslam) at any frequency
• Point Source Catalogs: Load and display point sources from pyradiosky .skyh5 files
• Antenna Beam Overlay: Project HERA beam patterns from FITS files onto the sky map with power contours
• Observable Strip: Highlight the region of sky visible to HERA during a given time range or LST range
• Interactive Plots: Zoom, pan, and hover over sources to see coordinates and flux values
• Flexible Coordinate Systems: Display in Right Ascension (RA) or Local Sidereal Time (LST)
• Multiple Background Modes: Full GSM with hover, reference-only GSM, or white background

Installation

From PyPI

pip install hera-strip

From Source

git clone https://github.com/RRI-interferometry/hera_strip.git
cd hera_strip
pip install -e .

Dependencies

Required packages:

• numpy
• astropy
• healpy
• pygdsm
• bokeh
• matplotlib
• scipy
• pyradiosky - For .skyh5 file support (point sources and healpix maps)
• pyuvdata - For beam FITS file support

Install all dependencies:

pip install -r requirements.txt

Quick Start

Basic Usage with LST Range

# Visualize sky strip from LST 1.25h to 5.75h at HERA location
python -m herastrip --location="-30.7,21.4" --lst-range="1.25-5.75" --frequency=80 --use-lst

With Point Source Catalog

# Overlay point sources from a skyh5 catalog
python -m herastrip --location="-30.7,21.4" --lst-range="1.25-5.75" \
    --skyh5=./catalog.skyh5 --background=reference --use-lst

With Beam Overlay

# Add HERA beam pattern centered at LST 18h
python -m herastrip --location="-30.7,21.4" --lst-range="1.25-5.75" \
    --skyh5=./catalog.skyh5 --background=reference --use-lst \
    --add-beam=./beam.fits --beam-lst=18

Command Line Interface

python -m herastrip [OPTIONS]

Required Arguments

Argument	Description
--location LAT,LON	Observer location as latitude,longitude in degrees (e.g., -30.7,21.4 for HERA)

Plus one of:

Argument	Description
--lst-range START-END	LST range in hours (e.g., 1.25-5.75)
--start TIME --duration SEC	ISO time and duration in seconds

Optional Arguments

Sky Model Options

Argument	Default	Description
--frequency FREQ	76	Observing frequency in MHz
--model MODEL	gsm2008	Sky model: gsm2008, gsm2016, lfss, haslam
--skyh5 PATH	None	Path to .skyh5 file (overrides --model)
--fov DEGREES	Auto	FOV radius in degrees (auto-calculated from HERA beam if not set)

Display Options

Argument	Default	Description
--background MODE	gsm	Background mode: gsm (full with hover), reference (GSM as reference, source colorbar), none (white)
--scale SCALE	log	Color scale for point sources: log or linear
--use-lst	False	Display x-axis as LST (hours) instead of RA (degrees)
--max-sources N	1000	Maximum number of point sources to display

Beam Overlay Options

Argument	Default	Description
--add-beam PATH	None	Path to beam FITS file (pyuvdata UVBeam format)
--beam-lst HOURS	Center	LST in hours where to center the beam
--beam-vmin DB	-40	Minimum power level in dB for beam colormap
--beam-vmax DB	0	Maximum power level in dB for beam colormap

Output Options

Argument	Default	Description
--output DIR	None	Output directory for saving HTML plot

Sky Models

HERA Strip supports multiple diffuse sky models via pygdsm:

Model	Frequency Range	Description
gsm2008	10 MHz - 100 GHz	Global Sky Model 2008 (de Oliveira-Costa et al.)
gsm2016	10 MHz - 5 THz	Global Sky Model 2016 (Zheng et al.)
lfss	10 - 408 MHz	LWA1 Low Frequency Sky Survey (Dowell et al.)
haslam	10 MHz - 100 GHz	Haslam 408 MHz map with spectral scaling

Python API

Basic Usage

from astropy.coordinates import EarthLocation
from herastrip import HeraStripSimulator

# HERA location
location = EarthLocation(lat=-30.7, lon=21.4)

# Create simulator with LST range
simulator = HeraStripSimulator(
    location=location,
    frequency=80,           # MHz
    lst_range=(1.25, 5.75), # LST hours
    use_lst=True,           # Display in LST
    background_mode="gsm",  # Full GSM background
)

# Run and display
simulator.run_simulation()

With Point Sources

from herastrip import HeraStripSimulator

simulator = HeraStripSimulator(
    location=location,
    frequency=80,
    lst_range=(1.25, 5.75),
    skyh5_path="./catalog.skyh5",  # Point source catalog
    max_sources=500,               # Show top 500 brightest
    background_mode="reference",   # GSM as visual reference
    use_lst=True,
)

simulator.run_simulation(save_simulation_data=True, folder_path="./output")

With Beam Overlay

from herastrip import HeraStripSimulator

simulator = HeraStripSimulator(
    location=location,
    frequency=80,
    lst_range=(1.25, 5.75),
    skyh5_path="./catalog.skyh5",
    background_mode="reference",
    use_lst=True,
    beam_path="./NF_HERA_Vivaldi_efield_beam.fits",
    beam_lst=18.0,      # Center beam at LST 18h
    beam_vmin=-40,      # dB range for colormap
    beam_vmax=0,
)

simulator.run_simulation()

Using Individual Components

from herastrip import (
    SkyMapGenerator,
    PointSourceCatalog,
    BeamProcessor,
    Plotter,
    calculate_hera_fov_radius,
)
from astropy.coordinates import EarthLocation

# HERA location
location = EarthLocation(lat=-30.7, lon=21.4)

# Generate sky map
sky_gen = SkyMapGenerator(frequency=80, model="gsm2008")
projected_map = sky_gen.generate_projected_map(nside=1024)

# Load point sources
catalog = PointSourceCatalog("./catalog.skyh5", frequency=80)
sources = catalog.get_sources(max_sources=500)

# Load beam
beam = BeamProcessor("./beam.fits", frequency_mhz=80)
beam_data = beam.transform_to_radec(location, lst_hours=18.0)

# Calculate FOV for a given frequency
fov_radius = calculate_hera_fov_radius(frequency_mhz=80)
print(f"FOV radius at 80 MHz: {fov_radius:.1f}°")

HERA Beam Physics

The FOV radius is automatically calculated using HERA's dish parameters:

FWHM = k × λ / D

Where:
  k = 1.17 (beam coefficient, calibrated to HERA measurements)
  λ = c / frequency (wavelength)
  D = 14m (HERA dish diameter)

Reference: Fagnoni et al. 2021, measured FWHM ~10° at 150 MHz

Frequency	FWHM	FOV Radius
50 MHz	28.1°	14.0°
80 MHz	17.6°	8.8°
100 MHz	14.0°	7.0°
150 MHz	9.4°	4.7°
200 MHz	7.0°	3.5°

Output Description

Plot Elements

1. Background: Diffuse sky model (Inferno colormap, 40th percentile threshold)
2. Observable Strip: Red/blue shaded region showing HERA's FOV during the observation
3. Declination Lines: Dotted horizontal lines at FOV boundaries with Dec labels
4. Strip Boundaries: Dashed vertical lines at LST/RA start and end
5. Point Sources: Blue-to-white colored dots (brighter = higher flux)
6. Top 5 Sources: Yellow highlighted sources with rank labels (1-5)
7. Beam Overlay (optional): RdBu_r colored hemisphere with -3dB and -10dB contours
8. Colorbars: Left (beam dB), Right (flux Jy or GSM brightness)

Interactive Features

• Hover: Display coordinates and flux for point sources
• Zoom: Scroll to zoom, double-click to reset
• Pan: Click and drag to pan
• Save: Use Bokeh toolbar to save as PNG

File Formats

skyh5 Files (pyradiosky)

HERA Strip supports two types of .skyh5 files:

1. Point Source Catalogs (component_type="point")

   • Contains RA, Dec, and Stokes I flux for each source
   • Multiple frequencies supported

2. HEALPix Maps (component_type="healpix")

   • Full-sky diffuse maps in HEALPix format
   • Supports RING or NESTED ordering

Beam FITS Files (pyuvdata)

Beam files should be in UVBeam format with:

• E-field or power beam data
• Azimuth/Zenith angle coordinate system
• Multiple frequencies supported

Module Architecture

herastrip/
├── __init__.py      # Package exports
├── __main__.py      # Entry point for python -m herastrip
├── main.py          # CLI argument parsing and orchestration
├── simulation.py    # HeraStripSimulator class, HERA beam physics
├── sky_model.py     # SkyMapGenerator, PointSourceCatalog, SkyH5MapGenerator
├── beam.py          # BeamProcessor for antenna beam overlay
└── plotting.py      # Plotter class, Bokeh visualization

Key Classes

Class	Module	Description
HeraStripSimulator	simulation.py	Main simulation orchestrator
SkyMapGenerator	sky_model.py	Generate projected maps from pygdsm models
SkyH5MapGenerator	sky_model.py	Load HEALPix maps from skyh5 files
PointSourceCatalog	sky_model.py	Load point sources from skyh5 files
BeamProcessor	beam.py	Load and transform beam patterns
Plotter	plotting.py	Create interactive Bokeh visualizations

Examples

Example 1: Galactic Center Region

# View the Galactic Center (transits at LST ~17.75h)
python -m herastrip --location="-30.7,21.4" --lst-range="16-20" \
    --frequency=150 --use-lst --model=gsm2008

Example 2: Point Sources with Beam

# Overlay GLEAM catalog with beam at Galactic Center
python -m herastrip --location="-30.7,21.4" --lst-range="1-6" \
    --skyh5=./gleam.skyh5 --background=reference --max-sources=300 \
    --use-lst --add-beam=./hera_beam.fits --beam-lst=18

Example 3: Time-Based Observation

# 2-hour observation starting at specific UTC time
python -m herastrip --location="-30.7,21.4" \
    --start="2024-04-06T22:00:00" --duration=7200 --frequency=80

Example 4: Save Output

python -m herastrip --location="-30.7,21.4" --lst-range="1.25-5.75" \
    --frequency=80 --use-lst --output=./plots/
# Saves to ./plots/sky_strip.html

Coordinate Systems

Right Ascension (RA) Mode

• X-axis: RA in degrees (-180° to 180°)
• Centered at RA = 0° (vernal equinox)

Local Sidereal Time (LST) Mode (--use-lst)

• X-axis: LST in hours (displayed as 0h-24h)
• Internally centered at LST = 0h (-12h to 12h)
• LST = RA / 15 (hours = degrees / 15)

Declination

• Y-axis: Dec in degrees (-90° to 90°)
• HERA at latitude -30.7° sees Dec from ~-90° to ~+60°

Troubleshooting

"No module named 'X'"

Install all required dependencies:

pip install -r requirements.txt

Beam overlay not visible

• Check --beam-lst is within the plot's LST range
• Increase --beam-vmin (e.g., -30 instead of -40) for more visibility

Plot appears blank

• Ensure frequency is within the model's valid range
• Check that skyh5 file exists and is readable

References

• HERA: https://reionization.org/
• Fagnoni et al. 2021 - HERA beam measurements
• de Oliveira-Costa et al. 2008 - GSM2008
• Zheng et al. 2017 - GSM2016
• Dowell et al. 2017 - LFSS
• Haslam et al. 1982 - 408 MHz all-sky survey

Author

Kartik Mandar Email: [e-mail]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request