plot.py

Module for constructing the standard AstroQ plots. All plots are returned as html strings. From there, they can be used as is or saved as png files.

class astroq.plot.StarPlotter(unique_id)

Bases: object

Define the StarPlotter class, which contains all information about a single request which is used for standardizing the plot inputs.

get_future(forecast_df, all_dates_array)

Gather the star’s future schedule out of the semester_planner solution from semester_plan.csv.

Parameters:

• forecast_df (pd.DataFrame) – Pre-loaded forecast DataFrame with minimum columns [‘r’, ‘d’, ‘s’]

• all_dates_array (list) – List of all dates in the semester, indexed by ‘d’

Returns:

None

get_map(semester_planner, forecast_df)

Build the 2D d/s matrix starmap for teh given star using semester_plan.csv. Only set starmap[d, s] = 1 if sched[‘r’] == self.unique_id.

Parameters:

• semester_planner – The semester planner object

• forecast_df (pd.DataFrame) – Pre-loaded forecast DataFrame with columns [‘r’, ‘d’, ‘s’]

get_past(past)

Gather the information about a star’s past observation history this semester in standard format.

Parameters:

past (DataFrame) – A DataFrame version of past.csv.

Returns:

None.

get_stats(row, slot_size)

Grab the observational stategy information for a given star from the requests.csv file.

Parameters:

• row (pd.Series) – A row from the requests.csv file as a DataFrame

• slot_size (int) – The slot size in minutes

Returns:

how many exposures we expect to take total_observations_requested (int): sum of observational strategie values exposure_time (int): exposure time of single shot slots_per_night (int): number of slots required to complete all exposures in a night program (str): the program code

Return type:

expected_nobs_per_night (int)

astroq.plot.add_star_links(request_df, semester_code, date, band)

Convert starname column to links: /semester/date/band/program_code/starname

Parameters:

• request_df (pd.DataFrame) – request frame with starname and program_code columns

• semester_code (str) – e.g. 2025B

• date (str) – e.g. 2025-01-15

• band (str) – e.g. band1

Returns:

df with starname as HTML links

Return type:

request_df (pd.DataFrame)

astroq.plot.compute_seasonality(semester_planner, starnames, ras, decs)

Compute the number of days a RA/Dec point is observable in the semester using Access object

Parameters:

• semester_planner (SemesterPlanner) – the semester planner object containing configuration

• starnames (list) – list of star names

• ras (array) – right ascension values in degrees

• decs (array) – declination values in degrees

Returns:

number of observable nights for each target

Return type:

available_nights_onsky (list)

astroq.plot.createTelSlewPath(stamps, changes, pointings, animationStep=120)

Correctly assign each frame of the animation to the telescope pointing at that time

stamps (list of zeros) - the list where each element represents a frame of the animation. We manipulate and return this at the end. changes (list) - the times at which the telescope pointing changes (in order of the slew path) poitings (list) - the astropy target objects of for the stars to be observed, in order of the slew path animationStep (int) - the time, in seconds, between frames

return

stamps - now a list where element holds the pointing of the telescope (aka the star object) at that frame

astroq.plot.dataframe_to_html(dataframe, sort_column=2, page_size=10, table_id='request-table')

Convert a pandas dataframe into an HTML string for rendering on the webapp pages.

Parameters:

• dataframe (pd.DataFrame) – The dataframe to convert

• sort_column (int) – Column index to sort by (default: 2 for starname)

• page_size (int) – Default number of rows per page (default: 25)

• table_id (str) – Unique ID for the table (default: ‘request-table’)

Returns:

HTML string with table and DataTables initialization

Return type:

table_html (str)

astroq.plot.get_birdseye(semester_planner, availablity, all_stars)

Produce the plotly figure showing the day/slot matrix intersection for a selection of stars

Parameters:

• semester_planner (obj) – a SemesterPlanner object from splan.py

• availability (array) – a 2D array of N_slots by N_nights, binary 1/0, it is the intersection of is_alloc and is_night

