satpy.readers.ahi_hsd module

Advanced Himawari Imager (AHI) standard format data reader.

References

Time Information

AHI observations use the idea of a “nominal” time and an “observation” time. The “nominal” time or repeat cycle is the overall window when the instrument can record data, usually at a specific and consistent interval. The “observation” time is when the data was actually observed inside the nominal window. These two times are stored in a sub-dictionary in the metadata calls time_parameters. Nominal time can be accessed from the nominal_start_time and nominal_end_time metadata keys and observation time from the observation_start_time and observation_end_time keys. Observation time can also be accessed from the parent (.attrs) dictionary as the start_time and end_time keys.

Satellite Position

As discussed in the Orbital Parameters documentation, a satellite position can be described by a specific “actual” position, a “nominal” position, a “projection” position, or sometimes a “nadir” position. Not all readers are able to produce all of these positions. In the case of AHI HSD data we have an “actual” and “projection” position. For a lot of sensors/readers though, the “actual” position values do not change between bands or segments of the same time step (repeat cycle). AHI HSD files contain varying values for the actual position.

Other components in Satpy use this actual satellite position to generate other values (ex. sensor zenith angles). If these values are not consistent between bands then Satpy (dask) will not be able to share these calculations (generate one sensor zenith angle for band 1, another for band 2, etc) even though there is rarely a noticeable difference. To deal with this this reader has an option round_actual_position that defaults to True and will round the “actual” position (longitude, latitude, altitude) in a way to produce as consistent a position between bands as possible.

class satpy.readers.ahi_hsd.AHIHSDFileHandler(filename, filename_info, filetype_info, mask_space=True, calib_mode='update', user_calibration=None, round_actual_position=True)[source]

Bases: BaseFileHandler

AHI standard format reader.

The AHI sensor produces data for some pixels outside the Earth disk (i,e: atmospheric limb or deep space pixels). By default, these pixels are masked out as they contain data of limited or no value, but some applications do require these pixels. It is therefore possible to override the default behaviour and perform no masking of non-Earth pixels.

In order to change the default behaviour, use the ‘mask_space’ variable as part of reader_kwargs upon Scene creation:

import satpy
import glob

filenames = glob.glob('*FLDK*.dat')
scene = satpy.Scene(filenames,
                    reader='ahi_hsd',
                    reader_kwargs={'mask_space': False})
scene.load([0.6])

The AHI HSD data files contain multiple VIS channel calibration coefficients. By default, the updated coefficients in header block 6 are used. If the user prefers the default calibration coefficients from block 5 then they can pass calib_mode=’nominal’ when creating a scene:

import satpy
import glob

filenames = glob.glob('*FLDK*.dat')
scene = satpy.Scene(filenames,
                    reader='ahi_hsd',
                    reader_kwargs={'calib_mode': 'update'})
scene.load([0.6])

Alternative AHI calibrations are also available, such as GSICS coefficients. As such, you can supply custom per-channel correction by setting calib_mode=’custom’ and passing correction factors via:

user_calibration={'chan': ['slope': slope, 'offset': offset]}

Where slo and off are per-channel slope and offset coefficients defined by:

rad_leo = (rad_geo - off) / slo

If you do not have coefficients for a particular band, then by default the slope will be set to 1 .and the offset to 0.:

import satpy
import glob

# Load bands 7, 14 and 15, but we only have coefs for 7+14
calib_dict = {'B07': {'slope': 0.99, 'offset': 0.002},
              'B14': {'slope': 1.02, 'offset': -0.18}}

filenames = glob.glob('*FLDK*.dat')
scene = satpy.Scene(filenames,
                    reader='ahi_hsd',
                    reader_kwargs={'user_calibration': calib_dict)
# B15 will not have custom radiance correction applied.
scene.load(['B07', 'B14', 'B15'])

By default, user-supplied calibrations / corrections are applied to the radiance data in accordance with the GSICS standard defined in the equation above. However, user-supplied gain and offset values for converting digital number into radiance via Rad = DN * gain + offset are also possible. To supply your own factors, supply a user calibration dict using type: ‘DN’ as follows:

calib_dict = {'B07': {'slope': 0.0037, 'offset': 18.5},
              'B14': {'slope': -0.002, 'offset': 22.8},
              'type': 'DN'}

You can also explicitly select radiance correction with ‘type’: ‘RAD’ but this is not necessary as it is the default option if you supply your own correction coefficients.

Initialize the reader.

_check_fpos(fp_, fpos, offset, block)[source]

Check file position matches blocksize.

_get_area_def()[source]
_get_metadata(key, ds_info)[source]
_get_user_calibration_correction_type()[source]
_ir_calibrate(data)[source]

IR calibration.

_mask_invalid(data, header)[source]

Mask invalid data.

_mask_space(data)[source]

Mask space pixels.

_read_data(fp_, header, resolution)[source]

Read data block.

_read_header(fp_)[source]

Read header.

property _timeline
_vis_calibrate(data)[source]

Visible channel calibration only.

property area

Get AreaDefinition representing this file’s data.

calibrate(data, calibration)[source]

Calibrate the data.

convert_to_radiance(data)[source]

Calibrate to radiance.

property end_time

Get the nominal end time.

get_area_def(dsid)[source]

Get the area definition.

get_dataset(key, info)[source]

Get the dataset.

property nominal_end_time

Get the nominal end time.

property nominal_start_time

Time this band was nominally to be recorded.

property observation_end_time

Get the observation end time.

property observation_start_time

Get the observation start time.

read_band(key, ds_info)[source]

Read the data.

property start_time

Get the nominal start time.

class satpy.readers.ahi_hsd._NominalTimeCalculator(timeline, area)[source]

Bases: object

Get time when a scan was nominally to be recorded.

Initialize the nominal timestamp calculator.

Parameters:

  • timeline (str) – Observation timeline (four characters HHMM)

  • area (str) – Observation area (four characters, e.g. FLDK)

_get_closest_timeline(observation_time)[source]

Find the closest timeline for the given observation time.

Needs to check surrounding days because the observation might start a little bit before the planned time.

Observation start time: 2022-12-31 23:59 Timeline: 0000 => Nominal start time: 2023-01-01 00:00

_get_offset_relative_to_timeline()[source]
_modify_observation_time_for_nominal(observation_time)[source]

Round observation time to a nominal time based on known observation frequency.

AHI observations are split into different sectors including Full Disk (FLDK), Japan (JP) sectors, and smaller regional (R) sectors. Each sector is observed at different frequencies (ex. every 10 minutes, every 2.5 minutes, and every 30 seconds). This method will take the actual observation time and round it to the nearest interval for this sector. So if the observation time is 13:32:48 for the “JP02” sector which is the second Japan observation where every Japan observation is 2.5 minutes apart, then the result should be 13:32:30.

property _observation_frequency
_parse_timeline(timeline)[source]
get_nominal_end_time(nominal_start_time)[source]

Get nominal end time of the scan.

get_nominal_start_time(observation_start_time)[source]

Get nominal start time of the scan.