# sealev
Allows to access various Sea Level Databases via python.
## Installation
To install the package use the command:
```
pip install sealev
```
After the installation, it is possible to use the package in python:
```
python
```
## List of available databases: getDB()
Once you are in python environment you can give the following collamnds
```
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
#
# get the list of available database sources:
dbs=sl.getDBs()
#
for db in dbs:
print(db)
```
You will get a list of all the database that you can query.
# LIst the devices of a database: getDevs(\<database\>)
You can select one specific database, i.e. DART, and requst the list of available devices:
```
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
darts=sl.getDevs('DART')
#
for dart in darts:
print(dart['id'],dart['location'],format(dart['lat'])+'/'+format(dart['lon']))
#
```
The response will be:
```
21413 Station 21413 - SOUTHEAST TOKYO - 700NM ESE of Tokyo, JP 30.492/152.085
21414 Station 21414 - AMCHITKA - 170 NM South of Amchitka, AK 48.97/178.165
21415 Station 21415 - ATTU - 175 NM South of Attu, AK 50.12/171.867
21416 Station 21416 - KAMCHATKA PENINSULA - 240NM SE of Kamchatka Peninsula, RU 48.12/163.43
21418 Station 21418 - NORTHEAST TOKYO - 450 NM NE of Tokyo, JP 38.73/148.8
...
56003 Station 56003 - Indian Ocean 2 - 630km NNE of Dampier -15.019/118.073
```
The response if a list of devices; each device is a dictionary composed of:
- id identifier of the device (will be used to retrieve data)
- location place of the device
- country country of the device
- lat/lon coordinates of the device
- [group] if it exists it represents a subclass of the database
the keyword 'id' contains the reference identifier to retrieve the level data.
## Retrieve sea level of a device: getLevel(\<database\>,\<device\>, \[\<tmin\>\],\[\<tmax\>\])
Suppose you want to retrieve the level values of one specific device, such as 21414 (Station 21414 - AMCHITKA - 170 NM South of Amchitka), you can give the following command:
```
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
values=sl.getLevel('DART','21414')
for j in range(len(values['x'])):
print(values['x'][j],values['y'][j])
```
The response of the example above is a list of data if the device has recent recorded data:
```
2024-10-02 00:00:00 5442.868
2024-10-02 00:15:00 5442.874
2024-10-02 00:30:00 5442.882
2024-10-02 00:45:00 5442.891
2024-10-02 01:00:00 5442.897
...
```
You can retrieve data from the past adding the keyword tmin, tmax in the getLevel call. Example
```
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
values=sl.getLevel('GLOSS @vliz','mnza','2022-09-19 00:00:00','2022-09-21 00:00:00')
for j in range(len(values['x'])):
print(values['x'][j],values['y'][j])
```
The example above retrieves and print the data related to the Tsunami event in Mexico.
The response is a dctionary containing the following keys:
- x (list) containing a series of datatime values representing the time of the level
- y (list) containing a series of sea level values of the device (m)
each point of the x list will have a corresponding point in y
In the example above, if you have setup the matplotlib package (pip install matplotlib), you can plot the quantities with the commands:
```
import matplotlib.pyplot as plt
plt.plot(values['x'],values['y'])
plt.xlabel('Date/Time')
plt.ylabel('Level (m)')
plt.title('M7.6 MEXICO, 2022-09-19 18:05:00')
plt.show()
```
The following plot would be generated:
As another example, let's show the Hurricane Helene 2024 at Clearwater Beach (USA)
```
from sealev.sldb import seaLevelDB
import matplotlib.pyplot as plt
sl=seaLevelDB()
values=sl.getLevel('GLOSS @vliz','cwfl','2024-09-24 00:00:00','2024-09-29 00:00:00')
plt.plot(values['x'],values['y'])
plt.xlabel('Date/Time')
plt.ylabel('Level (m)')
plt.title('Clearwater Beach (FL), Cyclone Helene-24')
plt.show()
```
the output will be:
## Export to csv file: to_csv(values,fnameout)
After having retrieved the values dictionary, you can export in a csv file. Example
```
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
values=sl.getLevel('GLOSS @vliz','mnza','2022-09-19 00:00:00','2022-09-21 00:00:00')
sl.to_csv(values,'output.csv')
```
## Extract other quantities
In some cases (i.e. JRC_TAD database), many other quantities are retrieved from the database in addition to the level. In these cases the available keys are many more thabn x and y, that however always eist. The other quantities can also be retrieved.
The xample below collects the data of Cadiz (IDSL-06) from the JRC database and creates a plot of the battery voltage.
```
import matplotlib.pyplot as plt
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
#
values=sl.getLevel('JRC_TAD','IDSL-06','2024-10-03 00:00:00','2024-10-08 00:00:00')
print('List of possible quantities to plot:',values.keys())
plt.plot(values['x'],values['anag3'])
plt.xlabel('Date/Time')
plt.ylabel('Battery voltage (volt)')
plt.title('Cadiz device IDSL-06')
plt.show()
```
The output plot is the folllowing:
## Search a sea level station: search(\<db\>,\<keyword\>)
To search a device using the name or the id as keyword use the search command:
```
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
details=sl.search('NOAA TC','Clearwater')
print('detail=',detail)
```
the reply will be:
```
detail= [{'location': 'Clearwater Beach', 'id': '8726724', 'lat': 27.978333, 'lon': -82.831667, 'country': '', 'group': ''}]
```
## plot a device using id: plot(\<db\>,\<devID\>,\[\<tmin\>\],\[\<tmax\>\])
This command will perform the plot as shown above.
```
from sealev.sldb import seaLevelDB
sl=seaLevelDB()
details=sl.search('NOAA TC','Clearwater')
id=details[0]['id']
sl.plot('NOAA TC',id,'2024-10-05 00:00:00','2024-10-11 00:00:00')
```
Raw data
{
"_id": null,
"home_page": null,
"name": "sealev",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python, first package",
"author": "Alessandro Annunziato",
"author_email": "alessandro.annunziato@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ca/4d/35265188433e14923eabe54e058f2c008c5b69afd8c009e4360bdf908730/sealev-0.0.19.tar.gz",
"platform": null,
"description": "# sealev\r\nAllows to access various Sea Level Databases via python.\r\n## Installation\r\nTo install the package use the command: \r\n```\r\npip install sealev\r\n```\r\nAfter the installation, it is possible to use the package in python:\r\n```\r\npython\r\n```\r\n## List of available databases: getDB()\r\nOnce you are in python environment you can give the following collamnds\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\n#\r\n# get the list of available database sources:\r\ndbs=sl.getDBs()\r\n#\r\nfor db in dbs:\r\n print(db)\r\n```\r\nYou will get a list of all the database that you can query.\r\n# LIst the devices of a database: getDevs(\\<database\\>)\r\n\r\nYou can select one specific database, i.e. DART, and requst the list of available devices:\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\ndarts=sl.getDevs('DART')\r\n#\r\nfor dart in darts:\r\n print(dart['id'],dart['location'],format(dart['lat'])+'/'+format(dart['lon']))\r\n#\r\n```\r\nThe response will be:\r\n```\r\n21413 Station 21413 - SOUTHEAST TOKYO - 700NM ESE of Tokyo, JP 30.492/152.085\r\n21414 Station 21414 - AMCHITKA - 170 NM South of Amchitka, AK 48.97/178.165\r\n21415 Station 21415 - ATTU - 175 NM South of Attu, AK 50.12/171.867\r\n21416 Station 21416 - KAMCHATKA PENINSULA - 240NM SE of Kamchatka Peninsula, RU 48.12/163.43\r\n21418 Station 21418 - NORTHEAST TOKYO - 450 NM NE of Tokyo, JP 38.73/148.8\r\n...\r\n56003 Station 56003 - Indian Ocean 2 - 630km NNE of Dampier -15.019/118.073\r\n\r\n```\r\n\r\nThe response if a list of devices; each device is a dictionary composed of:\r\n- id identifier of the device (will be used to retrieve data)\r\n- location place of the device\r\n- country country of the device\r\n- lat/lon coordinates of the device\r\n- [group] if it exists it represents a subclass of the database\r\n\r\nthe keyword 'id' contains the reference identifier to retrieve the level data.\r\n## Retrieve sea level of a device: getLevel(\\<database\\>,\\<device\\>, \\[\\<tmin\\>\\],\\[\\<tmax\\>\\])\r\nSuppose you want to retrieve the level values of one specific device, such as 21414 (Station 21414 - AMCHITKA - 170 NM South of Amchitka), you can give the following command:\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\nvalues=sl.getLevel('DART','21414')\r\nfor j in range(len(values['x'])):\r\n print(values['x'][j],values['y'][j])\r\n```\r\nThe response of the example above is a list of data if the device has recent recorded data:\r\n```\r\n2024-10-02 00:00:00 5442.868\r\n2024-10-02 00:15:00 5442.874\r\n2024-10-02 00:30:00 5442.882\r\n2024-10-02 00:45:00 5442.891\r\n2024-10-02 01:00:00 5442.897\r\n...\r\n```\r\nYou can retrieve data from the past adding the keyword tmin, tmax in the getLevel call. Example\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\nvalues=sl.getLevel('GLOSS @vliz','mnza','2022-09-19 00:00:00','2022-09-21 00:00:00')\r\nfor j in range(len(values['x'])):\r\n print(values['x'][j],values['y'][j])\r\n```\r\nThe example above retrieves and print the data related to the Tsunami event in Mexico.\r\n\r\n\r\nThe response is a dctionary containing the following keys:\r\n- x (list) containing a series of datatime values representing the time of the level\r\n- y (list) containing a series of sea level values of the device (m)\r\neach point of the x list will have a corresponding point in y\r\nIn the example above, if you have setup the matplotlib package (pip install matplotlib), you can plot the quantities with the commands:\r\n \r\n```\r\nimport matplotlib.pyplot as plt\r\nplt.plot(values['x'],values['y'])\r\nplt.xlabel('Date/Time')\r\nplt.ylabel('Level (m)')\r\nplt.title('M7.6 MEXICO, 2022-09-19 18:05:00')\r\nplt.show()\r\n```\r\nThe following plot would be generated:\r\n\r\n\r\nAs another example, let's show the Hurricane Helene 2024 at Clearwater Beach (USA)\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nimport matplotlib.pyplot as plt\r\n\r\nsl=seaLevelDB()\r\nvalues=sl.getLevel('GLOSS @vliz','cwfl','2024-09-24 00:00:00','2024-09-29 00:00:00')\r\n\r\nplt.plot(values['x'],values['y'])\r\nplt.xlabel('Date/Time')\r\nplt.ylabel('Level (m)')\r\nplt.title('Clearwater Beach (FL), Cyclone Helene-24')\r\nplt.show()\r\n```\r\nthe output will be:\r\n\r\n\r\n## Export to csv file: to_csv(values,fnameout)\r\nAfter having retrieved the values dictionary, you can export in a csv file. Example\r\n\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\nvalues=sl.getLevel('GLOSS @vliz','mnza','2022-09-19 00:00:00','2022-09-21 00:00:00')\r\nsl.to_csv(values,'output.csv')\r\n```\r\n\r\n## Extract other quantities\r\nIn some cases (i.e. JRC_TAD database), many other quantities are retrieved from the database in addition to the level. In these cases the available keys are many more thabn x and y, that however always eist. The other quantities can also be retrieved.\r\nThe xample below collects the data of Cadiz (IDSL-06) from the JRC database and creates a plot of the battery voltage.\r\n```\r\nimport matplotlib.pyplot as plt\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\n#\r\nvalues=sl.getLevel('JRC_TAD','IDSL-06','2024-10-03 00:00:00','2024-10-08 00:00:00')\r\nprint('List of possible quantities to plot:',values.keys())\r\nplt.plot(values['x'],values['anag3'])\r\nplt.xlabel('Date/Time')\r\nplt.ylabel('Battery voltage (volt)')\r\nplt.title('Cadiz device IDSL-06')\r\nplt.show()\r\n```\r\nThe output plot is the folllowing:\r\n\r\n\r\n## Search a sea level station: search(\\<db\\>,\\<keyword\\>)\r\nTo search a device using the name or the id as keyword use the search command:\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\ndetails=sl.search('NOAA TC','Clearwater')\r\nprint('detail=',detail)\r\n```\r\nthe reply will be:\r\n```\r\ndetail= [{'location': 'Clearwater Beach', 'id': '8726724', 'lat': 27.978333, 'lon': -82.831667, 'country': '', 'group': ''}]\r\n```\r\n\r\n## plot a device using id: plot(\\<db\\>,\\<devID\\>,\\[\\<tmin\\>\\],\\[\\<tmax\\>\\])\r\nThis command will perform the plot as shown above.\r\n```\r\nfrom sealev.sldb import seaLevelDB\r\nsl=seaLevelDB()\r\ndetails=sl.search('NOAA TC','Clearwater')\r\nid=details[0]['id']\r\nsl.plot('NOAA TC',id,'2024-10-05 00:00:00','2024-10-11 00:00:00')\r\n```\r\n\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Se Level DBs",
"version": "0.0.19",
"project_urls": null,
"split_keywords": [
"python",
" first package"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "845572f8f161c5076bc31f0c38861a81b92868ce077afa65fb58d1abeb0d3556",
"md5": "d137ee683ff1b9647b95e37fa161ec36",
"sha256": "cc20433c6924de9b0d6d71217f72761cf881dd21799bda3f74470bfe19cff622"
},
"downloads": -1,
"filename": "sealev-0.0.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d137ee683ff1b9647b95e37fa161ec36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20243,
"upload_time": "2024-10-10T06:29:33",
"upload_time_iso_8601": "2024-10-10T06:29:33.048132Z",
"url": "https://files.pythonhosted.org/packages/84/55/72f8f161c5076bc31f0c38861a81b92868ce077afa65fb58d1abeb0d3556/sealev-0.0.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ca4d35265188433e14923eabe54e058f2c008c5b69afd8c009e4360bdf908730",
"md5": "bbb7188d2504e7c485146729a2f1cda9",
"sha256": "178cc92a81104c557860b25dc31d0e22f69318237123ea0db51be880118163e9"
},
"downloads": -1,
"filename": "sealev-0.0.19.tar.gz",
"has_sig": false,
"md5_digest": "bbb7188d2504e7c485146729a2f1cda9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22186,
"upload_time": "2024-10-10T06:29:35",
"upload_time_iso_8601": "2024-10-10T06:29:35.719946Z",
"url": "https://files.pythonhosted.org/packages/ca/4d/35265188433e14923eabe54e058f2c008c5b69afd8c009e4360bdf908730/sealev-0.0.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 06:29:35",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sealev"
}
JSON