Note: The default ITS GitLab runner is a shared resource and is subject to slowdowns during heavy usage.
You can run your own GitLab runner that is dedicated just to your group if you need to avoid processing delays.

Commit b5a80a14 authored by Qusai Al Shidi's avatar Qusai Al Shidi
Browse files

Hopefully this works for docs

parent b5760f32
# swmfpy
<a name=".swmfpy"></a>
## swmfpy
SWMF Tools
==========
......@@ -23,299 +23,364 @@ These are not automatically imported. Might have extra dependancies.
*None yet.*
<a name=".swmfpy.web"></a>
## swmfpy.web
Tools to retrieve and send data on the web.
Here are a collection of tools to work with data on the internet. Thus,
this module mostly requires an internet connection.
<a name=".swmfpy.web.get_omni_data"></a>
#### get\_omni\_data
```python
get_omni_data(time_from, time_to, **kwargs)
```
Retrieve omni solar wind data over http.
This will download omni data from https://spdf.gsfc.nasa.gov/pub/data/omni
and put it into a dictionary. If your data is large, then make a csv and
use swmfpy.io.read_omni_data().
**Arguments**:
- `time_from` _datetime.datetime_ - The start time of the solar wind
data that you want to receive.
- `time_to` _datetime.datetime_ - The end time of the solar wind data
you want to receive.
**Returns**:
- `dict` - This will be a list of *all* columns
available in the omni data set.
**Examples**:
```python
import datetime
import swmfpy.web
storm_start = datetime.datetime(year=2000, month=1, day=1)
storm_end = datetime.datetime(year=2000, month=2, day=15)
data = swmfpy.web.get_omni_data(time_from=storm_start,
time_to=storm_end)
```
<a name=".swmfpy.web.download_magnetogram_adapt"></a>
#### download\_magnetogram\_adapt
```python
download_magnetogram_adapt(time, map_type='fixed', **kwargs)
```
This routine downloads GONG ADAPT magnetograms.
Downloads ADAPT magnetograms from ftp://gong2.nso.edu/adapt/maps/gong/
to a local directory. It will download all maps with the regex file
pattern: adapt4[0,1]3*yyyymmddhh
**Arguments**:
- `time` _datetime.datetime_ - Time in which you want the magnetogram.
- `map_type` _str_ - (default: 'fixed')
Choose either 'fixed' or 'central' for
the map type you want.
**kwargs:
- `download_dir` _str_ - (default is current dir) Relative directory
where you want the maps to be downloaded.
**Returns**:
- `str` - First unzipped filename found.
**Raises**:
- `NotADirectoryError` - If the adapt maps directory
is not found on the server.
- `ValueError` - If map_type is not recognized.
(i.e. not 'fixed' or 'central')
- `FileNotFoundError` - If maps were not found.
**Examples**:
```python
import datetime as dt
# Use datetime objects for the time
time_flare = dt.datetime(2018, 2, 12, hour=10)
swmfpy.web.download_magnetogram_adapt(time=time_flare,
map_type='central',
download_dir='./mymaps/')
```
<a name=".swmfpy.io"></a>
## swmfpy.io
# swmfpy.io
Input/Output tools
Here are tools to read and write files relating to SWMF.
TODO: Move pandas dependancy elsewhere.
<a name=".swmfpy.io.read_wdc_ae"></a>
#### read\_wdc\_ae
## read_wdc_ae
```python
read_wdc_ae(wdc_filename)
```
Read an auroral electrojet (AE) indeces from Kyoto's World Data Center
text file into a dictionary of lists.
Args:
wdc_filename (str): Filename of wdc data from
http://wdc.kugi.kyoto-u.ac.jp/
Returns:
dict: {
Auroral indeces 'AL', 'AE', 'AO', 'AU' (int): {
'times' (datetime.datetime): List of datetime objects
corresponding to time in UT.
'values' (int): List of indeces.
}
**Arguments**:
- `wdc_filename` _str_ - Filename of wdc data from
http://wdc.kugi.kyoto-u.ac.jp/
**Returns**:
- `dict` - {
Auroral indeces 'AL', 'AE', 'AO', 'AU' (int): {
- `'times'` _datetime.datetime_ - List of datetime objects
corresponding to time in UT.
- `'values'` _int_ - List of indeces.
}
<a name=".swmfpy.io.read_wdc_asy_sym"></a>
#### read\_wdc\_asy\_sym
## read_wdc_asy_sym
```python
read_wdc_asy_sym(wdc_filename)
```
Reads a WDC file for ASY/SYM data.
Reads an ASY/SYM file downloaded from
http://wdc.kugi.kyoto-u.ac.jp/aeasy/index.html
and puts it into a dictionary.
Args:
wdc_filename (str): Relative filename (or file handle no.) to read.
**Arguments**:
Returns:
dict: of values.
{'[ASY-SYM]-[D-H]': 'times': [], 'values': []}
- `wdc_filename` _str_ - Relative filename (or file handle no.) to read.
Examples:
```python
**Returns**:
indeces = swmfpy.io.read_wdc_asy_sym('wdc.dat')
# Plot data
plt.plot(indeces['SYM-H']['times'],
indeces['SYM-H']['values'],
label='SYM-H [nT]'
)
plt.xlabel('Time [UT]')
- `dict` - of values.
- `{'[ASY-SYM]-[D-H]'` - 'times': [], 'values': []}
```
**Examples**:
Important to note if there is bad data it will be filled as None.
```python
indeces = swmfpy.io.read_wdc_asy_sym('wdc.dat')
# Plot data
plt.plot(indeces['SYM-H']['times'],
indeces['SYM-H']['values'],
label='SYM-H [nT]'
)
plt.xlabel('Time [UT]')
```
Important to note if there is bad data it will be filled as None.
<a name=".swmfpy.io.read_omni_csv"></a>
#### read\_omni\_csv
## read_omni_csv
```python
read_omni_csv(filename, filtering=False, **kwargs)
```
Take an OMNI csv file from cdaweb.sci.gsfc.nasa.gov
and turn it into a pandas.DataFrame.
Args:
fnames (dict): dict with filenames from omni .lst files.
The keys must be: density, temperature,
magnetic_field, velocity
filtering (bool): default=False Remove points where the value
is >sigma (default: sigma=3) from mean.
**kwargs:
coarseness (int): default=3, Number of standard deviations
above which to remove if filtering=True.
clean (bool): default=True, Clean the omni data of bad data points
**Arguments**:
Returns:
pandas.DataFrame: object with solar wind data
- `fnames` _dict_ - dict with filenames from omni .lst files.
The keys must be: density, temperature,
magnetic_field, velocity
- `filtering` _bool_ - default=False Remove points where the value
is >sigma (default: sigma=3) from mean.
**kwargs:
- `coarseness` _int_ - default=3, Number of standard deviations
above which to remove if filtering=True.
- `clean` _bool_ - default=True, Clean the omni data of bad data points
Make sure to download the csv files with cdaweb.sci.gsfc.nasa.gov
the header seperated into a json file for safety.
**Returns**:
This only tested with OMNI data specifically.
- `pandas.DataFrame` - object with solar wind data
Make sure to download the csv files with cdaweb.sci.gsfc.nasa.gov
the header seperated into a json file for safety.
This only tested with OMNI data specifically.
<a name=".swmfpy.io.write_imf_input"></a>
#### write\_imf\_input
## write_imf_input
```python
write_imf_input(data, outfilename='IMF.dat', enable_rb=True, **kwargs)
write_imf_input(data, outfilename="IMF.dat", enable_rb=True, **kwargs)
```
Writes the pandas.DataFrame into an input file
that SWMF can read as input IMF (IMF.dat).
Args:
data: pandas.DataFrame object with solar wind data
outfilename: The output file name for ballistic solar wind data.
(default: "IMF.dat")
enable_rb: Enables solar wind input for the radiation belt model.
(default: True)
**Arguments**:
Other paramaters:
gse: (default=False)
Use GSE coordinate system for the file instead of GSM default.
- `data` - pandas.DataFrame object with solar wind data
- `outfilename` - The output file name for ballistic solar wind data.
- `(default` - "IMF.dat")
- `enable_rb` - Enables solar wind input for the radiation belt model.
- `(default` - True)
Other paramaters:
- `gse` - (default=False)
Use GSE coordinate system for the file instead of GSM default.
<a name=".swmfpy.io.read_gm_log"></a>
#### read\_gm\_log
## read_gm_log
```python
read_gm_log(filename, colnames=None, dtypes=None, index_time=True)
```
Make a dictionary out of the indeces outputted
from the GM model log.
Args:
filename (str): The relative filename as a string. (or file handle no.)
colnames ([str]): (default: None) Supply the name of the columns.
If None it will use second line
of log file.
dtypes ([types]): (default: None) Provide types for the columns, if
None then all will be float.
index_time (bool): (default: True) Make a column of dt.datetime objects
in dictionary key 'Time [UT]'.
**Arguments**:
Returns:
Dictionary of the log file
- `filename` _str_ - The relative filename as a string. (or file handle no.)
- `colnames` _[str]_ - (default: None) Supply the name of the columns.
If None it will use second line
of log file.
- `dtypes` _[types]_ - (default: None) Provide types for the columns, if
None then all will be float.
- `index_time` _bool_ - (default: True) Make a column of dt.datetime objects
in dictionary key 'Time [UT]'.
Examples:
To plot AL and Dst get the log files
```python
**Returns**:
geo = swmfpy.io.read_gm_log('run/GM/IO2/geoindex_e20140215-100500.log')
dst = swmfpy.io.read_gm_log('run/GM/IO2/log_e20140215-100500.log')
Dictionary of the log file
# Plot AL indeces
plt.plot(geo['times', geo['AL'])
**Examples**:
```
To plot AL and Dst get the log files
```python
geo = swmfpy.io.read_gm_log('run/GM/IO2/geoindex_e20140215-100500.log')
dst = swmfpy.io.read_gm_log('run/GM/IO2/log_e20140215-100500.log')
# Plot AL indeces
plt.plot(geo['times', geo['AL'])
```
<a name=".swmfpy.paramin"></a>
## swmfpy.paramin
# swmfpy.paramin
These tools are to help script the editing of PARAM.in files.
<a name=".swmfpy.paramin.replace_command"></a>
#### replace\_command
## replace_command
```python
replace_command(parameters, input_file, output_file='PARAM.in')
```
Replace values for the parameters in a PARAM.in file.
Note, if you have repeat commands this will replace all the repeats.
Args:
parameters (dict): Dictionary of strs with format
replace = {'#COMMAND': ['value', 'comments', ...]}
This is case sensitive.
input_file (str): String of PARAM.in file name.
output_file (str): (default 'PARAM.in') The output file to write to.
A value of None will not output a file.
Returns:
A list of lines of the PARAM.in file that would be outputted.
Raises:
TypeError: If a value given couldn't be converted to string.
Examples:
```python
change['#SOLARWINDFILE'] = [['T', 'UseSolarWindFile'],
['new_imf.dat', 'NameSolarWindFile']]
# This will overwrite PARAM.in
swmfpy.paramin.replace('PARAM.in.template', change)
```
## read_command
```python
read_command(command, paramin_file='PARAM.in', **kwargs)
```
Get parameters of a certain command in PARAM.in file.
This will find the [`COMMAND`](#COMMAND) and return a list of values for the parameters.
Args:
command (str): This is the [`COMMAND`](#COMMAND) you're looking for.
paramin_file (str): (default: 'PARAM.in') The file in which you're
looking for the command values.
**kwargs:
num_of_values (int): (default: None) Number of values to take from
command.
Returns:
list: Values found for the [`COMMAND`](#COMMAND) in file. Index 0 is [`COMMAND`](#COMMAND) and
the values follow (1 for first argument...)
**Arguments**:
Raises:
ValueError: When the [`COMMAND`](#COMMAND) is not found.
- `parameters` _dict_ - Dictionary of strs with format
replace = {'`COMMAND`': ['value', 'comments', ...]}
This is case sensitive.
- `input_file` _str_ - String of PARAM.in file name.
- `output_file` _str_ - (default 'PARAM.in') The output file to write to.
A value of None will not output a file.
Examples:
```python
**Returns**:
start_time = swmfpy.paramin.read_command('#STARTTIME')
end_time = swmfpy.paramin.read_command('#ENDTIME')
print('Starting month is ', start_time[1])
print('Ending month is ', end_time[1])
A list of lines of the PARAM.in file that would be outputted.
```
**Raises**:
This will treat all following lines as values for the command. To suppress
this, try using the `num_of_values` keyword. This is helpful if your
PARAM.in is comment heavy.
- `TypeError` - If a value given couldn't be converted to string.
**Examples**:
# swmfpy.web
Tools to retrieve and send data on the web.
```python
change['`SOLARWINDFILE`'] = [['T', 'UseSolarWindFile'],
['new_imf.dat', 'NameSolarWindFile']]
# This will overwrite PARAM.in
swmfpy.paramin.replace('PARAM.in.template', change)
```
Here are a collection of tools to work with data on the internet. Thus,
this module mostly requires an internet connection.
<a name=".swmfpy.paramin.read_command"></a>
#### read\_command
## get_omni_data
```python
get_omni_data(time_from, time_to, **kwargs)
read_command(command, paramin_file='PARAM.in', **kwargs)
```
Retrieve omni solar wind data over http.
This will download omni data from https://spdf.gsfc.nasa.gov/pub/data/omni
and put it into a dictionary. If your data is large, then make a csv and
use swmfpy.io.read_omni_data().
Get parameters of a certain command in PARAM.in file.
Args:
time_from (datetime.datetime): The start time of the solar wind
data that you want to receive.
time_to (datetime.datetime): The end time of the solar wind data
you want to receive.
This will find the `COMMAND` and return a list of values for the parameters.
Returns:
dict: This will be a list of *all* columns
available in the omni data set.
**Arguments**:
Examples:
```python
- `command` _str_ - This is the `COMMAND` you're looking for.
- `paramin_file` _str_ - (default: 'PARAM.in') The file in which you're
looking for the command values.
**kwargs:
- `num_of_values` _int_ - (default: None) Number of values to take from
command.
import datetime
import swmfpy.web
**Returns**:
storm_start = datetime.datetime(year=2000, month=1, day=1)
storm_end = datetime.datetime(year=2000, month=2, day=15)
data = swmfpy.web.get_omni_data(time_from=storm_start,
time_to=storm_end)
```
- `list` - Values found for the `COMMAND` in file. Index 0 is `COMMAND` and
the values follow (1 for first argument...)
**Raises**:
## download_magnetogram_adapt
```python
download_magnetogram_adapt(time, map_type='fixed', **kwargs)
```
This routine downloads GONG ADAPT magnetograms.
- `ValueError` - When the `COMMAND` is not found.
Downloads ADAPT magnetograms from ftp://gong2.nso.edu/adapt/maps/gong/
to a local directory. It will download all maps with the regex file
pattern: adapt4[0,1]3*yyyymmddhh
**Examples**:
Args:
time (datetime.datetime): Time in which you want the magnetogram.
map_type (str): (default: 'fixed')
Choose either 'fixed' or 'central' for
the map type you want.
**kwargs:
download_dir (str): (default is current dir) Relative directory
where you want the maps to be downloaded.
Returns:
str: First unzipped filename found.
Raises:
NotADirectoryError: If the adapt maps directory
is not found on the server.
ValueError: If map_type is not recognized.
(i.e. not 'fixed' or 'central')
FileNotFoundError: If maps were not found.
Examples:
```python
import datetime as dt
# Use datetime objects for the time
time_flare = dt.datetime(2018, 2, 12, hour=10)
swmfpy.web.download_magnetogram_adapt(time=time_flare,
map_type='central',
download_dir='./mymaps/')
```
```python
start_time = swmfpy.paramin.read_command('`STARTTIME`')
end_time = swmfpy.paramin.read_command('`ENDTIME`')
print('Starting month is ', start_time[1])
print('Ending month is ', end_time[1])
```
This will treat all following lines as values for the command. To suppress
this, try using the `num_of_values` keyword. This is helpful if your
PARAM.in is comment heavy.
"""Executable file to quickly use the tools found in swmfpy.
WIP
"""
if __name__ = "__main__":
pass
......@@ -14,9 +14,11 @@ def read_wdc_ae(wdc_filename):
text file into a dictionary of lists.
Args:
wdc_filename (str): Filename of wdc data from
http://wdc.kugi.kyoto-u.ac.jp/
Returns:
dict: {
Auroral indeces 'AL', 'AE', 'AO', 'AU' (int): {
'times' (datetime.datetime): List of datetime objects
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment