The CBE Clima Tool allows users to analyze and visualize climatic data. Via a map-based interface, our tool allows the users to easily access EPW files for circa 30,000 locations worldwide from two online repositories the Energy Plus and Climate.One.Building.org. In addition, users can upload into our tool their own EPW file.

Users can download:

• all the charts and figures in Scalable Vector Graphics (SVG);

• the data from the EPW file or those we used in the tool to generate the plots in Comma-Separated Values (CSV) format.

When displaying the variables in the interactive plots users can either select to use the Global or Local Value Ranges. The Global option uses preset limits for the chart axes, chosen to cover the vast majority of the climatic ranges to be found on planet Earth. This allows the user to easily compare charts generated for any two different locations. The Local option sets the upper and lower limits of the chart axes as a function of the data contained in the EPW file.

The top section of the page provides information about the selected location such as longitude, latitude, and Koppen-Geiger climate zone. Via this page, the user can also download the EPW data and the Clima Dataframe used to generate the plots, as shown below.

The bottom section of the page comprises the heating and cooling degree day chart and four violin plots showing the distribution of the dry-bulb air temperature (Tdb), relative humidity (RH), Global Horizontal Irradiance (GHI), and wind speed (U).

Video Tutorial

Learn more about the Climate Summary tab by watching the following video.

The CBE Clima Tool is a web-based application built to support climate analysis specifically designed to support the need of architects and engineers interested in climate-adapted design. It allows users to analyze the climate data of more than 27,500 locations worldwide from both Energy Plus and Climate.One.Building.org. You can, however, also choose to upload your own EPW weather file. Our tool can be used to analyze and visualize data contained in EnergyPlus Weather (EPW) files. It furthermore calculates a number of climate-related values (i.e. solar azimuth and altitude, Universal Thermal Climate Index (UTCI), comfort indices, etc.) that are not contained in the EPW files but can be derived from the information therein contained. It can be freely accessed at clima.cbe.berkeley.edu

If you use this tool please consider citing us. Betti, G., Tartarini, F., Nguyen, C, Schiavon, S. CBE Clima Tool: A free and open-source web application for climate analysis tailored to sustainable building design. Build. Simul. (2023). https://doi.org/10.1007/s12273-023-1090-5.

The CBE Clima Tool is open source. We have released the source code on a public repository. We welcome contributions from the community (more info here).

Video Tutorial

Learn more about the CBE Clima Tool by watching the following video.

Contributions

This ongoing project results from the collaboration and contributions of the people listed below.

• : Conceptualization, methodology, coding, review, supervision, and project administration

• : Methodology, coding, review, supervision, and code maintenance

• : Conceptualization, review, supervision, project administration, and funding acquisition

Acknowledgment

We would like to thank for their valuable feedback and support: Ed Arens, Dru Crawley, David Lehrer, Noah Pitts, and Hui Zhang. has been supported by the at the University of California Berkeley and the Republic of Singapore's National Research Foundation for Program.

License

In addition to the data from and CBE Clima Tool allows users to visualize any valid EPW file. Below we list some free sources from which climate files can be obtained.

The following sources will be divided according to:

• (TMY), in which weather data are condensed into a year of the most usual conditions;

The Climate Profiles graph gives the user the opportunity to observe at a glance the distribution of the data in the EPW file for four key variables and their variation between day and night.

The Climate Profiles graph are . They show the of the data at different values, usually smoothed by a . Wider sections of the violin plot represent a higher probability that members of the population will take on the given value; the skinnier sections represent a lower probability.

On mouse hover, they display various statistical properties of the data:

• maximum value

The Clima app is organized in a series of tabs that allow the exploration of various topics. All the tabs other than "Select Weather File" are active after a weather file has been selected.

Although there is a logical sequence in the organization of the tabs, thy can be accessed in any order.

The Followin section will explain the content and the usage of each tab.

Users can either choose to analyse the climate of the locations displayed on the map or upload a custom EPW file. After loading an EPW file the user can then access the other tabs to generate dynamic visualisations of the data.

Video Tutorial

Learn more about how to analyse the climate of a specific location and uploading your custom EPW file by watching the following video.

The Temperature and Humidity tab presents an overview of air dry bulb temperature and relative humidity trends.

