MagMAP is a python package for downloading, mapping, and processing solar magnetograms. It is an integral component of the Open-source Flux Transport OFT model.
First, download or clone this repository. For example:
git clone https://github.com/predsci/MagMAP.git
A conda recipe file is provided in rsrc/conda_recipe_magmap.yml.
See here for instructions on installing a conda environment.
This recipe is not necessary for using MagMAP, but does ensure that all dependencies are installed—and
that incompatible dependency versions are avoided.
To build this conda environment, first be sure that conda is active in your current shell.
As some packages/versions are in the conda-forge channel, check that it is in your python environment with:
conda config --show channels
If conda-forge is not there, add it with:
conda config --append channels conda-forge
The MagMAP conda environment can then be built using:
conda env create -f rsrc/conda_recipe_magmap.yml
To activate the environment, use:
conda activate magmap
This environment (or equivalent) should be active before each use of magmap.
While in the directory of the repository clone, install the magmap package into
your environment with:
pip install ${PWD}
The standard use of MagMAP involves two steps: 1) data acquisition of magnetogram disk images, and 2) mapping them into Carrington coordinate maps (along with converting the disk image data to radial magnetic field). If using the conda magmap environment described above, ensure it is active before running magmap.
The file bin/magmap_get_data.py is an executable script that downloads HMI line-of-site magnetograms. By default, given start and end timestamps will download HMI_M 720s images between those dates/times at a one hour cadence:
python magmap_get_data.py 2024-01-01T00:00:00 2024-01-02T00:00:00
The script will download the data and store them in an orderly directory structure with an index CSV file that lists the timestamp and relative path of each data file.
The script has optional arguments to set the data cadence, search window, output directory, and index file name.
Run python magmap_get_data.py -h for more information on these options.
The script can also update an existing folder of disk data with the most recently available data by running the script with the output directory set to the existing folder.
For another example script on how magmap can update an existing directory with the most recent HMI magnetograms, see magmap/scripts/Update_local_HMI.py.
Once HMI disk magnetogram image data has been downloaded, the script bin/magmap_disk2map.py is used to convert line-of-sight to radial magnetic field values (Br) and to interpolate to a longitude-colatitude Carrington coordinate map.
The process has five primary steps:
- Load the disk data and convert it into Br
- Interpolate the Br disk data to a very high resolution "interpolation" Carrington coordinate map
- Bin the high resolution map down to the chosen final map resolution (default 1024x512) using flux-preserving integration
- Set a layer of default data assimilation weights for use with HipFT as well as an additional layer with mu=cos(t) where
tis the disk-to-limb angle for use with custom assimilation functions in HipFT - Save the final three-layer maps in 3D HDF5 files
An example of running magmap_disk2map.pyon a folder containing the output of magmap_get_data.py (called here magmap_data_disks) is:
python magmap_disk2map.py magmap_data_disks
The script will process and map the disk data and store them in an orderly directory structure with an index CSV file that lists the timestamp and relative path of each map file.
The script has optional arguments to set the start and end date/time (for processing subsets), the theta and phi resolutions of the final maps, the assumed radius of the disk data (in solar radii), the theta and phi resolutions used for the high resolution interpolation map, output directory, and index file name. Run python magmap_disk2map.py -h for more information on these options.
Once a map output folder is generated, it can be directly used with HipFT (see instructions there).
The script can also be used to update a pre-existing map output folder by rerunning it on the same disk data folder with the same output folder name.
For the purpose of automated data processing, an alternative script magmap/scripts/Update_Map_HMI.py can be used/referenced to update maps as new data comes in.
James Turtle (jturtle@predsci.com)
- James Turtle
- Ronald M. Caplan
- Cooper Downs
- Jon A. Linker