coconut_tools.magnetogram.magnetogram_download¶

Magnetogram discovery, selection, and download helpers.

Functions

`append_timestamp_to_path`(path, date)	Append a compact timestamp before a path extension.
`build_gong_remote_dir`(date[, file_id])	Build a GONG QR magnetogram directory URL for one day.
`build_output_name`(map_type, output_dir[, ...])	Build the COCONUT boundary filename for a target date.
`build_processing_dates`(start_date[, ...])	Build target dates from a start date, cadence, and total duration.
`default_figure_path`(output_dir, map_type, date)	Build a default diagnostic figure path for one target date.
`download_candidate`(candidate, output_dir)	Download one candidate if it is missing locally.
`download_hmi_sync_magnetogram`(date_datetime, ...)	Download the nearest downloadable HMI_SYNC magnetogram through JSOC DRMS.
`download_interpolation_magnetograms`(date, ...)	Download the four magnetograms needed for temporal interpolation.
`fetch_remote_names`(remote_dir, file_id)	List remote filenames from a GONG-style directory page.
`find_hmi_sync_candidates`(client, date_datetime)	Return available HMI_SYNC metadata records sorted by distance to the target date.
`find_nearest_hmi_sync_record`(client, ...[, ...])	Find the nearest available HMI_SYNC record around a target datetime.
`format_timestamp`(date)	Format a datetime as YYYYMMDDHHMMSS for output filenames.
`generate_output_and_interpolation_map_names`(...)	Generate output name and download four maps for temporal interpolation.
`generate_output_and_map_names`(date, ...[, ...])	Generate output filename and download magnetogram file based on map type.
`gong_file_id_from_map_type`(map_type)	Resolve the GONG file identifier encoded by a map type.
`is_gong_diachronic_map_type`(map_type)	Return True for GONG diachronic map types.
`is_gong_map_type`(map_type)	Return True for legacy and file-id-specific GONG map types.
`is_gong_temporal_map_type`(map_type)	Return True for GONG map types supported by four-map interpolation.
`is_jsoc_unavailable_error`(exc)	Return True if JSOC found the record but the data file is unavailable.
`list_adapt_candidates`(date)	List ADAPT candidates around a target date.
`list_gong_candidates`(date[, file_id])	List GONG candidates around a target date.
`list_gong_diachronic_candidates`(date, file_id)	List GONG diachronic files from the closest available date folder.
`list_remote_candidates`(date, map_type)	List remote temporal candidates for a map type.
`magnetogram_display_date`(file_path, ...[, ...])	Return the date that should be displayed for a processed magnetogram.
`magnetogram_effective_date`(file_path, ...[, ...])	Return the timestamp represented by a processed magnetogram.
`normalize_map_type`(map_type)	Return the canonical map type, accepting case-insensitive input.
`parse_date_from_filename`(name, fmt, split_token)	Parse date from filename using a given format and delimiter.
`parse_hmi_sync_filename_date`(name)	Parse the timestamp from an HMI_SYNC JSOC FITS filename.
`parse_iso_datetime`(date)	Parse a date value into a datetime.
`parse_jsoc_trec`(t_rec)	Parse a JSOC T_REC string like 2025.11.22_08:24:00_TAI.
`resolve_figure_path`(output_path_fig, ...[, ...])	Build a figure filename from an optional file or directory path.
`select_interpolation_stencil`(candidates, ...)	Select four magnetograms around a target date for Hermite interpolation.
`select_nearest_candidate`(candidates, target_date)	Select the candidate closest to a target date.
`try_download_hmi_sync_record`(client, t_rec, ...)	Try to download one HMI_SYNC record.
`unique_sorted_candidates`(candidates)	Sort candidates and keep one entry per timestamp.

Classes

`InterpolationSelection`(before_previous, ...)	Four-map temporal interpolation stencil and its time weights.
`MagnetogramCandidate`(name, date, remote_url)	Remote magnetogram candidate with an observation timestamp.

class coconut_tools.magnetogram.magnetogram_download.InterpolationSelection(before_previous, before, after, after_next, coef_before, coef_after, interval_seconds, previous_interval_seconds, next_interval_seconds, target_date)[source]¶

Bases: object

Four-map temporal interpolation stencil and its time weights.

Parameters:

before_previous (MagnetogramCandidate)
before (MagnetogramCandidate)
after (MagnetogramCandidate)
after_next (MagnetogramCandidate)
coef_before (float)
coef_after (float)
interval_seconds (float)
previous_interval_seconds (float)
next_interval_seconds (float)
target_date (datetime)

after: MagnetogramCandidate¶

after_next: MagnetogramCandidate¶

before: MagnetogramCandidate¶

before_previous: MagnetogramCandidate¶

coef_after: float¶

coef_before: float¶

interval_seconds: float¶