Clima allows the user to visualize the annual data trend through a customizable chart.

Daily scatter plot shows all hourly data on all days of the month and the typical monthly trend.

allow the intensity of values to be perceived through color palettes throughout the year.

Video Tutorial

Learn more about the Temperature and Relative Humidity tab by watching the following video.

The CBE Clima Tool is still in the beta version. Much work still needs to be done, especially in developing comprehensive documentation.

Please report issues with the tool here.

Comments, suggestions, critiques (and offers of help) are most welcome! Please report them using this form.

you might want to start understanding what degree days are here:

Degree days are calculated as the integral of the difference between the outside air temperature and a base temperature over time.

If you can define a base temperature (the outside temperature above which a building needs no heating or cooling) then you can use this to estimate degree days. The building requires heating if the outside air temperature falls below the heating base temperature, and the heating degree days accrue; if the outside air temperature rises above the cooling base temperature, the structure requires cooling, and the cooling degree days accumulate.

The base temperature does not necessarily correspond to the desired building internal temperature, but is the homeostatic temperature between the interior and exterior. Base temperature might depend, among other factors, upon the use of the building, the internal heat gains and the level of insulation.

Clima calculates new variables and creates a new dataframe containing the variables already inside the original EPW files and other we calculate. Users can overlay all the variables on the sun path, on the psychrometric chart, and on the customizable graphs in the data explorer.

All the variables in the new Clima dataframe are listed below.

• Dry Bulb Temperature

In the cartesian coordinates, the solar elevation is plotted on the y-axis and the azimuth is plotted on the x-axis. It shows the path we would see the sun follow if we took a video with the camera in the right direction of the horizon (as notable comparing the following two figures).

A photographic paper left inside a cider exposed through a pinhole aperture captured 8 years of sun full cycles. The photographic paper immortalized a real cartesian sun path.

The cartesian sun path is comprised of various graphical elements overlayed on one another.

We'll attempt to describe them individually below.

The cartesian sun path can be read as a of the spherical sun path diagram. The map projection encompasses a wide range of transformations used to represent the curved two-dimensional surface of a globe on a plane. The cylindrical projection is obtained by unraveling the globe inside a cylinder. Among the different distortion versions of the globe in a flat map, the is a compromise that does not sacrifice either area or map shapes excessively at the extremes.

The planes parallel to the x-axis can be understood as sections of the imaginary sky dome. Each plane represents an increment of 10 degrees from the horizon. Thereby, it is possible to read the height of the sun in each of its positions.

The geographical coordinates are plotted on the x-axis in degrees, going from left to right: North (0°), East (90°), south (180°), and West (270°).

The upper spline represents the sun's path during the summer solstice, i.e. the maximum height of the sun above the horizon for the examined location. Meanwhile, the lower spline is the sun’s path during the winter solstice, when the sun reaches the lowest height above the horizon. The spline in the middle is the sun's path during the Equinoxes.

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people

• Being respectful of differing opinions, viewpoints, and experiences

• Giving and gracefully accepting constructive feedback

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or

  advances of any kind

• Trolling, insulting or derogatory comments, and personal or political attacks

• Public or private harassment

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement using All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the , version 2.0, available at .

Community Impact Guidelines were inspired by .

For answers to common questions about this code of conduct, see the FAQ at . Translations are available at .

Yearly chart

The annual graph allows the different months' relative humidity ranges to be evaluated. Moreover, overlaying the average value trend for each day helps visualize the differences between the minimum and maximum daily values for the investigated location.

The humidity comfort band is overlaid, considering 30-70% RH the comfortable range. With these trends, climates can be assessed, whether too dry or too humid, then evaluating design solutions that include humidification or dehumidification system.

Outdoor relative humidity varies greatly depending on the amount of rainfall. As expected, hot dry and tropical climates have diametrically opposite trends, always outside the comfort range, and some measures must be taken to recreate comfortable situations in buildings.

Daily chart

Monthly show all hourly relative humidity. The humidity excursion is much more evident than in the annual graphs. Daily medians, i.e., the most frequently occurring values, help evaluate the outliers.

Typical monthly days are useful to study relative humidity patterns. It is possible to read the variability of rainfall in a given location, from the constant high rates of tropical climate to the confusing and variable patterns of continental ones.

