| Name | frontpy JSON |
| Version |
0.1.14
JSON |
| download |
| home_page | None |
| Summary | FrontPy is a Python package designed for the detection and analysis of atmospheric fronts. It uses the Thermal Front Parameter (TFP) method to identify cold and warm fronts. The package also includes visualization capabilities, allowing users to plot the identified fronts over GOES-16 satellite imagery. |
| upload_time | 2024-10-17 18:08:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9.15 |
| license | None |
| keywords |
fronts
tfp
thermal front parameter
meteorology
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FrontPy
FrontPy is a Python package designed for the detection and analysis of atmospheric fronts. It uses the Thermal Front Parameter (TFP) method to identify cold and warm fronts. The package also includes visualization capabilities, allowing users to plot the identified fronts over GOES-16 East satellite imagery.
## Installation of FrontPy
### Step 1: Create a new Conda environment
First, you should create a new environment with the specific version of Python and some necessary dependencies. Run the following command in your terminal or command prompt:
```bash
conda create -n your_environment_name python=3.9.15 gdal=3.3.3 poppler=21.09 -c conda-forge
```
Replace **your_environment_name** with your desired name for the environment. The conda will create an isolated environment with Python 3.9.15 and the gdal and poppler libraries, which are necessary for the functionality of FrontPy. Now, FrontPy will probably run smoothly without any errors.
### Step 2: Activate your new Conda environment
Once the environment is created, activate it using the command:
```bash
conda activate your_environment_name
```
### Step 3: Install FrontPy using pip
Now that you are in an isolated environment, install FrontPy using pip:
```bash
pip install frontpy
```
## Usage
To use FrontPy, follow these steps:
**Step 1: Import the main and plot_results functions from the package**:
```python
from frontpy import main, plot_results
```
**Step 2: Set up the parameters required for downloading the data, calculating the Thermal Front Parameter (TFP), detecting cold and warm fronts, and final visualization**.
The parameters must be provided in a dictionary, like this:
```python
config = {
"start_date": "2024-10-11 12", # Start date and time for the analysis (format: YYYY-MM-DD HH) - string
"end_date": "2024-10-12 12", # End date and time for the analysis (format: YYYY-MM-DD HH) - string
"lat_max": 20, # Maximum latitude for the analysis area (degrees, range: -90 to 90) - float
"lat_min": -60, # Minimum latitude for the analysis area (degrees, range: -90 to 90) - float
"lon_max": -20, # Maximum longitude for the analysis area (degrees, range: -180 to 180) - float
"lon_min": -90, # Minimum longitude for the analysis area (degrees, range: -180 to 180) - float
"model_name": None, # Name of the dataset to be used. (Options available: ERA5, GFS). Leave it unchanged if you want to use your own files - string
"filepath": "path_to_your_netcdf_file", #Path to the local NetCDF file containing both u, v, specific humidity and temperature (required if model_name is None)
"pressure": 850, # [Default: 850] Atmospheric pressure level (hPa) at which front identification is performed - int
"thetaw_thresh": 3.0, # [Default: 3.0] Threshold for the magnitude of the gradient of potential wet-bulb temperature (K/100km) for front identification - float
"vf_thresh": 1.0, # [Default: 1.0] Threshold for wind velocity (m/s) for front classification as cold or warm front - float
"smooth_sigma": 0.5, # [Default: 0.5] Smoothing parameter (sigma) for Gaussian filtering - float
"line_or_area": "area", # Type of representation for the fronts (line or area) - string
"min_points": 4, # [Default: 4] Minimum number of frontal points required for a valid frontal line - int
"min_length": 500.0, # [Default: 500.0] Minimum length (km) for the frontal line to be considered - float
"min_area": 5000.0, # [Default: 5000.0] Minimum area (km²) for the frontal zone to be considered - float
"frame_rate": 3.0, # [Default: 3.0] Frame rate (frames per second) for the generated animation; higher rates result in a faster animation - float
"output_directory_fronts": "path_to_your_chosen_output_directory" # Path to your output directory
}
```
Currently, FrontPy allows you to automatically download ERA5 and GFS data (u, v, temperature, specific humidity) for calculating TFP and identifying fronts. To do this, enter "ERA5" or "GFS" in the **model_name** parameter.
If you want to use your own files, all variables must be contained in one netcdf file. In this case, do not assign any value for the **model_name** parameter. Instead, you must provide the path to the netcdf file in the **filepath** parameter, which should include u, v, specific humidity and temperature.
**Note:** The default values have only been tested for the Southern Hemisphere.
**Step 3: Call the main function**:
The *main* function will return two Pandas dataframes: one for cold fronts and one for warm fronts.
So, you can call the main function like this:
```python
cold_fronts, warm_fronts = main(config)
```
**Step 4: Plot the images and generate an animation**:
Lastly, you can plot the results and generate an animation (GIF) using the **plot_results** function. The images and animation will be saved in your output directory.
```
plot_results(cold_fronts, warm_fronts, config)
```
**Obs**: For now, it is only possible to generate images within the coverage area and the available data period of GOES-16 East.
### Command Line Interface (CLI)
FrontPy also supports command-line execution through the **cli.py** file and the **fronts** function. This allows users to specify the parameters directly from the command line.
To run FrontPy using the CLI, execute the following command in your terminal (without the <>):
```bash
fronts <start_date> <end_date> <lat_max> <lat_min> <lon_max> <lon_min> <line_or_area> <output_directory_fronts> <mode>
```
The above arguments are mandatory and must be provided in string format (in quotes) and in the specified order.
**Mode Argument Explanation:**
- To only **identify and generate the files and dataframes** relative to the TFP field and to cold and warm fronts, type **"identify"** as the `<mode>` argument.
- To only **create the images and animation** based on the files and dataframes that have already been generated, type **"plot"** as the `<mode>` argument.
- To **perform both actions** type **"both"** as the `<mode>` argument.
Optional arguments can also be included using the following prefixes before the values of your choice:
- `--model-name`
- `--filepath`
- `--pressure`
- `--thetaw-thresh`
- `--vf-thresh`
- `--smooth-sigma`
- `--min-points`
- `--min-length`
- `--min-area`
- `--frame-rate`
#### Real example using CLI:
1. Using GFS data to identify and plot the results:
```bash
fronts "2024-10-10 00" "2024-10-11 00" "20" "-60" "-20" "-90" "line" "/output_directory/" "both" --model-name "GFS"
```
2. Using my own data:
```bash
fronts "2024-10-10 00" "2024-10-11 00" "20" "-60" "-20" "-90" "line" "/output_directory/" "both" --filepath "/path_to_my_netcdf_file.nc"
```
## License
This project is licensed under the Apache License 2.0. See the LICENSE file for more details.
Raw data
{
"_id": null,
"home_page": null,
"name": "frontpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.15",
"maintainer_email": null,
"keywords": "fronts, tfp, thermal front parameter, meteorology",
"author": null,
"author_email": "Marcelo Souza <marcelo.rodriso@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/50/08/6098b6650db6fc12c33bca71eff86939607b0a73de422a9b2d8dcf5b3a89/frontpy-0.1.14.tar.gz",
"platform": null,
"description": "# FrontPy\n\nFrontPy is a Python package designed for the detection and analysis of atmospheric fronts. It uses the Thermal Front Parameter (TFP) method to identify cold and warm fronts. The package also includes visualization capabilities, allowing users to plot the identified fronts over GOES-16 East satellite imagery.\n\n## Installation of FrontPy\n\n### Step 1: Create a new Conda environment\n\nFirst, you should create a new environment with the specific version of Python and some necessary dependencies. Run the following command in your terminal or command prompt:\n\n```bash\nconda create -n your_environment_name python=3.9.15 gdal=3.3.3 poppler=21.09 -c conda-forge\n```\n\nReplace **your_environment_name** with your desired name for the environment. The conda will create an isolated environment with Python 3.9.15 and the gdal and poppler libraries, which are necessary for the functionality of FrontPy. Now, FrontPy will probably run smoothly without any errors.\n\n### Step 2: Activate your new Conda environment\n\nOnce the environment is created, activate it using the command:\n\n```bash\nconda activate your_environment_name\n```\n\n### Step 3: Install FrontPy using pip\n\nNow that you are in an isolated environment, install FrontPy using pip:\n\n```bash\npip install frontpy\n```\n\n## Usage\n\nTo use FrontPy, follow these steps:\n\n**Step 1: Import the main and plot_results functions from the package**:\n\n```python\nfrom frontpy import main, plot_results\n```\n\n**Step 2: Set up the parameters required for downloading the data, calculating the Thermal Front Parameter (TFP), detecting cold and warm fronts, and final visualization**. \n\nThe parameters must be provided in a dictionary, like this:\n\n```python\nconfig = {\n \"start_date\": \"2024-10-11 12\", # Start date and time for the analysis (format: YYYY-MM-DD HH) - string\n \"end_date\": \"2024-10-12 12\", # End date and time for the analysis (format: YYYY-MM-DD HH) - string\n \"lat_max\": 20, # Maximum latitude for the analysis area (degrees, range: -90 to 90) - float\n \"lat_min\": -60, # Minimum latitude for the analysis area (degrees, range: -90 to 90) - float\n \"lon_max\": -20, # Maximum longitude for the analysis area (degrees, range: -180 to 180) - float\n \"lon_min\": -90, # Minimum longitude for the analysis area (degrees, range: -180 to 180) - float\n \"model_name\": None, # Name of the dataset to be used. (Options available: ERA5, GFS). Leave it unchanged if you want to use your own files - string\n \"filepath\": \"path_to_your_netcdf_file\", #Path to the local NetCDF file containing both u, v, specific humidity and temperature (required if model_name is None)\n \"pressure\": 850, # [Default: 850] Atmospheric pressure level (hPa) at which front identification is performed - int\n \"thetaw_thresh\": 3.0, # [Default: 3.0] Threshold for the magnitude of the gradient of potential wet-bulb temperature (K/100km) for front identification - float\n \"vf_thresh\": 1.0, # [Default: 1.0] Threshold for wind velocity (m/s) for front classification as cold or warm front - float\n \"smooth_sigma\": 0.5, # [Default: 0.5] Smoothing parameter (sigma) for Gaussian filtering - float\n \"line_or_area\": \"area\", # Type of representation for the fronts (line or area) - string\n \"min_points\": 4, # [Default: 4] Minimum number of frontal points required for a valid frontal line - int\n \"min_length\": 500.0, # [Default: 500.0] Minimum length (km) for the frontal line to be considered - float\n \"min_area\": 5000.0, # [Default: 5000.0] Minimum area (km\u00b2) for the frontal zone to be considered - float\n \"frame_rate\": 3.0, # [Default: 3.0] Frame rate (frames per second) for the generated animation; higher rates result in a faster animation - float\n \"output_directory_fronts\": \"path_to_your_chosen_output_directory\" # Path to your output directory\n}\n```\n\nCurrently, FrontPy allows you to automatically download ERA5 and GFS data (u, v, temperature, specific humidity) for calculating TFP and identifying fronts. To do this, enter \"ERA5\" or \"GFS\" in the **model_name** parameter. \n\nIf you want to use your own files, all variables must be contained in one netcdf file. In this case, do not assign any value for the **model_name** parameter. Instead, you must provide the path to the netcdf file in the **filepath** parameter, which should include u, v, specific humidity and temperature.\n\n**Note:** The default values have only been tested for the Southern Hemisphere.\n\n**Step 3: Call the main function**:\n\nThe *main* function will return two Pandas dataframes: one for cold fronts and one for warm fronts.\n\nSo, you can call the main function like this:\n\n```python\ncold_fronts, warm_fronts = main(config)\n```\n\n**Step 4: Plot the images and generate an animation**:\n\nLastly, you can plot the results and generate an animation (GIF) using the **plot_results** function. The images and animation will be saved in your output directory.\n\n``` \nplot_results(cold_fronts, warm_fronts, config)\n```\n\n**Obs**: For now, it is only possible to generate images within the coverage area and the available data period of GOES-16 East.\n\n### Command Line Interface (CLI)\n\nFrontPy also supports command-line execution through the **cli.py** file and the **fronts** function. This allows users to specify the parameters directly from the command line.\n\nTo run FrontPy using the CLI, execute the following command in your terminal (without the <>):\n\n```bash\nfronts <start_date> <end_date> <lat_max> <lat_min> <lon_max> <lon_min> <line_or_area> <output_directory_fronts> <mode>\n```\n\nThe above arguments are mandatory and must be provided in string format (in quotes) and in the specified order.\n\n**Mode Argument Explanation:**\n\n- To only **identify and generate the files and dataframes** relative to the TFP field and to cold and warm fronts, type **\"identify\"** as the `<mode>` argument.\n\n- To only **create the images and animation** based on the files and dataframes that have already been generated, type **\"plot\"** as the `<mode>` argument.\n\n- To **perform both actions** type **\"both\"** as the `<mode>` argument.\n\nOptional arguments can also be included using the following prefixes before the values of your choice:\n\n- `--model-name`\n- `--filepath`\n- `--pressure`\n- `--thetaw-thresh`\n- `--vf-thresh`\n- `--smooth-sigma`\n- `--min-points`\n- `--min-length`\n- `--min-area`\n- `--frame-rate`\n\n#### Real example using CLI:\n\n1. Using GFS data to identify and plot the results:\n\n```bash\nfronts \"2024-10-10 00\" \"2024-10-11 00\" \"20\" \"-60\" \"-20\" \"-90\" \"line\" \"/output_directory/\" \"both\" --model-name \"GFS\"\n```\n\n2. Using my own data:\n\n```bash\nfronts \"2024-10-10 00\" \"2024-10-11 00\" \"20\" \"-60\" \"-20\" \"-90\" \"line\" \"/output_directory/\" \"both\" --filepath \"/path_to_my_netcdf_file.nc\"\n```\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the LICENSE file for more details.\n",
"bugtrack_url": null,
"license": null,
"summary": "FrontPy is a Python package designed for the detection and analysis of atmospheric fronts. It uses the Thermal Front Parameter (TFP) method to identify cold and warm fronts. The package also includes visualization capabilities, allowing users to plot the identified fronts over GOES-16 satellite imagery.",
"version": "0.1.14",
"project_urls": {
"Repository": "https://github.com/maartaud/frontpy"
},
"split_keywords": [
"fronts",
" tfp",
" thermal front parameter",
" meteorology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "09455c13eb356da5d3c1d66c01687544ea492241d37dac227037c3263c1944bf",
"md5": "9cd558d6ca52fa85079673ec89681ea1",
"sha256": "6cc3971b77214d07cfbf2f30f2befd37818b1797c536318097e0a05e204c3c2e"
},
"downloads": -1,
"filename": "frontpy-0.1.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9cd558d6ca52fa85079673ec89681ea1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.15",
"size": 25986,
"upload_time": "2024-10-17T18:08:10",
"upload_time_iso_8601": "2024-10-17T18:08:10.954037Z",
"url": "https://files.pythonhosted.org/packages/09/45/5c13eb356da5d3c1d66c01687544ea492241d37dac227037c3263c1944bf/frontpy-0.1.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50086098b6650db6fc12c33bca71eff86939607b0a73de422a9b2d8dcf5b3a89",
"md5": "2e6192783c4c5c04b6b881fce0958b05",
"sha256": "4aa86210021518c8256ea5f4f8defd068c395215cd7d6c614e5cc5534b2cff94"
},
"downloads": -1,
"filename": "frontpy-0.1.14.tar.gz",
"has_sig": false,
"md5_digest": "2e6192783c4c5c04b6b881fce0958b05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.15",
"size": 25830,
"upload_time": "2024-10-17T18:08:12",
"upload_time_iso_8601": "2024-10-17T18:08:12.071427Z",
"url": "https://files.pythonhosted.org/packages/50/08/6098b6650db6fc12c33bca71eff86939607b0a73de422a9b2d8dcf5b3a89/frontpy-0.1.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 18:08:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maartaud",
"github_project": "frontpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "frontpy"
}
