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,52 +23,166 @@ 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
**Arguments**:
- `wdc_filename` _str_ - Filename of wdc data from
http://wdc.kugi.kyoto-u.ac.jp/
Returns:
dict: {
**Returns**:
- `dict` - {
Auroral indeces 'AL', 'AE', 'AO', 'AU' (int): {
'times' (datetime.datetime): List of datetime objects
- `'times'` _datetime.datetime_ - List of datetime objects
corresponding to time in UT.
'values' (int): List of indeces.
- `'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**:
- `wdc_filename` _str_ - Relative filename (or file handle no.) to read.
**Returns**:
Returns:
dict: of values.
{'[ASY-SYM]-[D-H]': 'times': [], 'values': []}
- `dict` - of values.
- `{'[ASY-SYM]-[D-H]'` - 'times': [], 'values': []}
**Examples**:
Examples:
```python
indeces = swmfpy.io.read_wdc_asy_sym('wdc.dat')
......@@ -81,76 +195,91 @@ Examples:
```
Important to note if there is bad data it will be filled as None.
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.
**Arguments**:
- `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
- `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
- `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
- `clean` _bool_ - default=True, Clean the omni data of bad data points
**Returns**:
Returns:
pandas.DataFrame: object with solar wind data
- `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.
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.
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**:
- `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)
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.
**Arguments**:
- `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
- `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
- `index_time` _bool_ - (default: True) Make a column of dt.datetime objects
in dictionary key 'Time [UT]'.
Returns:
**Returns**:
Dictionary of the log file
Examples:
**Examples**:
To plot AL and Dst get the log files
```python
......@@ -162,160 +291,96 @@ Examples:
```
<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', ...]}
**Arguments**:
- `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.
- `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:
**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:
**Raises**:
- `TypeError` - If a value given couldn't be converted to string.
**Examples**:
```python
change['#SOLARWINDFILE'] = [['T', 'UseSolarWindFile'],
change['`SOLARWINDFILE`'] = [['T', 'UseSolarWindFile'],
['new_imf.dat', 'NameSolarWindFile']]
# This will overwrite PARAM.in
swmfpy.paramin.replace('PARAM.in.template', change)
```
<a name=".swmfpy.paramin.read_command"></a>
#### read\_command
## 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.
This will find the `COMMAND` and return a list of values for the parameters.
**Arguments**:
Args:
command (str): This is the [`COMMAND`](#COMMAND) you're looking for.
paramin_file (str): (default: 'PARAM.in') The file in which you're
- `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
- `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...)
Raises:
ValueError: When the [`COMMAND`](#COMMAND) is not found.
Examples:
```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])
```
**Returns**:
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.
- `list` - Values found for the `COMMAND` in file. Index 0 is `COMMAND` and
the values follow (1 for first argument...)
# swmfpy.web
Tools to retrieve and send data on the web.
**Raises**:
Here are a collection of tools to work with data on the internet. Thus,
this module mostly requires an internet connection.
- `ValueError` - When the `COMMAND` is not found.
## get_omni_data
```python
get_omni_data(time_from, time_to, **kwargs)
```
Retrieve omni solar wind data over http.
**Examples**:
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().
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.
Returns:
dict: This will be a list of *all* columns
available in the omni data set.
Examples:
```python
import datetime
import swmfpy.web
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])
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)
```
## 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
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/')
```
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
......
Supports Markdown
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