• all_stars (array) – a array of StarPlotter objects

Returns:

a plotly figure showing the day/slot matrix intersection for a selection of stars

Return type:

fig (plotly figure)

astroq.plot.get_cof(semester_planner, all_stars, use_time=False)

Produce a plotly figure showing the Cumulative Observability Function (COF) for a selection of stars

Parameters:

• semester_planner (obj) – a SemesterPlanner object from splan.py

• all_stars (array) – a array of StarPlotter objects

• use_time (bool) – if True, use the cumulative observe time percentage instead of the cumulative observe percentage

Returns:

a plotly figure showing the COF for a selection of stars

Return type:

fig (plotly figure)

astroq.plot.get_football(semester_planner, all_stars, use_program_colors=False)

Produce a plotly figure showing the sky map of the locations of requests with a static heatmap background and interactive star points.

Parameters:

• semester_planner – the semester planner object

• all_stars (list) – array of StarPlotter objects

• use_program_colors (bool) – If True, use program_color_rgb; if False, use star_color_rgb (default: False)

Returns:

a plotly figure showing the sky map of the locations of requests with a static heatmap background and interactive star points.

Return type:

fig (plotly figure)

astroq.plot.get_ladder(data, tonight_start_time)

Produce a plotly figure which illustrates the night plan solution.

Parameters:

data (obj) – a TTP data object containing the schedule information

Returns:

a plotly figure illustrating the night plan solution.

Return type:

fig (plotly figure)

astroq.plot.get_rawobs(semester_planner, all_stars, use_program_colors=False)

Produce a plotly figure showing a scatter plot of observation counts for each star. X-axis: total requested observations Y-axis: sum of past and scheduled observations Each point represents one StarPlotter object.

Parameters:

• semester_planner (obj) – a SemesterPlanner object from splan.py

• all_stars (array) – an array of StarPlotter objects

• use_program_colors (bool) – If True, use program_color_rgb; if False, use star_color_rgb (default: False)

Returns:

a plotly figure showing observation counts as a scatter plot

Return type:

fig (plotly figure)

astroq.plot.get_request_frame(semester_planner, all_stars)

Get a filtered request frame containing only the stars in all_stars.

Parameters:

• semester_planner – the semester planner object

• all_stars (list) – array of StarPlotter objects

Returns:

filtered request frame with only the specified stars

Return type:

filtered_frame (pd.DataFrame)

astroq.plot.get_script_plan(night_planner)

Generate script plan DataFrame from semester planner and night planner objects.

This function reads the request_selected.csv file from the semester planner’s output directory, merges it with the night planner’s solution data, and returns a properly formatted DataFrame with the same column structure as the original get_script_plan function.

Parameters:

night_planner – NightPlanner object containing solution attribute

Returns:

a formatted observing plan DataFrame

Return type:

final_df (pd.DataFrame)

astroq.plot.get_slew_animation_plotly(data, request_selected_path, animationStep=120)

Create a Plotly animated polar plot showing telescope slew path during observations.

Parameters:

• data – TTP data containing the schedule information

• request_selected_path – Path to request_selected.csv file

• animationStep (int) – the time, in seconds, between animation frames. Default to 120s.

Returns:

an interactive animated figure with play/pause controls

Return type:

fig (plotly figure)

astroq.plot.get_tau_inter_line(semester_planner, all_stars, use_program_colors=False)

Produce a plotly figure showing requested vs on sky inter-night cadences, grouped by star name.

Parameters:

• semester_planner (obj) – a SemesterPlanner object from splan.py

• all_stars (array) – a array of StarPlotter objects

• use_program_colors (bool) – If True, use program_color_rgb; if False, use star_color_rgb (default: False)

Returns:

a plotly figure showing requested vs on sky inter-night cadences, grouped by star name.

Return type:

fig (plotly figure)

astroq.plot.get_timebar(semester_planner, all_stars, use_program_colors=False, prevent_negative=False)

Create a horizontal bar chart of the time used vs forecasted vs available

Parameters:

