https://github.com/aburrell/pyintensityfeatures
Identify features, such as auroral luminosity boundaries, in imager data
https://github.com/aburrell/pyintensityfeatures
Last synced: 4 months ago
JSON representation
Identify features, such as auroral luminosity boundaries, in imager data
- Host: GitHub
- URL: https://github.com/aburrell/pyintensityfeatures
- Owner: aburrell
- License: other
- Created: 2025-03-25T20:34:41.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-28T14:36:03.000Z (about 1 year ago)
- Last Synced: 2025-09-23T13:55:35.858Z (9 months ago)
- Language: Python
- Size: 1.33 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](http://pyIntensityFeatures.readthedocs.io/en/latest/?badge=latest)
[DOI]
[PyPI version]
[](https://github.com/aburrell/pyIntensityFeatures/actions/workflows/main.yml)
[](https://coveralls.io/github/aburrell/pyIntensityFeatures?branch=main)
Overview
pyIntensityFeatures is a Python module that identifies features in imager
intensity data. It currently supports the identification of the Auroral
Luminosity Boundaries (ALBs). This package is designed to be data source
agnostic and uses a fitting method based on Longden et al. (2009) to identify
the poleward and equatorward ALBs. Current support focuses on satellite-based
imagers.
# Dependencies
The required dependecies encompass:
* aacgmv2
* numpy
* pandas
* scipy
* xarray
Optional dependencies include:
* apexpy
Testing is performed using the python module, unittest.
# Installation
Installation is now available through pypi
```
$ pip install pyIntensityFeatures
```
You may also checkout the repository and install it yourself:
```
$ git clone git://github.com/aburrell/pyIntensityFeatures.git;
```
Change directories into the repository folder and build the wheel.
```
$ cd pyIntensityFeatures/
$ python -m build .
$ pip install .
```
To run the unit tests,
```
$ python -m unittest discover
```
# Example
This example uses pysatNASA to obtain GUVI sdr-imaging data. You can use this
as a template to create the necessary supporting functions to identify ALBs
in your own data set. In iPython, run:
```
import datetime as dt
import pyIntensityFeatures
import pysat
from pysatNASA.instruments import timed_guvi
```
Obtain the data from which you want to get boundaries.
```
stime = dt.datetime(2005, 1, 1)
guvi = pysat.Instrument(inst_module=timed_guvi, tag='sdr-imaging',
inst_id='high_res')
guvi.download(start=stime)
```
We need to create a cleaning function to select only good intensity data using
the supplied DQI flag. Because GUVI images the ionosphere at several
wavelenghts and the satellite slice-detection function expects a 2D array for
intensity, we also need to create a function that will add a single-channel
intensity variable to the pysat GUVI Instrument.
```
def create_channel_intensity(guvi, channel='LBHlong'):
"""Create a new variable for the single-channel auroral intensity.
Parameters
----------
guvi : pysat.Instrument
pysat Instrument for the GUVI data.
channel : str
Desired channel name. (defualt='LBHlong')
"""
int_var = 'DISK_RECTIFIED_INTENSITY_DAY_AURORAL'
chan_var = 'nchan'
# Get the channel index
ichan = list(guvi[chan_var].values).index(channel)
# Create the new intensity variable
new_var = int_var.replace('DISK_RECTIFIED', channel)
guvi[new_var] = guvi[int_var][:, :, ichan]
return
def clean_guvi(guvi, int_var):
"""Get a mask for clean GUVI auroral intensity.
Parameters
----------
guvi : pysat.Instrument
pysat Instrument for the GUVI data.
int_var : str
Intensity variable name
Returns
-------
clean_mask : array-like
2D array with a mask denoting the good data by the DQI auroral flag.
"""
flag_var = 'DQI_DAY_AURORAL'
# Get the clean mask from the flag
clean_mask = np.full(shape=guvi[int_var].values.shape, fill_value=False)
clean_mask = guvi[flag_var].values <= 0
# The pyIntensityFeatures.instruments.satellites function requires time as
# the first dimension
return clean_mask.transpose()
```
pysat allows methods that update or alter the instrument to be run when loading
the data. Attach the `create_channel_intensity` function and load the
desired day.
```
guvi.custom_attach(create_channel_intensity, kwargs={'channel': 'LBHlong'})
guvi.load(date=stime)
```
Then initialise an AuroralBounds class object. The `transpose` kwarg is set
to `True` to reshape the GUVI longitude, latitude, and intensity data such that
the time dimension is first.
```
ckwargs = {'int_var': 'LBHlong_INTENSITY_DAY_AURORAL'}
guvi_alb = pyIntensityFeatures.AuroralBounds(guvi, 'time_auroral',
'PIERCEPOINT_DAY_LONGITUDE_AURORAL',
'PIERCEPOINT_DAY_LATITUDE_AURORAL',
'LBHlong_INTENSITY_DAY_AURORAL',
110.0, hemisphere=1,
opt_coords={'channel': 'LBHlong'},
transpose=True,
clean_func=clean_guvi,
clean_kwargs=ckwargs)
print(guvi_alb)
```
The output should be as follows, with the start and end times set to reflect
the times at which data was provided:
```
Auroral Boundary object
=======================
Instrument Data: pysat Instrument object
-----------------------
Platform: 'timed'
Name: 'guvi'
Tag: 'sdr-imaging'
Instrument id: 'high_res'
Data Processing
---------------
Cleaning Level: 'clean'
Data Padding: None
Custom Functions: 1 applied
0:
: Kwargs={'channel': 'LBHlong'}
Local File Statistics
---------------------
Number of files: 711
Date Range: 01 January 2005 --- 01 March 2005
Loaded Data Statistics
----------------------
Date: 01 January 2005
DOY: 001
Time range: 01 January 2005 00:12:38 --- 01 January 2005 23:59:59
Number of Times: 23989
Number of variables: 70
Variable Names:
ORBIT_DAY LATITUDE_DAY LONGITUDE_DAY
...
nCross nCrossDayAur LBHlong_INTENSITY_DAY_AURORAL
pysat Meta object
-----------------
Tracking 8 metadata values
Metadata for 90 standard variables
Metadata for 40 global attributes
Data Variables
--------------
Time: time_auroral
Geo Lon: PIERCEPOINT_DAY_LONGITUDE_AURORAL
Geo Lat: PIERCEPOINT_DAY_LATITUDE_AURORAL
Intensity: LBHlong_INTENSITY_DAY_AURORAL
Transpose: {'PIERCEPOINT_DAY_LONGITUDE_AURORAL': True,
'PIERCEPOINT_DAY_LATITUDE_AURORAL': True,
'LBHlong_INTENSITY_DAY_AURORAL': True}
Coordinate Attributes
---------------------
Hemisphere: 1
Altitude: 110.00 km
Optional coords: {'channel': 'LBHlong', 'hemisphere': 1}
Start time: 2005-01-01T00:12:38.575362000
End time: 2005-01-01T23:59:59.722748000
Instrument Functions
--------------------
Slicing: functools.partial(, transpose=True)
Cleaning: functools.partial(,
int_var='LBHlong_INTENSITY_DAY_AURORAL')
```
Now, get the ALBs for the loaded data using the method defaults. This will
update the `boundaries` attribute from `None` to a filled or empty xarray
Dataset. We will update the end time to be shorter than the amount of loaded
data to limit the processing time.
```
guvi_alb.etime = dt.datetime(2005, 1, 1, 0, 25)
guvi_alb.set_boundaries()
print(guvi_alb.boundaries)
```
This will yield one slice of intensity data in the Northern hemisphere with
ALBs:
```
Dimensions: (sweep_start: 1, mlt: 48, coeff: 12, lat: 31, sweep_end: 1)
Coordinates:
* sweep_start (sweep_start) datetime64[ns] 2005-01-01T00:24:35.572131
* sweep_end (sweep_end) datetime64[ns] 2005-01-01T00:49:11.295639
* mlt (mlt) float64 0.25 0.75 1.25 1.75 ... 22.75 23.25 23.75
channel