next_interval_seconds: float¶

previous_interval_seconds: float¶

target_date: datetime¶

class coconut_tools.magnetogram.magnetogram_download.MagnetogramCandidate(name, date, remote_url)[source]¶

Bases: object

Remote magnetogram candidate with an observation timestamp.

Parameters:

name (str)
date (datetime)
remote_url (str)

date: datetime¶

name: str¶

remote_url: str¶

coconut_tools.magnetogram.magnetogram_download.append_timestamp_to_path(path, date)[source]¶

Append a compact timestamp before a path extension.

Return type:

str

Parameters:

path (str)
date (str | datetime)

coconut_tools.magnetogram.magnetogram_download.build_gong_remote_dir(date, file_id='mrzqs')[source]¶

Build a GONG QR magnetogram directory URL for one day.

Return type:

str

Parameters:

date (datetime)
file_id (str)

coconut_tools.magnetogram.magnetogram_download.build_output_name(map_type, output_dir, method_used='sph')[source]¶

Build the COCONUT boundary filename for a target date.

Return type:

str

Parameters:

map_type (str)
output_dir (str)
method_used (str)

coconut_tools.magnetogram.magnetogram_download.build_processing_dates(start_date, cadence_hours=None, total_hours=None)[source]¶

Build target dates from a start date, cadence, and total duration.

Return type:

list[datetime]

Parameters:

start_date (str | datetime)
cadence_hours (float | None)
total_hours (float | None)

coconut_tools.magnetogram.magnetogram_download.default_figure_path(output_dir, map_type, date)[source]¶

Build a default diagnostic figure path for one target date.

Return type:

str

Parameters:

output_dir (str)
map_type (str)
date (str | datetime)

coconut_tools.magnetogram.magnetogram_download.download_candidate(candidate, output_dir)[source]¶

Download one candidate if it is missing locally.

Return type:

str

Parameters:

candidate (MagnetogramCandidate)
output_dir (str)

coconut_tools.magnetogram.magnetogram_download.download_hmi_sync_magnetogram(date_datetime, output_dir, drms_email)[source]¶

Download the nearest downloadable HMI_SYNC magnetogram through JSOC DRMS.

Return type:

tuple[str, str]

Parameters:

date_datetime (datetime)
output_dir (str)
drms_email (str | None)

coconut_tools.magnetogram.magnetogram_download.download_interpolation_magnetograms(date, map_type, output_dir)[source]¶

Download the four magnetograms needed for temporal interpolation.

Return type:

tuple[list[str], InterpolationSelection]

Parameters:

date (str | datetime)
map_type (str)
output_dir (str)

coconut_tools.magnetogram.magnetogram_download.fetch_remote_names(remote_dir, file_id)[source]¶

List remote filenames from a GONG-style directory page.

Return type:

list[str]

Parameters:

remote_dir (str)
file_id (str)

coconut_tools.magnetogram.magnetogram_download.find_hmi_sync_candidates(client, date_datetime, half_window_hours=12)[source]¶

Return available HMI_SYNC metadata records sorted by distance to the target date.

Return type:

list[tuple[str, datetime]]

Parameters:

date_datetime (datetime)
half_window_hours (int)

coconut_tools.magnetogram.magnetogram_download.find_nearest_hmi_sync_record(client, date_datetime, half_window_hours=12)[source]¶

Find the nearest available HMI_SYNC record around a target datetime.

Return type:

tuple[str, datetime]

Parameters:

date_datetime (datetime)
half_window_hours (int)

coconut_tools.magnetogram.magnetogram_download.format_timestamp(date)[source]¶

Format a datetime as YYYYMMDDHHMMSS for output filenames.

Return type:: str
Parameters:: date (str | datetime)

coconut_tools.magnetogram.magnetogram_download.generate_output_and_interpolation_map_names(date, map_type, output_dir, method_used='sph', download_dir=None)[source]¶: Generate output name and download four maps for temporal interpolation.

coconut_tools.magnetogram.magnetogram_download.generate_output_and_map_names(date, map_type, output_dir, method_used='sph', drms_email=None)[source]¶

Generate output filename and download magnetogram file based on map type.

Parameters:: drms_email (str | None)

coconut_tools.magnetogram.magnetogram_download.gong_file_id_from_map_type(map_type)[source]¶

Resolve the GONG file identifier encoded by a map type.

Return type:: str
Parameters:: map_type (str)

coconut_tools.magnetogram.magnetogram_download.is_gong_diachronic_map_type(map_type)[source]¶

Return True for GONG diachronic map types.

Return type:: bool
Parameters:: map_type (str)

coconut_tools.magnetogram.magnetogram_download.is_gong_map_type(map_type)[source]¶

Return True for legacy and file-id-specific GONG map types.

Return type:: bool
Parameters:: map_type (str)

