Metadata-Version: 2.1
Name: eis-pointing
Version: 2019.2.6
Summary: Tools to correct the pointing of Hinode/EIS
Home-page: https://github.com/gpelouze/eis_pointing
Author: Gabriel Pelouze
Author-email: gabriel.pelouze@ias.u-psud.fr
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Requires-Dist: astropy (>=3.0)
Requires-Dist: python-dateutil (>=2.7)
Requires-Dist: matplotlib (>=2.0)
Requires-Dist: numpy (>=1.15)
Requires-Dist: requests (>=2.19)
Requires-Dist: scipy (>=1.0)
Requires-Dist: PyYAML (>=3.13)
Requires-Dist: pySitools2

# EIS pointing

Tools to correct the pointing of Hinode/EIS.

## Usage

### From the command line

This tool can be run from the command line by calling
`compute_eis_pointing`:

~~~
usage: compute_eis_pointing [-h] [-s STEPS_FILE] [--io IO] [-c CORES]
                            [--cache-aia-data]
                            filename [filename ...]

Determine the pointing of Hinode/EIS.

positional arguments:
  filename              The names of the level 0 EIS files, eg.
                        'eis_l0_20100815_192002'.

optional arguments:
  -h, --help            show this help message and exit
  -s STEPS_FILE, --steps-file STEPS_FILE
                        Path to a yaml file containing the registration steps.
  --io IO               Directory where output files are written,
                        default: ./io.
  -c CORES, --cores CORES
                        Maximum number of cores used for parallelisation,
                        default: 4.
  --cache-aia-data      Cache the AIA data to a file. This uses a lot of
                        storage, but speeds things up when the same raster is
                        aligned for the second time.
~~~

**Examples (command line):**

~~~bash
compute_eis_pointing -c16 eis_l0_20140810_042212
compute_eis_pointing --steps-file steps/shift_only.yml eis_l0_20140810_042212
~~~

### As a Python module

The tool can also be used from within a Python script, using
`eis_pointing.compute()`.

~~~
compute(*filename, steps_file=None, io='io', cores=4, cache_aia_data=False)
    Perform all computation steps to determine the optimal EIS pointing.

    Parameters
    ==========
    filename : list
        The names of the level 0 EIS files, eg. 'eis_l0_20100815_192002'.
    steps_file : str or None (default: None)
        Path to a yaml file containing the registration steps.
    io : str (default: 'io')
        Directory where output files are written.
    cores : int (default: 4)
        Maximum number of cores used for parallelisation.
    cache_aia_data : bool (default: False)
        Cache the AIA data to a file. This uses a lot of storage, but speeds
        things up when the same raster is aligned for the second time.
~~~

**Examples (Python):**

~~~python
import eis_pointing
eis_pointing.compute('eis_l0_20140810_042212', cores=16)
eis_pointing.compute('eis_l0_20140810_042212', steps_file='steps/shift_only.yml')
~~~

## Installation

### Prerequisite: Installing SolarSoft

In order to prepare and export EIS data, this tool calls external IDL routines
from [SolarSoft]. For all features to be available, a functioning installation
of SolarSoft containing the EIS instrument is therefore required. If SolarSoft
is installed elsewhere than `/usr/local/ssw`, set the environment variable
`$SSW` to the appropriate path.

