| Name | mapflow JSON |
| Version |
0.2.6
JSON |
| download |
| home_page | None |
| Summary | A Python library to export xarray.DataArray as video files |
| upload_time | 2025-07-27 18:29:50 |
| maintainer | None |
| docs_url | None |
| author | Cyril Joly |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="_static/logo.svg" alt="mapflow logo" width="200" height="200">
# mapflow
[](https://badge.fury.io/py/mapflow)
[](https://anaconda.org/conda-forge/mapflow)
[](https://github.com/CyrilJl/mapflow/actions/workflows/pytest.yaml)
</div>
``mapflow`` transforms 3D ``xr.DataArray`` in video files in one code line. It relies on ``matplotlib`` and ``ffmpeg``. If you're not installing ``mapflow`` from conda-forge, make sure ``ffmpeg`` is installed on your system.
## Installation
```bash
pip install mapflow
```
Or:
```bash
conda install -c conda-forge -y mapflow
```
## Simple usage
```python
import xarray as xr
from mapflow import animate
ds = xr.tutorial.open_dataset("era5-2mt-2019-03-uk.grib")
animate(da=ds['t2m'].isel(time=slice(120)), path='animation.mp4')
```
https://github.com/user-attachments/assets/a6e136eb-5c35-4236-9472-0845a4804740
## Quick documentation
``animate`` is the core function of ``mapflow``.
It creates an animation from an xarray DataArray. This function prepares data from an xarray DataArray (e.g., handling geographic coordinates, extracting time information for titles) and then uses the `Animation` class to generate and save the animation.
### `animate` function arguments
* **`da`** (`xr.DataArray`):
Input DataArray with at least time, x, and y dimensions.
* **`path`** (`str`):
Output path for the video file.
* **`time_name`** (`str`, optional):
Name of the time coordinate in `da`. Defaults to `"time"`.
* **`x_name`** (`str`, optional):
Name of the x-coordinate (e.g., longitude) in `da`. Defaults to `"longitude"`.
* **`y_name`** (`str`, optional):
Name of the y-coordinate (e.g., latitude) in `da`. Defaults to `"latitude"`.
* **`crs`** (`int | str | pyproj.CRS`, optional):
Coordinate Reference System of the data. Defaults to `4326` (WGS84).
```python
# Examples
crs_epsg_code = 4326
crs_proj_string = "+proj=laea +lat_0=52 +lon_0=10 +x_0=4321000 +y_0=3210000 +ellps=GRS80 +units=m +no_defs"
# from pyproj import CRS
# crs_object = CRS.from_epsg(3035)
```
* **`borders`** (`gpd.GeoDataFrame | gpd.GeoSeries | None`, optional):
Custom borders to use for plotting. If `None`, defaults to world borders. Defaults to `None`.
```python
import geopandas as gpd
# Example: Load a shapefile for custom borders
custom_borders = gpd.read_file("path/to/your/custom_borders.shp")
```
* **`cmap`** (`str`, optional):
Colormap for the plot. Defaults to `"jet"`.
Refer to Matplotlib documentation for available colormaps: <https://matplotlib.org/stable/gallery/color/colormap_reference.html>
* **`norm`** (`matplotlib.colors.Normalize`, optional):
Custom normalization object. Defaults to `None`.
```python
import matplotlib.colors as mcolors
# Example: Using a custom normalization
custom_norm = mcolors.PowerNorm(gamma=0.5)
```
* **`log`** (`bool`, optional):
Use logarithmic color scale. Defaults to `False`.
* **`qmin`** (`float`, optional):
Minimum quantile for color normalization. Defaults to `0.01`. Used if `vmin` is not set.
* **`qmax`** (`float`, optional):
Maximum quantile for color normalization. Defaults to `99.9`. Used if `vmax` is not set.
* **`vmin`** (`float`, optional):
Minimum value for color normalization. Overrides `qmin`. Defaults to `None`.
* **`vmax`** (`float`, optional):
Maximum value for color normalization. Overrides `qmax`. Defaults to `None`.
* **`time_format`** (`str`, optional):
Strftime format for time in titles. Defaults to `"%Y-%m-%dT%H"`.
Refer to Python's `strftime` documentation for formatting options: <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes>
```python
# Example: Display only Year-Month-Day
# time_format_example = "%Y-%m-%d"
# Example: Display Hour:Minute AM/PM
# time_format_example = "%I:%M %p"
```
* **`upsample_ratio`** (`int`, optional):
Factor to upsample data temporally for smoother animations. Defaults to `4`. A value of `1` means no upsampling.
* **`fps`** (`int`, optional):
Frames per second for the video. Defaults to `24`.
* **`n_jobs`** (`int`, optional):
Number of parallel jobs for frame generation. Defaults to `None` (auto-determined, typically 2/3 of CPU cores). Set to `1` for no parallel processing.
* **`verbose`** (`int`, optional):
Verbosity level for the Animation class. If `> 0`, progress bars will be shown. Defaults to `0`.
## Future developments
* More customization options
* Better RAM management (generating upsampled frames on the fly instead of computing them all at once)
* CLI tools
* Documentation
Raw data
{
"_id": null,
"home_page": null,
"name": "mapflow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Cyril Joly",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/fb/57/2a737aeb0e1be17376bce237f9db629a37f79ddd319d1518625213f550ab/mapflow-0.2.6.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img src=\"_static/logo.svg\" alt=\"mapflow logo\" width=\"200\" height=\"200\">\n\n# mapflow\n\n[](https://badge.fury.io/py/mapflow)\n[](https://anaconda.org/conda-forge/mapflow)\n[](https://github.com/CyrilJl/mapflow/actions/workflows/pytest.yaml)\n</div>\n\n``mapflow`` transforms 3D ``xr.DataArray`` in video files in one code line. It relies on ``matplotlib`` and ``ffmpeg``. If you're not installing ``mapflow`` from conda-forge, make sure ``ffmpeg`` is installed on your system.\n\n## Installation\n\n```bash\npip install mapflow\n```\n\nOr:\n\n```bash\nconda install -c conda-forge -y mapflow\n```\n\n## Simple usage\n\n```python\nimport xarray as xr\nfrom mapflow import animate\n\nds = xr.tutorial.open_dataset(\"era5-2mt-2019-03-uk.grib\")\nanimate(da=ds['t2m'].isel(time=slice(120)), path='animation.mp4')\n```\n\nhttps://github.com/user-attachments/assets/a6e136eb-5c35-4236-9472-0845a4804740\n\n## Quick documentation\n\n``animate`` is the core function of ``mapflow``.\nIt creates an animation from an xarray DataArray. This function prepares data from an xarray DataArray (e.g., handling geographic coordinates, extracting time information for titles) and then uses the `Animation` class to generate and save the animation.\n\n### `animate` function arguments\n\n* **`da`** (`xr.DataArray`):\n Input DataArray with at least time, x, and y dimensions.\n\n* **`path`** (`str`):\n Output path for the video file.\n\n* **`time_name`** (`str`, optional):\n Name of the time coordinate in `da`. Defaults to `\"time\"`.\n\n* **`x_name`** (`str`, optional):\n Name of the x-coordinate (e.g., longitude) in `da`. Defaults to `\"longitude\"`.\n\n* **`y_name`** (`str`, optional):\n Name of the y-coordinate (e.g., latitude) in `da`. Defaults to `\"latitude\"`.\n\n* **`crs`** (`int | str | pyproj.CRS`, optional):\n Coordinate Reference System of the data. Defaults to `4326` (WGS84).\n\n ```python\n # Examples\n crs_epsg_code = 4326 \n crs_proj_string = \"+proj=laea +lat_0=52 +lon_0=10 +x_0=4321000 +y_0=3210000 +ellps=GRS80 +units=m +no_defs\"\n # from pyproj import CRS\n # crs_object = CRS.from_epsg(3035)\n ```\n\n* **`borders`** (`gpd.GeoDataFrame | gpd.GeoSeries | None`, optional):\n Custom borders to use for plotting. If `None`, defaults to world borders. Defaults to `None`.\n\n ```python\n import geopandas as gpd\n # Example: Load a shapefile for custom borders\n custom_borders = gpd.read_file(\"path/to/your/custom_borders.shp\")\n ```\n\n* **`cmap`** (`str`, optional):\n Colormap for the plot. Defaults to `\"jet\"`.\n Refer to Matplotlib documentation for available colormaps: <https://matplotlib.org/stable/gallery/color/colormap_reference.html>\n\n* **`norm`** (`matplotlib.colors.Normalize`, optional):\n Custom normalization object. Defaults to `None`.\n\n ```python\n import matplotlib.colors as mcolors\n # Example: Using a custom normalization\n custom_norm = mcolors.PowerNorm(gamma=0.5)\n ```\n\n* **`log`** (`bool`, optional):\n Use logarithmic color scale. Defaults to `False`.\n\n* **`qmin`** (`float`, optional):\n Minimum quantile for color normalization. Defaults to `0.01`. Used if `vmin` is not set.\n\n* **`qmax`** (`float`, optional):\n Maximum quantile for color normalization. Defaults to `99.9`. Used if `vmax` is not set.\n\n* **`vmin`** (`float`, optional):\n Minimum value for color normalization. Overrides `qmin`. Defaults to `None`.\n\n* **`vmax`** (`float`, optional):\n Maximum value for color normalization. Overrides `qmax`. Defaults to `None`.\n\n* **`time_format`** (`str`, optional):\n Strftime format for time in titles. Defaults to `\"%Y-%m-%dT%H\"`.\n Refer to Python's `strftime` documentation for formatting options: <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes>\n\n ```python\n # Example: Display only Year-Month-Day\n # time_format_example = \"%Y-%m-%d\"\n # Example: Display Hour:Minute AM/PM\n # time_format_example = \"%I:%M %p\" \n ```\n\n* **`upsample_ratio`** (`int`, optional):\n Factor to upsample data temporally for smoother animations. Defaults to `4`. A value of `1` means no upsampling.\n\n* **`fps`** (`int`, optional):\n Frames per second for the video. Defaults to `24`.\n\n* **`n_jobs`** (`int`, optional):\n Number of parallel jobs for frame generation. Defaults to `None` (auto-determined, typically 2/3 of CPU cores). Set to `1` for no parallel processing.\n\n* **`verbose`** (`int`, optional):\n Verbosity level for the Animation class. If `> 0`, progress bars will be shown. Defaults to `0`.\n\n## Future developments\n\n* More customization options\n* Better RAM management (generating upsampled frames on the fly instead of computing them all at once)\n* CLI tools\n* Documentation\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library to export xarray.DataArray as video files",
"version": "0.2.6",
"project_urls": {
"Homepage": "https://github.com/CyrilJl/mapflow"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2851f96828e6be14d1119676abb0b8623662d6eec4717cdbf13985381dc1c040",
"md5": "19a0437aaabe2026195a8e4b24e244c9",
"sha256": "8ccfc5f542c4819850a98c154472e1c9507f12a26822df6669adf3802072b830"
},
"downloads": -1,
"filename": "mapflow-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "19a0437aaabe2026195a8e4b24e244c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 2055529,
"upload_time": "2025-07-27T18:29:49",
"upload_time_iso_8601": "2025-07-27T18:29:49.300117Z",
"url": "https://files.pythonhosted.org/packages/28/51/f96828e6be14d1119676abb0b8623662d6eec4717cdbf13985381dc1c040/mapflow-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fb572a737aeb0e1be17376bce237f9db629a37f79ddd319d1518625213f550ab",
"md5": "0956647012a40820cf1b08f36517b4a0",
"sha256": "60dc2715ffd6117ed6a8387e6f565eed481e44f6e6fd5e8800c593307507be07"
},
"downloads": -1,
"filename": "mapflow-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "0956647012a40820cf1b08f36517b4a0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2059737,
"upload_time": "2025-07-27T18:29:50",
"upload_time_iso_8601": "2025-07-27T18:29:50.477906Z",
"url": "https://files.pythonhosted.org/packages/fb/57/2a737aeb0e1be17376bce237f9db629a37f79ddd319d1518625213f550ab/mapflow-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 18:29:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CyrilJl",
"github_project": "mapflow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mapflow"
}
