{"id":26005,"name":"DeepR","description":"Global reanalysis downscaling to regional scales by means of deep learning techniques.","url":"https://github.com/ECMWFCode4Earth/DeepR","last_synced_at":"2026-05-16T21:30:22.250Z","repository":{"id":170637075,"uuid":"642751681","full_name":"ECMWFCode4Earth/DeepR","owner":"ECMWFCode4Earth","description":"DeepR: Deep Reanalysis","archived":false,"fork":false,"pushed_at":"2023-10-25T09:54:56.000Z","size":1412,"stargazers_count":32,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-11T19:04:46.336Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ECMWFCode4Earth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-05-19T09:09:28.000Z","updated_at":"2026-04-09T19:25:36.000Z","dependencies_parsed_at":"2023-07-11T02:02:25.277Z","dependency_job_id":"9d0bb543-5623-4cff-bf8e-c515309f3213","html_url":"https://github.com/ECMWFCode4Earth/DeepR","commit_stats":{"total_commits":295,"total_committers":4,"mean_commits":73.75,"dds":"0.33220338983050846","last_synced_commit":"761cc3bc710197ce42c97b211cc27bb743b17601"},"previous_names":["ecmwfcode4earth/deepr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ECMWFCode4Earth/DeepR","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ECMWFCode4Earth","download_url":"https://codeload.github.com/ECMWFCode4Earth/DeepR/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32997729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"ssl_error","status_checked_at":"2026-05-13T13:14:51.610Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"owner":{"login":"ECMWFCode4Earth","name":"ECMWF Code for Earth","uuid":"44897980","kind":"organization","description":"ECMWF Code for Earth is a collaborative programme where each summer several developer teams work on innovative earth sciences-related software.","email":null,"website":"https://codeforearth.ecmwf.int","location":"Online","twitter":"ECMWFCode4Earth","company":null,"icon_url":"https://avatars.githubusercontent.com/u/44897980?v=4","repositories_count":37,"last_synced_at":"2023-05-10T13:37:08.293Z","metadata":{"has_sponsors_listing":false},"html_url":"https://github.com/ECMWFCode4Earth","funding_links":[],"total_stars":null,"followers":null,"following":null,"created_at":"2022-11-13T15:01:28.778Z","updated_at":"2023-05-10T13:37:08.420Z","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ECMWFCode4Earth","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ECMWFCode4Earth/repositories"},"packages":[],"commits":{"id":1338020,"full_name":"ECMWFCode4Earth/DeepR","default_branch":"main","total_commits":295,"total_committers":4,"total_bot_commits":0,"total_bot_committers":0,"mean_commits":73.75,"dds":0.33220338983050846,"past_year_total_commits":0,"past_year_total_committers":0,"past_year_total_bot_commits":0,"past_year_total_bot_committers":0,"past_year_mean_commits":0.0,"past_year_dds":0.0,"last_synced_at":"2026-05-13T20:02:35.159Z","last_synced_commit":"761cc3bc710197ce42c97b211cc27bb743b17601","created_at":"2023-09-12T07:58:55.579Z","updated_at":"2026-05-13T20:02:17.753Z","committers":[{"name":"Mario Santa Cruz Lopez","email":"santacruzm@predictia.es","login":null,"count":197},{"name":"pereza","email":"aperez@predictia.es","login":"aperezpredictia","count":93},{"name":"Mario Santa Cruz","email":"48736305+JPXKQX","login":"JPXKQX","count":4},{"name":"JavierDiezSierra","email":"javier.diez@unican.es","login":"JavierDiezSierra","count":1}],"past_year_committers":[],"commits_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR/commits","host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-05-15T00:00:35.990Z","repositories_count":6234725,"commits_count":894549360,"contributors_count":34908088,"owners_count":1153531,"icon_url":"https://github.com/github.png","host_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories"}},"issues_stats":{"full_name":"ECMWFCode4Earth/DeepR","html_url":"https://github.com/ECMWFCode4Earth/DeepR","last_synced_at":"2025-11-10T02:04:57.643Z","status":"error","issues_count":3,"pull_requests_count":0,"avg_time_to_close_issue":null,"avg_time_to_close_pull_request":null,"issues_closed_count":0,"pull_requests_closed_count":0,"pull_request_authors_count":0,"issue_authors_count":2,"avg_comments_per_issue":0.0,"avg_comments_per_pull_request":null,"merged_pull_requests_count":0,"bot_issues_count":0,"bot_pull_requests_count":0,"past_year_issues_count":0,"past_year_pull_requests_count":0,"past_year_avg_time_to_close_issue":null,"past_year_avg_time_to_close_pull_request":null,"past_year_issues_closed_count":0,"past_year_pull_requests_closed_count":0,"past_year_pull_request_authors_count":0,"past_year_issue_authors_count":0,"past_year_avg_comments_per_issue":null,"past_year_avg_comments_per_pull_request":null,"past_year_bot_issues_count":0,"past_year_bot_pull_requests_count":0,"past_year_merged_pull_requests_count":0,"created_at":"2023-09-12T07:59:07.582Z","updated_at":"2025-11-10T02:04:57.643Z","repository_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR","issues_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/ECMWFCode4Earth%2FDeepR/issues","issue_labels_count":{},"pull_request_labels_count":{},"issue_author_associations_count":{"COLLABORATOR":2,"NONE":1},"pull_request_author_associations_count":{},"issue_authors":{"JPXKQX":2,"mhmnia":1},"pull_request_authors":{},"host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-05-03T00:00:29.752Z","repositories_count":14488306,"issues_count":34264625,"pull_requests_count":112304305,"authors_count":11253318,"icon_url":"https://github.com/github.png","host_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories","owners_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/owners","authors_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors"},"past_year_issue_labels_count":{},"past_year_pull_request_labels_count":{},"past_year_issue_author_associations_count":{},"past_year_pull_request_author_associations_count":{},"past_year_issue_authors":{},"past_year_pull_request_authors":{},"maintainers":[{"login":"JPXKQX","count":2,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/JPXKQX"}],"active_maintainers":[]},"events":{"total":{"WatchEvent":9},"last_year":{"WatchEvent":4}},"keywords":[],"dependencies":[{"ecosystem":"actions","filepath":".github/workflows/on-push.yml","sha":null,"kind":"manifest","created_at":"2023-07-11T02:02:24.379Z","updated_at":"2023-07-11T02:02:24.379Z","repository_link":"https://github.com/ECMWFCode4Earth/DeepR/blob/main/.github/workflows/on-push.yml","dependencies":[{"id":11311216295,"package_name":"actions/checkout","ecosystem":"actions","requirements":"v3","direct":true,"kind":"composite","optional":false},{"id":11311216296,"package_name":"actions/setup-python","ecosystem":"actions","requirements":"v4","direct":true,"kind":"composite","optional":false},{"id":11311216297,"package_name":"pre-commit/action","ecosystem":"actions","requirements":"v3.0.0","direct":true,"kind":"composite","optional":false},{"id":11311216298,"package_name":"actions/upload-artifact","ecosystem":"actions","requirements":"v3","direct":true,"kind":"composite","optional":false},{"id":11311216299,"package_name":"actions/download-artifact","ecosystem":"actions","requirements":"v3","direct":true,"kind":"composite","optional":false},{"id":11311216300,"package_name":"mamba-org/setup-micromamba","ecosystem":"actions","requirements":"v1","direct":true,"kind":"composite","optional":false},{"id":11311216312,"package_name":"pypa/gh-action-pypi-publish","ecosystem":"actions","requirements":"release/v1","direct":true,"kind":"composite","optional":false}]},{"ecosystem":"conda","filepath":"environment.yml","sha":null,"kind":"manifest","created_at":"2023-07-11T02:02:24.578Z","updated_at":"2023-07-11T02:02:24.578Z","repository_link":"https://github.com/ECMWFCode4Earth/DeepR/blob/main/environment.yml","dependencies":[{"id":11311216336,"package_name":"accelerate","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216337,"package_name":"cartopy","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216338,"package_name":"dask","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216339,"package_name":"diffusers","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216340,"package_name":"evaluate","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216417,"package_name":"huggingface_hub","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216419,"package_name":"matplotlib","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216421,"package_name":"mlflow","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216423,"package_name":"netcdf4","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216481,"package_name":"pydantic","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216484,"package_name":"pytorch","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216485,"package_name":"pyyaml","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216487,"package_name":"scikit-image","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216489,"package_name":"seaborn","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216491,"package_name":"tensorboard","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216493,"package_name":"tqdm","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216495,"package_name":"transformers","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216497,"package_name":"types-pyyaml","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216499,"package_name":"types-requests","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false},{"id":11311216775,"package_name":"xarray","ecosystem":"conda","requirements":"","direct":true,"kind":"runtime","optional":false}]},{"ecosystem":"docker","filepath":"Dockerfile","sha":null,"kind":"manifest","created_at":"2023-07-11T02:02:25.028Z","updated_at":"2023-07-11T02:02:25.028Z","repository_link":"https://github.com/ECMWFCode4Earth/DeepR/blob/main/Dockerfile","dependencies":[{"id":11311217651,"package_name":"pytorch/pytorch","ecosystem":"docker","requirements":"2.0.1-cuda11.7-cudnn8-runtime","direct":true,"kind":"build","optional":false}]}],"score":4.941642422609304,"created_at":"2023-09-12T07:39:32.028Z","updated_at":"2026-05-16T21:30:22.261Z","avatar_url":"https://github.com/ECMWFCode4Earth.png","language":"Python","category":"Climate Change","sub_category":"Climate Downscaling","monthly_downloads":0,"total_dependent_repos":0,"total_dependent_packages":0,"readme":"[![OS - Linux](https://img.shields.io/badge/OS-Linux-blue?logo=linux\u0026logoColor=white)](https://www.linux.org/ \"Go to Linux homepage\")\n[![Made with Python](https://img.shields.io/badge/Python-%3E=3.9-blue?logo=python\u0026logoColor=white)](https://python.org \"Go to Python homepage\")\n[![DeepR](https://img.shields.io/static/v1?label=ECMWFCode4Earth\u0026message=deepr\u0026color=blue\u0026logo=github)](https://github.com/MichaelCurrin/badge-generator)\n[![stars](https://img.shields.io/github/stars/ECMWFCode4Earth/DeepR?style=social)](https://github.com/ECMWFCode4Earth/DeepR)\n[![forks](https://img.shields.io/github/forks/ECMWFCode4Earth/DeepR?style=social)](https://github.com/ECMWFCode4Earth/DeepR)\n\n# DeepR: Deep Reanalysis.\n\nGlobal reanalysis downscaling to regional scales by means of deep learning techniques.\n\n[![view - Documentation](https://img.shields.io/badge/view-Documentation-blue?style=for-the-badge)](/docs/#readme \"Go to project documentation\")\n\n## Introduction\n\nIn the rapidly evolving landscape of climate science and data analysis, the need for\nhigh-resolution data has become increasingly evident. Climate researchers and\nprofessionals in various fields, from agriculture to disaster management, rely\nheavily on accurate and detailed data to make informed decisions. However, the existing\nglobal reanalysis data, such as ERA5, with its coarse spatial resolution, often falls\nshort in meeting these requirements. In response to this pressing challenge, the DeepR\nproject, led by Antonio Pérez, Mario Santa Cruz, and Javier Diez, was conceived and\nexecuted with the aim of downscaling ERA5 data to a finer resolution, thus enabling\nenhanced accuracy and applicability across a wide range of industries and research\ndomains.\n\n______________________________________________________________________\n\n## Project Motivation\n\nThe ERA5 Global reanalysis data, with its spatial resolution of approximately 0.25\ndegrees, has proven to be a valuable resource for multiple sectors. Still, its\nlimitations in resolution can hinder precise decision-making and analysis across\ndiverse domains. The primary motivation behind the DeepR project was to bridge this gap\nby downscaling ERA5 data to a finer resolution of\napproximately 0.05 degrees, termed as CERRA resolution. This enhancement aimed to\nunlock the full potential of climate data for improved decision support.\n\n![img.png](docs/_static/project_motivation.png)\n\n______________________________________________________________________\n\n## Super-Resolution in Climate Science\n\nThe project drew inspiration from the field of image processing and computer vision,\nspecifically the concept of super-resolution. In image processing, super-resolution\ninvolves augmenting the resolution or quality of an image, typically generating a\nhigh-resolution image from one or more low-resolution iterations. DeepR adapted this\nconcept to climate science, making it a super-resolution task tailored to atmospheric\nfields.\n\n______________________________________________________________________\n\n## Data: The Foundation of DeepR\n\nIn any data-intensive project, data plays a pivotal role, and DeepR is no exception.\nThe project relies on extensive datasets sourced from the publicly accessible Climate\nData Store (CDS), ensuring transparency and open access to valuable climate information.\n\nThe data used in this project has been generously provided by our mentors and is used\nin its raw form without any processing. To download the data from the repository,\nyou can access the\n[`european_weather_cloud.py`](scripts/download/european_weather_cloud.py) script.\n\nAdditionally, we have developed a script to directly download data from the Climate\nData Store. You can find this script at\n[`climate_data_store.py`](scripts/download/climate_data_store.py).\n\n### Focus on a specific domain\n\nThe project focuses on a specific subdomain within the original domain. In our case,\nthis domain encompasses diverse ecosystems, including mountains, rivers, coastal areas,\nand more. This simplification helps reduce the dimensionality of the problem while\nmaintaining the diversity necessary for comprehensive research.\n\nThe selected domain is shown here:\n\n![img.png](docs/_static/spatial-domain-small.png)\n\nTo achieve this spatial selection of the data, we utilize the\n[`data_spatial_selection.py`](scripts/processing/data_spatial_selection.py) script,\nwhich transforms the data into the desired domain.\n\nThe process of rewriting the data for the smaller domain aims to expedite data access,\nenhancing both memory and time efficiency for smoother and faster data handling.\nFurthermore, this approach empowers users to define their own specific domains and\nseamlessly retrain the model according to their unique research requirements.\n\n______________________________________________________________________\n\n## Definition in configuration file\n\nThe data configuration section outlines how the project manages and processes the data.\nThis section is divided into three main parts: `features_configuration`,\n`label_configuration`, and `split_coverages`.\n\n### Features Configuration\n\nThis part focuses on the configuration of features used in the project.\n\n```yaml\nfeatures_configuration:\n  variables:\n  - t2m\n  data_name: era5\n  spatial_resolution: \"025deg\"\n  add_auxiliary:\n    time: true\n    lsm-low: true\n    orog-low: true\n    lsm-high: true\n    orog-high: true\n  spatial_coverage:\n    longitude: [-8.35, 6.6]\n    latitude: [46.45, 35.50]\n  standardization:\n    to_do: true\n    cache_folder: /PATH/TO/.cache_reanalysis_scales\n    method: domain-wise\n  data_location: /PATH/TO/features/\n  land_mask_location: /PATH/TO/static/land-mask_ERA5.nc\n  orography_location: /PATH/TO/static/orography_ERA5.nc\n```\n\n- **Variables**: The variables to be included, such as `t2m` (2-meter temperature data).\n- **Data Name**: The source of the feature data, which is `era5`.\n- **Spatial Resolution**: The spatial resolution used for feature data is\n  `0.25 degrees`.\n- **Add Auxiliary Data**: Specifies whether auxiliary data is added. In this case,\n  `time`, `lsm-low` (low-resolution land-sea mask), `orog-low` (low-resolution\n  orography), `lsm-high` (high-resolution land-sea mask), and `orog-high`\n  (high-resolution orography) are added.\n- **Spatial Coverage**: The selected spatial coverage, defined by longitude and\n  latitude ranges.\n- **Standardization**: Indicates whether standardization is performed. The\n  `to_do` flag is set to `true`, and the standardization method is `domain-wise`.\n  Other possible methods include `pixel-wise` and `landmask-wise`.\n- **Data Location**: The directory where feature data is stored.\n- **Land Mask Location**: The location of the land-sea mask data for ERA5.\n- **Orography Location**: The location of the orography data for ERA5.\n\n______________________________________________________________________\n\n### Label Configuration\n\nThis part focuses on the configuration of labels used in the project.\n\n```yaml\nlabel_configuration:\n  variable: t2m\n  data_name: cerra\n  spatial_resolution: \"005deg\"\n  spatial_coverage:\n    longitude: [-6.85, 5.1]\n    latitude: [44.95, 37]\n  standardization:\n    to_do: true\n    cache_folder: /PATH/TO/.cache_reanalysis_scales\n    method: domain-wise # pixel-wise, domain-wise, landmask-wise\n  data_location: /PATH/TO/labels/\n  land_mask_location: /PATH/TO/static/land-mask_CERRA.nc\n  orography_location: /PATH/TO/static/orography_CERRA.nc\n```\n\n- **Variable**: The variable used as labels, which is `t2m` (2-meter temperature data).\n- **Data Name**: The source of the label data, which is `cerra`.\n- **Spatial Resolution**: The spatial resolution used for label data is `0.05 degrees`.\n- **Spatial Coverage**: The selected spatial coverage, defined by longitude and\n  latitude ranges.\n- **Standardization**: Indicates whether standardization is performed. The\n  `to_do` flag is set to `true`, and the standardization method is `domain-wise`.\n  Other possible methods include `pixel-wise` and `landmask-wise`.\n- **Data Location**: The directory where label data is stored.\n- **Land Mask Location**: The location of the land-sea mask data for CERRA.\n- **Orography Location**: The location of the orography data for CERRA.\n\n______________________________________________________________________\n\n### Split Coverages\n\nSplitting the data into different time periods for training, validation and test.\n\n```yaml\nsplit_coverages:\n  train:\n    start: 1981-01\n    end: 2013-12\n    frequency: MS\n  validation:\n    start: 2014-01\n    end: 2017-12\n    frequency: MS\n  test:\n    start: 2018-01\n    end: 2020-12\n    frequency: MS\n```\n\n- **Train**: Data split for training begins from `1981-01` and ends at `2013-12`,\n  with a frequency of `Monthly (MS)`.\n- **Validation**: Data split for validation starts from `2014-01` and ends at\n  `2017-12`, with a frequency of `Monthly (MS)`.\n- **Test**: Data split for validation starts from `2018-01` and ends at\n  `2020-12`, with a frequency of `Monthly (MS)`.\n\nThese configuration settings are crucial for organizing, processing, and standardizing\nthe data used in the project.\n\n______________________________________________________________________\n\n## Methodology\n\n### Standardization\n\n#### Why is it important?\n\nIn the context of deep learning for climatology, standardizing climatological data is a\ncrucial step. Standardization refers to the process of transforming the data to have a\nmean of zero and a standard deviation of one. This process is vital for several reasons:\n\n- **Preventing Dominance**: Standardization prevents one variable from dominating the\n  learning process. In climate data, variables can have vastly different scales and\n  magnitudes. Without standardization, variables with larger scales could overshadow\n  others, leading to biased model training.\n\n- **Capturing Complex Patterns**: Standardized data allows the deep learning model to\n  effectively capture complex climate patterns across diverse geographical regions.\n  By removing scale differences, the model can focus on extracting meaningful patterns\n  and relationships within the data.\n\n- **Facilitating Convergence**: Deep neural networks benefit from standardized input\n  data. It helps in the convergence of the network during training. When the input\n  data has consistent scales and distributions, the optimization process becomes more\n  stable, and the model is more likely to converge to a meaningful solution.\n\n#### Application\n\nTo apply standardization to climatological data, we use the script located in\n[`scaler.py`](%60deepr/data/scaler.py%60). This script automates the process of\nstandardization, making it easy to preprocess large datasets efficiently.\n\n![img.png](docs/_static/standardization_types.png)\n\nIn summary, standardizing climatological data is a fundamental preprocessing step\nthat ensures the deep learning model can learn effectively, prevent variable dominance,\ncapture intricate climate patterns, and converge efficiently during training. It plays\na pivotal role in enhancing the model's performance and its ability to provide\nvaluable insights into climatic phenomena.\n\n______________________________________________________________________\n\n## Modeling\n\nThe two main modeling approaches covered are:\n\n### Diffusion model\n\nThe probabilistic generative model employed in this context is a sophisticated\nframework designed to denoise images. It leverages a diffusion process, which is a\nmathematical concept representing the gradual spread of information or change across\ndata. In the context of image denoising, the diffusion process helps in gradually\nremoving noise from an image while preserving the underlying structure and content.\n\nAdvantages of the Model:\n\n- Learning Capacity: The probabilistic generative model is endowed with significant\n  learning capacity. It has the ability to learn intricate structures and patterns\n  from data. This means it can effectively capture complex features, textures, and\n  nuances present in images. By learning from a diverse range of images, it becomes\n  proficient in identifying and preserving the underlying information even in noisy\n  or low-resolution inputs.\n\n- Extrapolation: The model exhibits a remarkable generalization capability known as\n  extrapolation. It means that once the model has learned from a set of training data,\n  it can extend its knowledge to new and unseen scenarios. This ability is invaluable\n  in real-world applications where the model encounters image inputs it hasn't\n  explicitly seen during training. Despite this, it can produce high-quality denoised\n  outputs.\n\n- Realism: A key strength of the probabilistic generative model is its capacity to\n  produce denoised images that maintain a high level of realism. This realism extends\n  to preserving fine details, textures, and nuances in the upscaled images.\n  Additionally, the model is adept at handling artifacts that may be present in the\n  input images, resulting in outputs that closely resemble natural, artifact-free images.\n\nThe scheme of the Diffusion process:\n\n![img.png](docs/_static/dp_scheme.png)\n\n## The diffusers library\n\nThe [Diffusers](https://huggingface.co/docs/diffusers/v0.16.0/en/api/models) library\nprovides a comprehensive set of options for working with Diffusion Models.\nIn this documentation, we explore various options and functionalities available in the\nlibrary that can be tailored to specific use cases or extended with custom\nimplementations.\n\n______________________________________________________________________\n\n### diffusers.UNet2DModel\n\nThe [diffusers.UNet2DModel](https://huggingface.co/docs/diffusers/v0.16.0/en/api/models#diffusers.UNet2DModel)\nclass closely resembles our U-net architecture. It offers flexibility in designing the\ndown and up blocks, making it a versatile choice for various tasks.\n\n#### Down Blocks\n\nYou can choose from a variety of down block types, including:\n\n- DownBlock2D\n- ResnetDownsampleBlock2D\n- AttnDownBlock2D\n- CrossAttnDownBlock2D\n- SimpleCrossAttnDownBlock2D\n- SkipDownBlock2D\n- AttnSkipDownBlock2D\n- DownEncoderBlock2D\n- AttnDownEncoderBlock2D\n- KDownBlock2D\n- KCrossAttnDownBlock2D\n\n#### Up Blocks\n\nThe available up block types include:\n\n- UpBlock2D\n- ResnetUpsampleBlock2D\n- CrossAttnUpBlock2D\n- SimpleCrossAttnUpBlock2D\n- AttnUpBlock2D\n- SkipUpBlock2D\n- AttnSkipUpBlock2D\n- UpDecoderBlock2D\n- AttnUpDecoderBlock2D\n- KUpBlock2D\n- KCrossAttnUpBlock2D\n\nHere's an example configuration for\n[diffusers.UNet2DModel](https://huggingface.co/docs/diffusers/v0.16.0/en/api/models#diffusers.UNet2DModel):\n\n```yaml\ntraining_configuration:\n  type: diffusion\n  model_configuration:\n    eps_model:\n      class_name: diffusers.UNet2DModel\n      kwargs:\n        block_out_channels: [112, 224, 336, 448]\n        down_block_types: [DownBlock2D, AttnDownBlock2D, AttnDownBlock2D, AttnDownBlock2D]\n        up_block_types: [AttnUpBlock2D, AttnUpBlock2D, AttnUpBlock2D, UpBlock2D]\n        layers_per_block: 2\n        time_embedding_type: positional\n        num_class_embeds: 24\n        in_channels: 2\n        norm_num_groups: 4\n    scheduler:\n      class_name: LMSDiscreteScheduler\n      kwargs:\n        num_train_timesteps: 1000\n        beta_start: 0.0001\n        beta_end: 0.02\n        beta_schedule: linear\n        prediction_type: epsilon\n        timestep_spacing: trailing\n```\n\nThe [diffusers.UNet2DModel](https://huggingface.co/docs/diffusers/v0.16.0/en/api/models#diffusers.UNet2DModel)\nalso accepts conditioning on labels through its argument `class_labels`. First,\nthe embedding type must be specified in the [`__init__`](https://github.com/huggingface/diffusers/blob/v0.16.0/src/diffusers/models/unet_2d.py#L83) method trough:\n\n- Passing `class_embed_type` (Options are 'timestep', 'identity' or None).\n- Passing `num_class_embeds` with the size of the dictionary of embeddings to use.\n\nFor example, to consider the hour of the data as covariate in this model we have\ntwo options:\n\n**Option A:** Set `num_class_embeds = 24` in the model creation and\n`hour_embed_type = class` in training configuration. This way the model learns\nan Embedding table for each hour.\n\n**Option B:** Set `class_embed_type = identity` in the model configuration and\n`hour_embed_type = positional` in training configuration.\n\n**Option C:** Set `class_embed_type = timestep` in the model configuration and\n`hour_embed_type` = `timestep` in training configuration. This configuration applies\nthe same cos \u0026 sin transformation as in Option B maintaining the same\n`max_duration=10000`. Unlike Option B, we fit 2 `nn.Linear` after the embedding\nbefore feeding it to the NN.\n\n______________________________________________________________________\n\n### diffusers.UNet2DConditionModel\n\nThe [diffusers.UNet2DConditionModel](https://huggingface.co/docs/diffusers/v0.16.0/en/api/models#diffusers.UNet2DConditionModel) is an extension of the previous [diffusers.UNet2DModel](https://huggingface.co/docs/diffusers/v0.16.0/en/api/models#diffusers.UNet2DModel) to consider conditions during the reverse process such as time stamps, or other covariables.\n\nOne interesting parameter to tune is the activation funcion used in the time embedding which can be: Swish, Mish, SiLU or GELU.\n\nBut the most remarkable difference is the possibility of conditioning the reverse diffusion process in the encoder hidden states (comming from images, text, or any other)\n\nOne example configuration to use [diffusers.UNet2DConditionModel](https://huggingface.co/docs/diffusers/v0.16.0/en/api/models#diffusers.UNet2DConditionModel) is included below:\n\n```yaml\ntraining_configuration:\n  type: diffusion\n  model_configuration:\n    eps_model:\n      class_name: diffusers.UNet2DConditionModel\n      kwargs:\n        block_out_channels: [\n          124,\n          256,\n          512\n        ]\n        down_block_types: [\n          CrossAttnDownBlock2D,\n          CrossAttnDownBlock2D,\n          DownBlock2D\n        ]\n        mid_block_type: UNetMidBlock2DCrossAttn\n        up_block_types: [\n          UpBlock2D,\n          CrossAttnUpBlock2D,\n          CrossAttnUpBlock2D\n        ]\n        layers_per_block: 2\n        time_embedding_type: positional\n        in_channels: 2\n        out_channels: 1\n        sample_size: [20, 32]\n        only_cross_attention: False\n        cross_attention_dim: 256\n        addition_embed_type: other\n```\n\n______________________________________________________________________\n\n### Tailored UNet\n\nIn particular, a tailored U-Net architecture with 2D convolutions, residual connections and attetion layers is used.\n\n![U-Net Architecture Diagram](docs/_static/eps-U-Net%20diagram.svg)\n\nThe parameteres of these model implemented in [deepr/model/unet.py](deepr/model/unet.py) are:\n\n- `image_channels`: It is the number of channels of the high resolution imagen we want to generate, that matches with the number of channels of the output from the U-Net. Default value is `1`, as we plan to sample one variable at a time.\n\n- `n_channels`: It is the number of output channels of the initial Convolution. Defaults to `16`.\n\n- `channel_multipliers`: It is the multiplying factor over the channels applied at each down/upsampling level of the U-Net. Defaults to `[1, 2, 2, 4]`.\n\n- `is_attention`: It represents the use of Attention over each down/upsampling level of the U-Net. Defaults to `[False, False, True, True]`.\n\n- `n_blocks`: The number of residual blocks considered in each level. Defaults to `2`.\n\n- `conditioned_on_input`: The number of channels of the conditions considered.\n\n*NOTE I*: The length of `channel_multipliers` and `is_attention` should match as it sets the number of resolutions of our U-Net architecture.\n\n*NOTE II*: Spatial tensors fed to Diffusion model must have shapes of length multiple of $2^{\\\\text{num resolutions} - 1}$.\n\nAn example configuration for this model is specified in training_configuration \u003e model_configuration \u003e eps_model,\n\n```yaml\ntraining_configuration:\n  type: diffusion\n  model_configuration:\n    eps_model:\n      class_name: UNet\n      kwargs:\n        block_out_channels: [32, 64, 128, 256]\n        is_attention: [False, False, True, True]\n        layers_per_block: 2\n        time_embedding_type: positional\n        in_channels: 2\n        out_channels: 1\n        sample_size: [20, 32]\n```\n\n##### Downsampling\n\nThe class [Downsample](deepr/model/unet_blocks.py#LL20) represents a downsampling\nblock. It uses a convolutional layer to reduce the spatial dimensions of the input\ntensor. Here are the key details:\n\n- Constructor: Initializes a nn.ConvTranspose2d layer with specified input and output\n  channels, kernel size, stride, and padding.\n\n- Forward Method: Takes an input tensor x and a time tensor t (though t is not used in\n  this case) and applies the convolution operation to downsample x.\n\n##### Upsampling\n\nThe class [Upsample](deepr/model/unet_blocks.py#LL8) represents an upsampling block.\nIt uses a transposed convolutional layer to increase the spatial dimensions of the\ninput tensor. Here are the key details:\n\n- Constructor: Initializes a nn.ConvTranspose2d layer with specified input and output\n  channels, kernel size, stride, and padding.\n\n- Forward Method: Takes an input tensor x and a time tensor t (though t is not used in\n  this case) and applies the transposed convolution operation to upsample x.\n\n##### Down Block\n\nThe class [Down block](deepr/model/unet_blocks.py#LL30) represents a block used in the\nfirst half of a U-Net architecture for encoding input features. It consists of a\nresidual block followed by an optional attention block. Here are the key details:\n\n- Constructor: Initializes a ResidualBlock and, if has_attn is True, an AttentionBlock.\n  These blocks are used for feature extraction during downsampling.\n\n- Forward Method: Takes an input tensor x and a time tensor t and passes x through the\n  residual block and, if applicable, the attention block.\n\n##### Middle Block\n\nThe class [Middle block](deepr/model/unet_blocks.py#LL123) represents a block used in\nthe middle section of a U-Net architecture. It contains two residual blocks with\nan attention block in between. Here are the key details:\n\n- Constructor: Initializes two ResidualBlock instances and an AttentionBlock. This\n  block is typically used for processing features in the middle layers of the U-Net.\n\n- Forward Method: Takes an input tensor x and a time tensor t and passes x through\n  the first residual block, the attention block, and then the second residual block.\n\n##### Up Block\n\nThe class [Up block](deepr/model/unet_blocks.py#LL73) represents a block used in the\nsecond half of a U-Net architecture for decoding features. It consists of a residual\nblock followed by an optional attention block. Here are the key details:\n\n- Constructor: Initializes a ResidualBlock and, if has_attn is True, an AttentionBlock.\n  These blocks are used for feature decoding during upsampling.\n\n- Forward Method: Takes an input tensor x and a time tensor t and passes x through\n\n- the residual block and, if applicable, the attention block.\n\n##### Residual Block\n\nThe class [Residual Block](deepr/model/resnet.py#LL7) is a component commonly used in\nneural networks. It enhances feature extraction and information flow within the\nnetwork. Key details include:\n\n- Constructor: Initializes the block with input and output channel specifications,\n  time channels, group normalization settings, and optional dropout.\n\n- Components:\n\n  - Two convolutional layers with group normalization and Swish activation.\n  - Time embeddings for temporal information.\n  - Optional dropout.\n\n- Forward Method: Takes an input tensor and time tensor, applies convolution,\n  adds time embeddings, and produces the output tensor.\n\n______________________________________________________________________\n\n### Convolutional Swin2SR\n\nThe Convolutional Swin2SR is a state-of-the-art (SOTA) neural network designed for\nsuper-resolution tasks in computer vision. It stands out for several key features\nthat make it a powerful tool for enhancing image resolution:\n\n- Efficient Scaling: The model's primary component is based on Swin v2 attention layers,\n  which are known for their efficiency and effectiveness. These layers enable the network\n  to efficiently process and generate high-resolution images while maintaining\n  performance.\n\n- Easy Experiment Setting: Setting up experiments with the Convolutional Swin2SR is\n  straightforward, making it accessible for researchers and practitioners. The model's\n  architecture and parameters are designed for ease of use and experimentation.\n\n- Fast Training and Inference: Thanks to its efficient design, the Convolutional\n  Swin2SR offers fast training and inference times. This efficiency is particularly\n  valuable when dealing with large datasets or real-time applications.\n\n![img.png](docs/_static/convswin2sr_scheme.png)\n\nLoss Terms: The model employs various loss terms to guide the training process\neffectively:\n\n- L1 Loss of Predictions and References: This loss term measures the difference\n  between the model's predictions and the high-resolution reference images. It encourages\n  the model to generate outputs that closely match the ground truth.\n\n- L1 Loss of Downsampled Predictions and References: To further refine the training\n  process, the model also considers downsampled versions of both predictions and\n  references. This helps in capturing details at multiple scales.\n\n- L1 Loss of Blurred Predictions and References: Blurring is introduced as an\n  additional loss term, allowing the model to learn and recover fine details while\n  handling different levels of image degradation.\n\nFor training the Convolutional-Swin2SR, a configuration similar to the one provided\nneeds to be given:\n\n```yaml\ntraining_configuration:\n  type: end2end\n  model_configuration:\n    neural_network:\n      class_name: ConvSwin2SR\n      kwargs:\n        embed_dim: 180\n        depths: [6, 6, 6, 6, 6, 6]\n        num_heads: [6, 6, 6, 6, 6, 6]\n        patch_size: 1\n        window_size: 5\n        num_channels: 1\n        img_range: 1\n        resi_connection: \"1conv\"\n        upsampler: \"pixelshuffle\"\n        interpolation_method: \"bicubic\"\n        hidden_dropout_prob: 0.0\n        upscale: 5\n```\n\n______________________________________________________________________\n\n### Training configuration: commons\n\nThere are training parameters that are common to all the models:\n\n- `num_epochs`: The number of training epochs.\n- `batch_size`: The batch size for training.\n- `gradient_accumulation_steps`: The number of gradient accumulation steps.\n- `learning_rate`: The initial learning rate.\n- `lr_warmup_steps`: The number of warm-up steps for learning rate scheduling.\n- `mixed_precision`: Mixed-precision training, e.g., `\"fp16\"`.\n- `hour_embed_type`: Type of hour embedding, e.g., `\"class\"`.\n- `hf_repo_name`: The Hugging Face repository name for model storage.\n- `output_dir`: The directory for saving training outputs.\n- `device`: The device for training, e.g., `\"cuda\"` for GPU.\n- `push_to_hub`: Whether to push the trained model to the Hugging Face model hub.\n- `seed`: Random seed for reproducibility.\n- `save_model_epochs`: Frequency of saving the model during training.\n- `save_image_epochs`: Frequency of saving images during training.\n\nAn example of how they should be defined in the configuration file is provided:\n\n```yaml\ntraining_parameters:\n    num_epochs: 50\n    batch_size: 8\n    gradient_accumulation_steps: 2\n    learning_rate: 0.001\n    lr_warmup_steps: 500\n    mixed_precision: \"fp16\"\n    hour_embed_type: class # none, timestep, positional, cyclical, class\n    output_dir: \"/PATH/TO/WRITE/ARTIFACTS\"\n    device: cuda\n    seed: 2023\n    save_model_epochs: 5\n    save_image_epochs: 5\n```\n\n______________________________________________________________________\n\n## Training a model\n\nTo train your model, follow these steps:\n\n1. Prepare your dataset: Ensure that your dataset is properly formatted with all the\n   different netCDF files inside the same folder structure.\n\n1. Configure your training parameters: Create a configuration file (usually in YAML\n   format) that specifies various training hyperparameters, such as learning rate, batch\n   size, number of epochs, etc. You can use the provided configuration examples as a\n   starting point.\n\n1. Start training: Run the training script, specifying the path to your configuration\n   file. The training script is located at\n   [`train_model.py`](scripts/modeling/train_model.py)\n\n______________________________________________________________________\n\n## Generating model predictions\n\nTo make predictions using the model you've defined, you can use the provided script:\n[`generate_model_predictions.py`](scripts/modeling/generate_model_predictions.py)\n\nThis script is designed to generate predictions using your trained model. You can run\nit with the appropriate input data to obtain model predictions for your specific\ntask or application.\n\n______________________________________________________________________\n\n## Appendix I: Positional Embeddings\n\nWhen working with sequential data, the order of the elements is important, and we must pay attention to how we pass this information to our models.\n\nIn our particular case, the timesteps $t$ is encoded with positional embeddings as proposed in the [Denoising Diffusion Probabilistic Models](https://arxiv.org/pdf/2006.11239.pdf) paper.\n\n![Positional Embeddings](docs/_static/pos_embedding.png)\n\nBesides, we may encode other important features as the hour of the day or the day of the year, which are cyclical. This is different from positional encodings because we want the encoding from hour 23 to be more similar to the one from 0 than from hour 18.\n\n## References\n\n- Ho, J., Jain, A., \u0026 Abbeel, P. (2020). [Denoising diffusion probabilistic models](https://arxiv.org/pdf/2006.11239.pdf). Advances in Neural Information Processing Systems, 33, 6840-6851.\n\n- Song, J., Meng, C., \u0026 Ermon, S. (2020). [Denoising diffusion implicit models](https://arxiv.org/pdf/2010.02502.pdf). arXiv preprint arXiv:2010.02502.\n\n- Conde, M. V., Choi, U. J., Burchi, M., \u0026 Timofte, R. (2022). [Swin2SR: Swinv2 transformer for compressed image super-resolution and restoration](https://arxiv.org/pdf/2209.11345.pdf). arXiv preprint arXiv:2209.11345.\n\n- Rombach, R., Blattmann, A., Lorenz, D., Esser, P., \u0026 Ommer, B. (2022). [High-resolution image synthesis with latent diffusion models](https://arxiv.org/pdf/2112.10752.pdf). In Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (pp. 10684-10695).\n\n- [Annotated Deep Learning Paper implementations](https://github.com/labmlai/annotated_deep_learning_paper_implementations)\n\n## License\n\n```\nCopyright 2023, European Union.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n## Workflow for developers/contributors\n\nFor best experience create a new conda environment (e.g. DEVELOP) with Python 3.10:\n\n```\nmamba create -n deepr-cuda -c conda-forge python=3.10\nmamba activate deepr-cuda\nmake mamba-cuda_env-update\n```\n\nA data directory for the testing data must be created:\n\n```\ncd tests\nmkdir data\ncd data\nmkdir features\nmkdir labels\n```\n\nOnce the directories have been created, testing data can be downloaded:\n\n```\ncd tests\nwget -O data.zip https://cloud.predictia.es/s/zen8PGwJbi7mTCB/download\nunzip data.zip\nrm data.zip\n```\n\nBefore pushing to GitHub, run the following commands:\n\n1. Update conda environment: `make conda-env-update`\n1. Install this package: `pip install -e .`\n1. Sync with the latest [template](https://github.com/ecmwf-projects/cookiecutter-conda-package) (optional): `make template-update`\n1. Run quality assurance checks: `make qa`\n1. Run tests: `make unit-tests`\n1. Run the static type checker: `make type-check`\n1. Build the documentation (see [Sphinx tutorial](https://www.sphinx-doc.org/en/master/tutorial/)): `make docs-build`\n","funding_links":[],"readme_doi_urls":[],"works":{},"citation_counts":{},"total_citations":0,"keywords_from_contributors":[],"project_url":"https://ost.ecosyste.ms/api/v1/projects/26005","html_url":"https://ost.ecosyste.ms/projects/26005"}