If SolarSoft is not installed, steps 1 to 3 of the [pipeline](#pipeline) will
have to be performed manually.

### Option 1: Installation using `pip`

Run `pip install eis_pointing`.

### Option 2: Manual installation

1. Clone this repository.
2. Satisfy the dependencies in `requirements.txt`, eg. by running
   `pip install -r requirements.txt`.
3. Place `compute_eis_pointing.py` in your `$PATH`, and
   `eis_pointing/` in your `$PYTHONPATH`.

[SolarSoft]: http://www.ascl.net/1208.013
[pySitools2]: http://medocias.github.io/pySitools2_1.0/

## Customisation

The registration steps used to find the optimal pointing can be customised in a
YAML file, and passed to `eis_pointing` using the `--steps-file` parameter (see
examples above). The file should have a top-level key named `steps` that
contains a list of registration steps. Each step must specify at least a
`type`, chosen between `shift`, `rotshift`, and `slitshift`.

By default, EIS data are coaligned with synthetic AIA raster. To coalign with a
single AIA image, add the top-level key `single_aia_frame: True`. In this case,
the reference AIA image chosen at the middle of the EIS raster.

See files in `steps/` for examples.

When no file is specified, the default behaviour is the same as using
`steps/full_registration.yml`.

## Code structure

### Pipeline

All the steps required to determine the optimal pointing data from EIS level 0
files are defined in `driver.py`. The appropriate functions are called by the
executable `compute_eis_pointing` when using the tool from the CLI, or by
`eis_pointing.compute()` when using it as a Python module.

1. **Download data** Download the required EIS level 0 FITS,
   and place them in the EIS data files and directory structure
   described in [EIS Software Note #18][swn18]
   (eg.  `$HINODE_DATA/eis/level0/2014/08/10/eis_l0_20140810_042212.fits`).

2. **Prepare data** Generate EIS level 1 FITS from level 0, and save it to the
   EIS data files and directory structure
   (eg. `$HINODE_DATA/eis/level1/2014/08/10/eis_l1_20140810_042212.fits`).
   Performed by `eis_pointing/prep.pro`, which calls the SolarSoft routine
   `eis_prep.pro`.

3. **Export windata** Save a `windata` structure containing the
   Fe XII 195.119 Å line, obtained using the SolarSoft function
   `eis_getwindata` (see [EIS Software Note #21][swn21]).
   The structure is saved to `<io>/windata/eis_windata_<date>.sav`
   (eg. `./io/windata/windata_20140810_042212.sav`).
   Performed by `eis_pointing/export_windata.pro`.

   **Alternative to steps 1-3.** Use SolarSoft to prepare the EIS raster,
   then generate a windata structure containing Fe XII 195.119 Å and write
   it to `<io>/windata/eis_windata_<date>.sav`. Eg:

   ~~~IDL
   wd = eis_getwindata('eis_l1_20140810_042212.fits', 195.119, /refill)
   save, wd, filename='./io/windata/windata_20140810_042212.sav'
   ~~~

4. **Compute the EIS emission**
   Generate an intensity map of the Fe XII 195.119 Å line by summing
   the spectra between 194.969 and 195.269 Å. Data are saved to
   `<io>/eis_aia_emission/eis_aia_emission_<date>.fits` (eg.
   `./io/eis_aia_emission/eis_aia_emission_20140810_042212.fits`).
   Performed by `eis_pointing.eis_aia_emission.compute()`.

5. **Determine the optimal pointing** Determine the optimal pointing for EIS
   using the intensity map generated at the previous step, and AIA 193 data
   retrieved from [Medoc][medoc-homepage] as a reference.  Results from the
   alignment (ie. new EIS coordinates) are saved to
   `<io>/pointing/eis_pointing_<date>.fits`. Diagnostics plots, correlation
   cubes, as well as a YAML file containing the results from the coregistration
   are also saved to `<io>/pointing_verification/<date>/`.  Performed by
   `eis_pointing.eis_aia_registration.optimal_pointing()`.

[swn18]: ftp://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/18_FILES/eis_swnote_18.pdf
[swn21]: ftp://sohoftp.nascom.nasa.gov/solarsoft/hinode/eis/doc/eis_notes/21_WINDATA/eis_swnote_21.pdf
[medoc-homepage]: https://idoc.ias.u-psud.fr/MEDOC


### Coregistration functions: `eis_pointing.coregister`

- `images` contains functions to register images in translation, relatively to
  another image.
- `rasters` contains functions to register images in translation and rotation,
  relatively to a synthetic raster.
- `slits` functions to register slit positions (ie. vertical columns in an
  image) separately, relatively to a synthetic raster.
- `tools` functions shared among the previous submodules.

### Functions shared by different components `eis_pointing.utils`

- `aia_raster`: defines `AIARasterGenerator` that builds synthetic rasters
  from AIA data. Also contains `SimpleCache` and `FileCache`.
- `cli`: argument parsing and output display.
- `eis`, `aia.py`: functions to handle native EIS and AIA data, filenames,
  and data queries. This does not take care of transformed data such as
  `AIARasterGenerator`.
- `files`: manage local filenames (ie. those in `io/`); canonical EIS or AIA
  filenames are handled in `eis.py` or `aia.py`.
- `idl`: run IDL or SSW code from Python, load and format data returned by
  IDL. Contains `IDLFunction`, `SSWFunction` and `IDLStructure`.
- `num`: tools that extend numpy or scipy.
- `plots`: help generate plots at step 4.
- `sun`: generic solar computations.

## License

This package is released under a MIT open source licence. See `LICENSE.txt`.