Heatmap

Heatmap is another very useful method for evaluating relative humidity excursion over a year (by evaluating the horizontal gradient) or over individual days (by evaluating the vertical gradient).

The four heatmaps give a clear idea of the comparison of the four climate types. Albeit little differences in the percentage scale, observations can be made about relative humidity trends, especially between day and night. Except on rainy days, we can see how daily sunshine decreases relative humidity, even in tropical climates.

Descriptive statistics

The last tool for relative humidity assessment is the statistics table. The earlier graphically made evaluations can be supported by the numbers. The following are listed, for each month:

• the relative humidity means;

• the ;

• the minimum values;

The cloud coverage diagram reports, for every month of the year the frequency of "clear", "cloudy" or "intermediate" conditions.

As the Cloud cover is reported in tenths of coverage (i.e. 0 is 0/10 covered. 10 is total coverage) for the purpose of this graph we have simplified the scale as per the table below.

The Wind tab presents an overview of how to visualize the intensity, frequency, and direction of the wind.

Clima allows the user to visualize the annual, seasonal, daily and customizable period wind data in a wind rose.

Moreover, Clima shows wind intensity and direction using heat maps.

Video Tutorial

Learn more about the Wind tab by watching the following video.

The spherical sun path is comprised of various graphical elements overlayed on one another.

We'll attempt to describe them individually below.

The sunpath can be read as a compass, with the radial lines indicating the different directions.

The concentric circles can be understood as sections of the immaginary sky dome. Each ring represents an increment of 10 degreees from the horizon. As such, they help visualize the solar altitude for each sun position.

The daily path of the sun on a given day can be traced by following a sun path spline from the east (sunrise) to the west (sunset).

The upper spline represents the sun's path during the summer solstice, i.e. the maximum height of the sun above the horizon for the examined location. Meanwhile, the lower spline is the sun’s path during the winter solstice, when the sun reaches the lowest height above the horizon. The spline in the middle is the sun's path during the Equinoxes.

Gathering the sun's positions for each time of day, during all days of the year, creates splines called .

Overlapping photos taken at the same time of day over the course of an entire year results in an analemma like the one in the picture.

The last section of Clima allows for a deeper analysis of all the data in the Clima dataframe.

The tab is divided into three sections:

• Single-variable analysis

• Single-variable + filter analysis

• Triple-variable + filter analysis

The single-variable analysis allows data to be displayed in 4 outputs: a yearly chart, monthly daily charts, an annual heatmap chart, and a descriptive statistics table.

The single-variable + filter analysis allows data to be displayed in a customizable heatmap. The chart can be created starting from one variable inside the Clima dataframe and, eventually, filtered by another one.

The triple-variable + filter analysis allows data to be displayed in two composite charts, a scatterplot, and a heat map. The baselines of the two graphs are driven by the choice of one variable to be placed on the x-axis and one on the y-axis. Then, data can be colored according to a third variable and filtered according to a fourth.

Video Tutorial

Learn more about the Data Explorer tab by watching the following video.

The Outdoor Comfort tab shows an overview of the perceived environmental condition based on the UTCI model.

The Universal Thermal Climate Index (UTCI), introduced in 1994, aims to be the measure of human physiological reaction to the atmospheric environment.

It considers:

• dry bulb temperature

• mean radiant temperature

• wind speed

• relative humidity

to calculate a reference environmental temperature causing strain when compared to an individual's response to the real environment. It is based on .'s multi-node model of thermo-regulation.

The is a function of the above parameters, which are combined in a multinode thermo-physiological model that takes into account clothing insulation and metabolic rate. From this a (UTCI) of perceived thermal stress is derived.

Clima allows the user to visualize the annual UTCI equivalent temperature as heatmap under various environmental conditions.

The UTCI temperature can be converted in a scale assessing thermal stress, displayed by Clima in a heatmap graph.

Video Tutorial

Learn more about the Outdoor Comfort tab by watching the following video.

Clima displays hourly Global and Diffuse Horizontal Solar Radiation values for a typical day for each month.

Typical daily graphs showing the amount of energy gained from the sun have many uses, such as:

