amisrsynthdata documentation

amisrsynthdata

This module provides tools to create synthetic data files for the AMISR (Advanced Module Incoherent Scatter Radar) systems. The files are based on both a specified ionospheric state and a radar configuration. This can be used to generate synthetic data in the “SRI data format” both for the three existing AMISRs and for hypothetical future “AMISR-like” systems. Primarily, it was designed to help test the functionality of various inversion algorithms that attempt to create a complete picture of ionospheric state parameters from discrete measurements by creating a way to check the output of these algorithms against known “truth” data. Please note that this module does NOT attempt to simulate any aspect of fundamental ISR theory.

docs/synthdata_summary_ne.png docs/synthdata_gemini_plot.png

Quick Start

Installation

The amisrsynthdata package is pure python and can be installed with pip:

pip install amisrsynthdata

Additional installation instructions are also available.

Example Usage

This package installs the command line tool amisrsynthdata, which is used along with a YAML configuration file to generate an output hdf5 AMISR data file. The configuration file specifies the ionosphere state and radar configuration that should be used. The following steps show how to use a provided example configuration file to run amisrsythdata.

  1. Install amisrsynthdata with the plots option.

pip install 'amisrsynthdata[plots]'
  1. Download the example configuration file. This can be done directly from the repository webpage or with a command line utility such as wget.

wget https://raw.githubusercontent.com/amisr/amisrsynthdata/refs/heads/main/example_synth_config.yaml
  1. Run amisrsynthdata with the verbose option.

amisrsynthdata example_synth_config.yaml -v

This should product the output synthetic data file synthetic_data.h5 and four summary plot files in your working directory. Note that this example uses extremely simple ionospheric state functions for illustrative purposes. By editing the options in the configuration file, you can specify the radar mode and ionosphere that are used to create the synthetic data. Refer to the configuration file documentation for information about the contents of the configuration file.

Additional information about using this pacakge is available in the usage documentation.

Limitations

The following are NOT currently included in the amisrsynthdata module:

  1. Any kind of proper treatment or simulation of ISR theory - The module effectively assumes the radar measures plasma parameters perfectly at a particular location, although empirical errors can be added.

  2. Integration over a time period or smearing along the length of pulses, as well as pulse coding.

  3. Madrigal data format - Currently files are only generated in the SRI data format.

Documentation

Full documentation for amisrsynthdata is available on ReadTheDocs.

Contributing

Contributions to this package are welcome and encouraged, particularly to expand the currently set of specified ionospheres. Contributions can take the form of issues to report bugs and request new features and pull requests to submit new code. Please refer to the contributing guidelines for more details. Specific instructions on how to add a new state function to describe the ionosphere are available in Create New State Functions.

Indices and tables