coconut_tools.magnetogram.magnetogram_download.is_gong_temporal_map_type(map_type)[source]¶

Return True for GONG map types supported by four-map interpolation.

Return type:: bool
Parameters:: map_type (str)

coconut_tools.magnetogram.magnetogram_download.is_jsoc_unavailable_error(exc)[source]¶

Return True if JSOC found the record but the data file is unavailable.

Return type:: bool
Parameters:: exc (Exception)

coconut_tools.magnetogram.magnetogram_download.list_adapt_candidates(date)[source]¶

List ADAPT candidates around a target date.

Return type:: list[MagnetogramCandidate]
Parameters:: date (str | datetime)

coconut_tools.magnetogram.magnetogram_download.list_gong_candidates(date, file_id='mrzqs')[source]¶

List GONG candidates around a target date.

Return type:

list[MagnetogramCandidate]

Parameters:

date (str | datetime)
file_id (str)

coconut_tools.magnetogram.magnetogram_download.list_gong_diachronic_candidates(date, file_id)[source]¶

List GONG diachronic files from the closest available date folder.

Return type:

list[MagnetogramCandidate]

Parameters:

date (str | datetime)
file_id (str)

coconut_tools.magnetogram.magnetogram_download.list_remote_candidates(date, map_type)[source]¶

List remote temporal candidates for a map type.

Return type:

list[MagnetogramCandidate]

Parameters:

date (str | datetime)
map_type (str)

coconut_tools.magnetogram.magnetogram_download.magnetogram_display_date(file_path, map_type, target_date, interpolated=False)[source]¶

Return the date that should be displayed for a processed magnetogram.

Return type:

datetime

Parameters:

file_path (str)
map_type (str)
target_date (str | datetime)
interpolated (bool)

coconut_tools.magnetogram.magnetogram_download.magnetogram_effective_date(file_path, map_type, target_date, interpolated=False)[source]¶

Return the timestamp represented by a processed magnetogram.

Interpolated maps represent the requested target time. Non-interpolated GONG, ADAPT, and HMI_SYNC maps represent the observation time encoded in their filenames. HMI small/polar-filled and WSO products use the requested target time by convention.

Return type:

datetime

Parameters:

file_path (str)
map_type (str)
target_date (str | datetime)
interpolated (bool)

coconut_tools.magnetogram.magnetogram_download.normalize_map_type(map_type)[source]¶

Return the canonical map type, accepting case-insensitive input.

Return type:: str
Parameters:: map_type (str)

coconut_tools.magnetogram.magnetogram_download.parse_date_from_filename(name, fmt, split_token)[source]¶: Parse date from filename using a given format and delimiter.

coconut_tools.magnetogram.magnetogram_download.parse_hmi_sync_filename_date(name)[source]¶

Parse the timestamp from an HMI_SYNC JSOC FITS filename.

Return type:: datetime | None
Parameters:: name (str)

coconut_tools.magnetogram.magnetogram_download.parse_iso_datetime(date)[source]¶

Parse a date value into a datetime.

Return type:: datetime
Parameters:: date (str | datetime)

coconut_tools.magnetogram.magnetogram_download.parse_jsoc_trec(t_rec)[source]¶

Parse a JSOC T_REC string like 2025.11.22_08:24:00_TAI.

Return type:: datetime
Parameters:: t_rec (str)

coconut_tools.magnetogram.magnetogram_download.resolve_figure_path(output_path_fig, output_dir, map_type, date, use_unique_name=False)[source]¶

Build a figure filename from an optional file or directory path.

Return type:

str

Parameters:

output_path_fig (str | None)
output_dir (str)
map_type (str)
date (str | datetime)
use_unique_name (bool)

coconut_tools.magnetogram.magnetogram_download.select_interpolation_stencil(candidates, target_date)[source]¶

Select four magnetograms around a target date for Hermite interpolation.

Return type:

InterpolationSelection

Parameters:

candidates (list[MagnetogramCandidate])
target_date (str | datetime)

coconut_tools.magnetogram.magnetogram_download.select_nearest_candidate(candidates, target_date)[source]¶

Select the candidate closest to a target date.

Return type:

MagnetogramCandidate

Parameters:

candidates (list[MagnetogramCandidate])
target_date (str | datetime)

coconut_tools.magnetogram.magnetogram_download.try_download_hmi_sync_record(client, t_rec, output_dir)[source]¶

Try to download one HMI_SYNC record. Return None if the data file is unavailable.

Return type:

tuple[str, str] | None

Parameters:

t_rec (str)
output_dir (str)

coconut_tools.magnetogram.magnetogram_download.unique_sorted_candidates(candidates)[source]¶

Sort candidates and keep one entry per timestamp.

Return type:: list[MagnetogramCandidate]
Parameters:: candidates (list[MagnetogramCandidate])