• design the building with a passive approach, to control solar gains and reduce energy consumption (allow solar gain during months of heating demand and block them during periods of cooling demand, see for reference the degree days);

• manage the direct solar gain through the glass, to evaluate solar shading devices (most useful in locations with high temperatures and a strong direct component);

• manage the indirect solar gain transfer into the building with a time shift, exploiting the thermal mass, heating thick walls or concrete floors, or designing special rooms adjacent to the main spaces that rely on convection to transfer the heat, such as sunroom or ;

• evaluating sustainable renewable energy solutions such as solar thermal or photovoltaic panels.

The integral of the curves in the graphs is the total energy (in Wh/m²), supplied by the sun. Be careful in considering the

A psychrometric diagram is a psychrometry tool used to understand the relationship between humidity and air temperature conditions. Through the use of the psychrometric diagram and appropriate calculations, it is possible to know the amount of heat or cooling needed to achieve the desired temperature and humidity.

The Clima psychrometric diagram shows dry bulb temperature on the abscissae, specific humidity on the ordinates, and relative humidity as parametric curves inside the graph.

The humidity ratio is the water vapor's weight per unit weight of dry air, the so-called specific humidity. It is important not to confuse it with relative humidity. The same specific humidity value can have different relative humidity conditions by changing the air temperature.

All air conditions cannot go beyond the 100% saturation curve, which means that the air contains the maximum amount of water vapor, in certain conditions of temperature ad pressure.

The simplest transformation to be analyzed on the psychrometric diagram is the heating and cooling processes. The transition from the starting condition (1) to the final one (2) occurs horizontally, at constant humidity ratio values. The final condition (2) can be inspected as a function of the starting one.