• semester_planner – the semester planner object

• all_stars (list) – array of StarPlotter objects

• use_program_colors (bool) – If True, use program_color_rgb; if False, use star_color_rgb (default: False)

• prevent_negative (bool) – If True, set Incomplete and Not used categories to zero if they are negative (default: True)

Returns:

a plotly figure showing the time used vs forecasted vs available as a horizontal bar chart

Return type:

fig (plotly figure)

astroq.plot.get_timebar_by_program(semester_planner, programs_dict, prevent_negative=False)

Create a grid of horizontal bar charts showing time breakdown for each program individually

Each program displays 5 bars: Unused, Incomplete, Future Scheduled, Past Completed, and Requested. A dashed vertical line represents their total allocated time. Programs are arranged in a grid with 3 columns. All bars use the same scale for easy comparison across programs.

Parameters:

• semester_planner – the semester planner object

• programs_dict (dict) – dictionary mapping program codes to lists of StarPlotter objects (e.g., data_astroq[0])

• prevent_negative (bool) – If True, set Incomplete and Not used categories to zero if they are negative (default: False)

Returns:

a plotly figure showing time breakdown per program as a grid of horizontal bar charts

Return type:

fig (plotly figure)

astroq.plot.nightplan_table_to_html(script_df, table_id='script-table', page_size=100)

Convert nightplan script DataFrame to HTML with same styling as request_frame_to_html.

Same colors, fonts, fontsize, filtering (partial match, numeric > < >= <=), hover tooltips. Displays: First Available, Start Exposure, Last Available, unique_id, starname, program_code, ra, dec, exptime, n_exp, n_intra_max, tau_intra, jmag, gmag.

astroq.plot.past_history_table(semester_planner, star_plotters, table_id='past-history-table', page_size=25)

Build a table of past observation history for the given StarPlotter objects.

Columns: starname, total past exposures, total past exposure time, dates (NightOf observing-night dates from n_obs_on_nights, with “– N” counts per night).

Parameters:

• semester_planner – SemesterPlanner instance (for past_history).

• star_plotters (list) – List of StarPlotter objects.

• table_id (str) – HTML id for the table.

• page_size (int) – DataTables page size.

Returns:

HTML string for the table (with DataTables).

Return type:

str

astroq.plot.plot_path_2D_interactive(data, night_start_time=None)

Create an interactive Plotly plot showing telescope azimuth and altitude paths with UTC times and white background.

Parameters:

• data (list) – a list containing the TTP model solution

• night_start_time – Astropy Time object representing the start of night (Minute 0) from allocation file

Returns:

an interactive plot showing telescope azimuth and altitude paths with UTC times and white background.

Return type:

fig (plotly figure)

astroq.plot.process_stars(semester_planner)

Construct the StarPlotter objects for all the stars in the semester planner.

Parameters:

semester_planner (obj) – a SemesterPlanner object from splan.py

Returns:

a dictionary of program names and their corresponding StarPlotter objects programs_as_stars (dict): a dictionary of program names and their corresponding StarPlotter objects nulltime (array): a 2D array of N_slots by N_nights, binary 1/0, it is the intersection of is_alloc and is_night

Return type:

program_dict (dict)

astroq.plot.request_frame_to_html(request_df, semester_code=None, date=None, band=None, table_id='request-table', page_size=25)

Convert a request frame (from request.csv) to HTML for admin/program/star pages.

Displays only: starname, unique_id, program_code, ra, dec, exptime, n_exp, n_inter_max, tau_inter, n_intra_max, n_intra_min, tau_intra, Band1, Band2, Band3, Inactive. Boolean columns (weather bands, inactive) are shown as Y/N with transparent green/red.

Parameters:

• request_df (pd.DataFrame) – request frame, e.g. from get_request_frame

• semester_code (str, optional) – for star links

• date (str, optional) – for star links

• band (str, optional) – for star links

• table_id (str) – HTML table id

• page_size (int) – rows per page

Returns:

HTML string with table and DataTables

Return type:

str