A common application of the diagram is humidification and dehumidification of environments, where the saturation curve is used. The air is cooled to (2), and then heat continues to be removed, so condensing some of the vapor and decreasing the specific humidity until the desired value (2'). Therefore, a post-heating process could bring the air back to the starting relative humidity (3).

The main application of the psychrometric diagram is in the design of large all-air systems. The air we breathe is differentiated into dry air and humid air. Humid air, which is what is analyzed in the psychrometric diagram, is composed of dry air and water vapor. Thanks to the diagram, we can run the HVAC system on heating/cooling air and mixing humid and dry air, and know exactly what temperature and relative humidity conditions we will obtain. For instance, an adiabatic mixing of air in the two starting conditions (1-2) will obtain a new mixture (3).

The diagram is applied whenever the humidity of a particular environment needs to be studied, for reasons of thermal comfort or for the preservation of valuable objects, such as in museums.

• Global Horizontal Irradiance (GHI) is the total irradiance from the sun on a horizontal surface. It is the sum of the Diffuse Horizontal Irradiance and the Direct Normal Irradiance, projected onto the horizontal plane using the solar zenith angle (z).

• Diffuse Horizontal Irradiance (DHI) is the radiation that arrives from the entirety of the sky dome, except the solar disc. Is the radiation that has been scattered by molecules and particles in the atmosphere. It is measured on a horizontal surface

• Direct Normal Irradiance (DNI) is the measurement of the intensity of sunlight on a surface perpendicular (normal) to the sun, as such, in very clear sky conditions and low solar altitudes, the Direct Normal Irradiance can be higher than the Global Horizontal Irradiance.

Yearly chart

The annual graph allows the different months' dry-bulb temperature ranges to be evaluated. Moreover, overlaying the average value trend for each day helps visualize the differences between the minimum and maximum daily values for the investigated location.

Comfortable temperature ranges for 80% and 90% of the population, calculated according to ASHRAE adaptive comfort, are overlaid (see also the excellent CBE Thermal Comfort Tool). For each location, it is therefore possible to assess the temperature difference between outdoors and comfort conditions, or to evaluate passive free cooling strategies using outside air in the summer season. For more information on natural ventilation potential, see the dedicated page.

Building design must inevitably consider local climatic trends. Comparing the different annual trends in the previous image, keeping the comfort zone as a fixed reference point, it is very clear that we expect to find four aesthetically and functionally dramatically different buildings.

Daily chart

Monthly show all hourly temperatures. The temperature excursion is much more evident than in the annual graphs. Daily medians, i.e., the most frequently occurring values, help evaluate the outliers.

Typical monthly days show what buildings must provide to create comfortable environments. Below is an example of a comparison between four drastically opposite climates

Overall, the first observation is the climatic variability of desert and continental climates, while the other two are mostly stable at constant levels.

More in detail, imaging that we might design a building, we start from the factual need to reduce incoming heat into the environment with solar shading or other passive solutions in desert climates, to the constant need to create air movement that gives a sense of coolness in the constant tropical climates; we get to the steady temperate climates where it is easier to recreate comfortable conditions, to the continental climates, which are highly variable from summer to winter and certainly more challenging to handle.

Heatmap

Heatmap is another useful method for evaluating thermal excursion over a year (by evaluating the horizontal gradient) or over individual days (by evaluating the vertical gradient).

Albeit with different scales, the four heatmaps give a clear idea of the comparison of the four given climate types, especially for the temperature excursion between day and night.

• the desert climate, despite having a scale with a large delta T, shows clear contrasting vertical gradients, thus between day and night temperatures;

• the tropical climate has no variability throughout the year, with a nearly constant pattern. The same observation can be made for daily and nighttime temperatures;

• the temperate climate shows a certain constancy between day and night, but especially a slight increase over the summer month temperatures;

Descriptive statistics

The last tool for temperature assessment is the statistics table. The earlier graphically made evaluations can be supported by the numbers. The following are listed, for each month:

• the temperature means;

• the ;

• the minimum values;

Clima allows the user to visualize daily charts and heatmaps of all the variables listed in 'Apparent sun path for the location'.

The chart above shows the scatter plot of all hourly data on all days of the month and the typical monthly trend.

Heat maps allow the intensity of values to be perceived through color palettes. These graphs are very helpful in seeing how magnitudes vary throughout the year.

Version 0.9.0(2025-10-30)

Feat:

• Moved the top navigation bar to the left side

• Extracted the hours and months into a global filter and place it in the Sidebar

• Migrated testing framework from Cypress to Playwright

Fix:

• Fixed issues #249, #245, #159, #242: Code redundancy and CSS styling issues

• Fixed issues #248

• Fixed issues #236, #259: Sidebar issues

Version 0.8.5 (2023-04-12)

Feat:

• Added stacked bar chart Outdoor Comfort

• Added filter for the descriptive statistics table in the Data Explorer tab

Fix:

• Fixed issues 154, 156: Update the option list

• Fixed issues 157: Align the legend bar of "Thermal Stress" with the text

• Fixed issues 122

Version 0.8.0 (2023-03-27)

Feat:

• Implemented the units converter from SI to IP

• Updated the documentation

• Added reference to ArXiV paper

Fix:

• Issue calculation of the running mean outdoor temperature

• Issue cloud cover figure

Version 0.6.2 (2022-05-27)

Fix:

• Issue windrose

Version 0.6.1 (2022-04-01)

Feat:

• added more and newer EPW files from climate.onebuildings.org

• added more info in card displayed on mouse over epw file

Version 0.5.2 (2022-04-01)

Fix:

• added units to all charts

Version 0.5.0 (2021-10-14)

Fix:

• text condensation risk

• links to EnergyPlus files

Features:

• implemented responsiveness of the tool

Version 0.4.6 (2021-09-07)

Fix:

• issue with dew-point temperature filter in nat ven tab

Features:

• implemented responsive layout in some tabs

• linked GitBook documentation

• returning a warning id EnergyPlus files are not available

Version 0.4.5 (2021-08-30)

Fix:

• wind rose was not displaying correctly

Features:

• first draft of the documentation

• extracting reference years from EnergyPlus file

• added title to daily profile chart

Version 0.4.4 (2021-08-16)

Fix:

• error importing some EPW files

• error with cooling and heating degrees chart

Features:

• improved footer layout

Version 0.4.3 (2021-08-16)

Fix:

• app was crashing is Koppen data was not available

• displaying elevation correctly

Features:

• displaying info on reference years used to create EPW file

• added labels to some chart

• pop up modal now shows weather station name

Version 0.4.2 (2021-07-22)

Fix:

• display error if no data are available to plot

• saving charts with their unique names

Features:

• added more variables to plot in psy and explore tabs

• user can now invert hour and month selection

Version 0.4.1 (2021-07-08)

Fix:

• issue with natural ventilation heatmap chart

• title heatmap natural ventilation tab

Features:

• added checkbox in apply filter dew point temperature

• changed order outdoor and natural ventilation tab

• natural ventilation tab charts have now a constant y range

Version 0.4.0 (2021-07-06)

Features:

• created natural ventilation tab

Version 0.3.2 (2021-07-06)

Fix:

• meta is now a dictionary

Features:

• user can download both the EPW and the Clima df

• improved data explorer tab

• outdoor tab added images

Version 0.3.0 (2021-07-02)

Fix:

• issues in psychrometric chart tab

• changed Flask cache type

Features:

• added more links to EPW files ()

• improved layout wind tab

• changed order tabs

Version 0.2.1 (2021-06-23)

Fix:

• added Koppen-Geiger climate classification

• tooltip is now correctly displaying

Features:

• added heating and cooling degree days chart

• successfully implemented continuous deployment

• improved the layout of the application

Version 0.2.0 (2021-06-23)

Fix:

• callback error in select tab - the callback was not returning an output

• tabs are disabled until data is uploaded

• changed the name of chart when downloaded

Features:

• improved loading speed of temperature and RH tab

• user can upload a custom EPW file

• user can select and EPW directly from the map

Version 0.1.1 (2021-06-21)

Features:

• Changed look of the footer

• Added CHANGELOG

Version 0.1.0 (2021-06-14)

Features:

• Reduced loading time

• Fixed errors

• EPW data loaded persist even if the user navigates back to main page

Clima allows an estimation of the hours when indoor environments can be ventilated with outside air depending on the external temperature.

Natural ventilation is the process of introducing outdoor air into a building from the outside to improve air quality, provide fresh air and/or comfort cooling without actively conditioning the incoming airstream. Hourly air changes are required by most building regulations to ensure a healthy and smell-free environment, usually set at a minimum of one volume exchanged per hour.

In favorable climates and building types, natural ventilation can be used in combination with or as an alternative to air conditioning systems.

Clima Natural Ventilation Potential assessment is based primarily on outdoor temperatures. Natural ventilation is assumed to be possible when the outdoor air temperature is below the indoor comfort threshold and above a minimum to avoid drafts.

The maximum temperature threshold can be estimated depending on the internal loads, how many people are in the room, and how many electrical appliances. Considering the desired indoor air setpoint temperature, it can be dropped by 2 or 3 °C based on how much heat needs to be removed from the interior.

The minimum temperature threshold is typically dictated by local discomfort near the fresh air inlet source. The minimum limit to be considered may be as low as 10 °C, but a typically used value to minimize the risk of draft is 15 °C.

Clima shows by default a heatmap with all hours when the temperature is between 10 and 24 °C and a bar chart with the number of hours in which the filter was successful. The bar chart can be normalized, then displayed as a percentage of total monthly hours, or simply plotted with the total sum of the filtered hours.

Clima provides various options to customize the natural ventilation potential calculations for individual projects:

• setting the minimum and maximum outdoor air temperatures to be considered;

• selecting the time of the day or months to be analyzed;

• assessing eventual condensation risks on chilled surfaces (i.e. radiant chilled panels)

Natural ventilation can be used in combination with and in aid of radiant cooling systems. The most common risk is that condensation will form on cold surfaces, creating slippery floors or potential mold. Clima allows this control to be performed with the "surface temperature" filter, which is a function of the dew temperature.

Video Tutorial

Learn more about the Natural Ventilation tab by watching the following video.

The Sun and Clouds tab presents an overview of various climatic factors that relate to sun, solar position, intensity, and cloud cover, in particular:

• Apparent sunpath for the location (spherical and cartesian projection)

• Global and Diffuse Horizontal Solar Radiation

Apparent sun path for the location

Clima allows the user to visualize the sun path for the chosen location in spherical and cartesian projection

Clima optionally allows a variety of variables to be overlayed on either sun path type.

This allows the user to identify climatic patterns in relation to the apparent solar position. Data are plotted on the analemma.

Video Tutorial

Learn more about the Sun and Clouds tab by watching the following video.

The wind rose is used to provide a synthetic overview of wind speed and wind direction frequency distribution at a given location.

Wind speed can be estimated with several scales. One of the first was created by Britain's Admiral Sir Francis Beaufort (1805). The Beaufort scale is an empirical scale that relates wind speed to observed conditions at sea or on land. The original scale goes from 0 to 12, but the Clima Tool will show the results from 1 to 9 since it is not common to construct buildings in places with recurrent winds over 100 km/h.

Each circle segment shows the winds according to the cardinal direction along which they blow from.

The length of each radius around the circle shows how often the wind blew from that direction. A click of the mouse over each slice of the rose shows therefore the recurrence frequency in which the wind of such intensity is repeated over the analyzed period.

As most graphs in Clima Tool, the wind rose is strongly interactive. Clicking on the legend will hide or highlight the selected category. As such, it is easy to go from a wind rose showing all the wind directions and frequency to one that highlights only the selected speed range. This can be particularly useful to identify low-frequency, high-speed wind patterns.

In the seasonal graphs section, Clima shows 4 wind roses for the periods of:

• December - February;

• March - May;

• June - August;

Personal viewing periods are available using the last portion of the Wind section, where a wind rose of the desired interval can be generated.

In building design, the wind is addressed in several forms:

• assessing pedestrian and outdoor comfort;

• design for wind-driven natural ventilation;

• understanding pollution dispersal and outdoor air quality;

First off, thanks for taking the time to contribute! We use GitHub as our main collaboration platform. Please work from the development branch, create small feature branches, and open focused pull requests. Follow Conventional Commit messages (e.g., feat:, fix:, docs:), format Python code with Black, and add tests where needed. Never merge your own PR—wait for review and address all comments (including AI reviewer suggestions). Use Issues and Projects to track tasks and discussions.

This project requires Python 3.11. Do not use Python 3.12 or newer, as it may cause dependency incompatibilities, build failure or runtime errors

General Feedback

If you have a general feedback about our project, please do not open an issue but instead please fill in this

Fork & branch processing

First fork the origin repository to your own github repository, then clone the repository to your local computer.

Install the dependencies using pipenv. You will need to have pipenv installed on your machine. If you do not have it yet, please refer to .

Set up the upstream repository and check the output repositories.

The terminal should output a list:

• origin → your Fork repository

• upstream → origin repository

Check all branches.

The terminal will show a list of branches:

Pull the development branch first, and if the terminal does not notice you that you should try the second command.

Create a new branch in the development branch.

Finally update and push to your repository branch if you modify the files.

Code of Conduct

Available

Code style

Code Formatting

We use ruff to enforce the code style and code formatting. You can run it with:

To ensure that the code is formatted correctly, we use a pre-commit hook that runs Ruff before every commit. Run the following once to enable hooks in your local repo:

Hence, you will need to make sure that the code is formatted correctly before committing your changes; otherwise, the commit will fail. More information about pre-commit hooks can be found .

Code Simplicity

Strive to minimize redundancy in your code.

• Keep logic as concise as possible.

• Remove unused variables, imports, and components.

• Prefer reusable utilities to repeated patterns.

UI Modifications

For UI-related changes:

• Use wherever applicable for layout and styling consistency.

• Do not use CSS, only inline styles are allowed, but still try to minimize their use.

• Ensure visual consistency with existing components.

Testing

Before submitting a Pull Request, please make sure:

• All tests should pass.

• You have installed project dependencies:

Start the app server:

Then, from the root directory, run tests using pytest:

Submitting changes

Please send a Pull Request with a clear list of what you've done. Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:

Detailed requirements for submitting a PR are described in the section below

Classification of Common Commit Types:

• Main (Master): Stable branch, merge code that passes review and CI; merge and release every time,

• Develop: Continuous Integration branch for daily integration with multiple collaborators.

• Feature/*: feature development branch, cut out from main or develop, send PR to merge in after completing the feature.

Pull Request Regulation

Time to submit PR:

• User requirements/issues have been addressed or discussed in Issue and consensus has been reached.

• Changes have been minimised (small steps/phased submission) to avoid "mega PRs".

The pull request should include the following information:

• Description: Provide a brief summary of the changes, related issues, and motivation. List any required dependencies. Fixes # (issue)

• Type of Change: Bug fix (non-breaking); New feature (non-breaking); Breaking change; Documentation update.

• Testing: Describe how you tested your changes and how we can reproduce them. Include test details if necessary.

Pull Request Review:

• After submitting a Pull Request (PR), please @Coderabbit for review.

• Check all improvement suggestions provided by Coderabbit before requesting a final review.

Discussion of Solutions: When needed, seek feedback from collaborators Toby and Giobetti before making major design or logic decisions.

Thanks

Thank you again for being interested in this project! You are awesome!

Prerequisites

Python 3 installed on your machine and pipenv.

• If you do not have Python installed on your machine you can follow

• You can install pipenv using the following command pip install pipenv.

Installation

This guide is for Mac OSX, Linux, or Windows.

1. Get the source code from the GitHub repository

2. Create a virtual environment using pipenv and install dependencies:

3. Run tool locally

Now you should be ready to run the tool locally.

pipenv run python main.py

Visit in your browser to check it out. Note that whenever you want to run the tool, you have to activate the virtualenv first.

Adding new dependencies

Pipfiles contain information about the dependencies of your project, and supersede the requirements.txt file that is typically used in Python projects.

To install a Python package for your project use the install keyword. For example,

pipenv install beautifulsoup4

The package name, together with its version and a list of its own dependencies, can be frozen by updating the Pipfile.lock. This is done using the lock keyword,

pipenv lock

Managing your development environment

There are usually some Python packages that are only required in your development environment and not in your production environment, such as unit testing packages. Pipenv will let you keep the two environments separate using the --dev flag. For example,

pipenv install --dev nose2

Testing

This project runs both Python unit tests, and Cypress end-to-end tests in CI.

To run Python tests locally:

• If you haven't already, install Python dev dependencies.

• Then: pipenv run python -m pytest

To run Cypress locally:

• If you haven't already, start the Clima application and confirm that http://localhost:8080/ is up.

• Then: cd tests/node; npm install; npm run cy:open

Versioning

When you release a new version of the tool you should first use bumpversion to update the version of the tool. You can use the following command:

If the above command do not work even if you have committed all the files try with bumpversion patch --allow-dirty

Secondly, you should describe the changes in CHANGELOG.md

Deploy to Google Cloud Run

You need to have installed on your computer. A short guide on how to deploy on Google Cloud Run can be found .

First make sure you that:

• gcloud is up-to-date

• that you are logged in with the right account

• you have updated the Pipfile.lock.

First test the application.

Deploy test version manually using gcloud and docker locally - quicker and great to test small changes

Deploy test version of the project

Deploy main version of the project

The UTCI tab allows users to analyze outdoor thermal comfort for a combination of different meteorological conditions based on the presence or absence of sun and wind.

Clima leverages the several models implemented in Pythermalcomfort.

• The "Solar gain on people" calculates the solar gain to the human body, so the mean radiant temperature. To simulate a sunless situation, Clima considers the person surrounded by surfaces that shade him, all of which tend toward dry bulb temperature;

• Wind data is obtained directly from the weather file. The windless situation sets the value at 0.5 m/s, which is the minimum value allowed by the UTCI model.

The UTCI can then be visualized for the entire year for the scenario chosen.

The values are then converted into a scale assessing thermal stress, either because of cold or heat. Therefore, a second chart maps if people will experience thermal stress for all the hours of the year for corresponding UTCI temperatures.

The UTCI is a useful tool to design the outdoor space, to maximize the number of comfortable hours. The designer can influence two factors out of the four driving outdoor comfort: radiant temperature (i.e. exposure to the sun) and wind speed (i.e. exposure to the wind).

Clima allows the user to visualize all annual weather conditions on a psychrometric diagram.

The default diagram allows the users to overlay the frequency with which weather conditions recur throughout the year.

With the first choice in the drop-down list, "None", it is possible to view temperature conditions in the psychrometric diagram over the entire year. The visualized dots have the same gradient with a transparency rate, they are not colored according to a legend. Multiplying them when overlaid provides a visualization of their frequency, so the most common conditions.

Then, users can overlay another variable on the graphs, choosing from Clima dataframe.

Moreover, data can be filtered by date, time, or one of the variables.

Video Tutorial

Learn more about the Psychrometric tab by watching the following video.