Package: climex
CLIMEX TutorialÁngel Marqués-Mateu1, Azucena Pérez-Vega2, Adolfo Molada-Tebar31Universitat Politècnica de València (España) (amarques@cgf.upv.es)2Universidad de Guanajuato (México)3Universidad de Salamanca (España)InstallationCLIMEX can be installed usingpip$pipinstallclimexIntroductionCLIMEX is a Python package intended to support Climate Change computations and analyses from datasets hosted at theCONAGUAweb site. CLIMEX is primarily intended to support climate research in México.The typical workflow in CLIMEX takes the following steps:Import CLIMEXCreate a CLIMEX projectConfigure the set of stations and baselineDownload data filesPass quality controlCompute climate indicesExport data to tabular or map formatsSections below explain each step in detail.1. Import CLIMEXIn order to use CLIMEX, import the package as usual:>>>importclimexWhen CLIMEX is imported for the first time, it creates a folder in the local disk and a number of files using contents from the CONAGUA web site.2. Create a CLIMEX projectThe CLIMEX package defines a number of classes, but users should interact with one only class namedProject(). There are different ways to create a project, the easiest is to create a new, empty project as follows:>>>test=climex.Project('test')where'test'is a text string containing the name of the project. This line creates an instance of the classProject()which can be accesed by labeltestand a folder on the local disk to store data. In order to see the contents of the project, just type the variable name:>>>test{"created":"2022-05-13 12:39:08","updated":"2022-05-13 12:39:08","operating":true,"baseline":[1961,1990],"stations":[]}At this point, the project is almost empty; it has creation and updating dates, a default baseline 1961-1990 and no stations.3. Basic configuration: stations and baselineThe next step is to add stations to the project. In this example, we add several stations from Guanajuato with IDs 11020, 11025, 11040, 11045, 11053 and 11095. Thestationsproperty is used to add stations to the project.>>>test.stations=[11020,11025,11040,11045,11053]>>>test{"created":"2022-05-15 09:34:53","updated":"2022-05-15 09:35:15","operating":true,"baseline":[1961,1990],"stations":["11020","11025","11040","11045","11053"]}Users can add more stations at any time. If we want to add a new station with ID=11095 we type the following line.>>>test.stations=11095>>>test{"created":"2022-05-15 09:34:53","updated":"2022-05-15 09:36:52","operating":true,"baseline":[1961,1990],"stations":["11020","11025","11040","11045","11053","11095"]}The baseline can be updated using the correspondingbaselineproperty.>>>test.baseline=[1971,2000]>>>test{"created":"2022-05-15 09:34:53","updated":"2022-05-15 09:38:33","operating":true,"baseline":[1971,2000],"stations":["11020","11025","11040","11045","11053","11095"]}4. Download climate dataAfter tuning the parameters of the project, the next step is to download the data from the CONAGUA web site using the.download()method of theProject()instance.>>>test.download()Downloadinghttps://smn.conagua.gob.mx/tools/RESOURCES/Diarios/11020.txt[200]Downloadinghttps://smn.conagua.gob.mx/tools/RESOURCES/Diarios/11025.txt[200]Downloadinghttps://smn.conagua.gob.mx/tools/RESOURCES/Diarios/11040.txt[200]Downloadinghttps://smn.conagua.gob.mx/tools/RESOURCES/Diarios/11045.txt[200]Downloadinghttps://smn.conagua.gob.mx/tools/RESOURCES/Diarios/11053.txt[200]Downloadinghttps://smn.conagua.gob.mx/tools/RESOURCES/Diarios/11095.txt[200]The label[200]means that the corresponding HTTP request worked well. However, it should be noted that network transactions (the download of files being a good example) can fail due to server side causes that are out of user control. Particularly, if you see any SSL related issues, please go toSSLlink and check the details to install the SSL certificate in the Python local environment.Users can check the contents in the project folder. In order to keep track of the files in a project we can use thecontents()method.>>>test.contents()[/home/climex/.climex/PROJECTS/CEAG/CONAGUA]11020.txt11025.txt11040.txt11045.txt11053.txt11095.txt[/home/climex/.climex/PROJECTS/CEAG/CLIMDEX]11020.txt11020_1971_2000.txt11025.txt11025_1971_2000.txt11040.txt11040_1971_2000.txt11045.txt11045_1971_2000.txt11053.txt11053_1971_2000.txt11095.txt11095_1971_2000.txtThe output ofcontents()shows that there are files in two
subfolders with datasets in two formats:The original CONAGUA formatThe well-known Climdex input format (SeeClimdex User's Guide. Appendix C)Note that in the particular case of the Climdex format, there is a file per station with data in the baseline period, in addition to the file with all the data. Filenames provide an overview of the file contents.5. Quality controlAfter the data download, it is convenient to check for missing data and other mistakes using the.qc()method. This method accepts a named plot parameter to create plots of the time series. Note that creating the plot graphical files may take a while.>>>test.qc(plot=True)RunningQConstation"11020"[OK]RunningQConstation"11025"[OK]RunningQConstation"11040"[OK]RunningQConstation"11045"[OK]RunningQConstation"11053"[OK]RunningQConstation"11095"[OK]The.qc()method generates new files in the folder structure of the project. We can locate those files usingcontents().>>>test.contents()......[/home/climex/.climex/PROJECTS/CEAG/QC]11020_1971_2000_qc0.json11020_1971_2000_qc_prcp.png11020_1971_2000_qc_temp.png11025_1971_2000_qc0.json11025_1971_2000_qc_prcp.png11025_1971_2000_qc_temp.png11040_1971_2000_qc0.json11040_1971_2000_qc_prcp.png11040_1971_2000_qc_temp.png11045_1971_2000_qc0.json11045_1971_2000_qc_prcp.png11045_1971_2000_qc_temp.png11053_1971_2000_qc0.json11053_1971_2000_qc_prcp.png11053_1971_2000_qc_temp.png11095_1971_2000_qc0.json11095_1971_2000_qc_prcp.png11095_1971_2000_qc_temp.pngThere is a JSON file and two PNG files per station. Plots in PNG files allow easily detecting missing data which are plotted in grey colour, whereas precipitation and temperature data that are plotted in blue or red. Figure 1 shows several years from 1992 to 1997 with very few data (some of those years have actually no available data).6. Compute climate indicesThe list of common indices in climate change research are located in theClimdexweb site. There are 17 heat/cold indices and 13 precipitation indices.The CLIMEX module provides information about climate indices by means of theinfo()function. In order to see the whole list of indices run this functions without any arguments:>>>climex.info()['FD','SU','ID','TR','GSL','TXX','TNX','TXN','TNN','TN10P','TX10P','TN90P','TX90P','WSDI','CSDI','DTR','ETR','RX1DAY','RX5DAY','SDII','R10MM','R20MM','RNNMM','CDD','CWD','R95P','R99P','R95PTOT','R99PTOT','PRCPTOT']The detailed explanation of a given index is available by providing the specific index name as a parameter to functioninfo():>>>climex.info('su')SU:NumberofsummerdaysAnnualcountofdayswhenTX(dailymaximumtemperature)>25°C.LetTXijbedailyminimumtemperatureondayiinyearj.CountthenumberofdayswhereTXij>25°C.TheProject()class has a.compute_index()method that conducts all the computations needed to determine climate indices. This method requires the name of the index to be computed and can optionally create plots of the indices. The following line computes the SU index at all stations of the project and create the corresponding plots.>>>test.compute_index('su',plot=True)Computingindex"SU"onstation"11020"[OK]Computingindex"SU"onstation"11025"[OK]Computingindex"SU"onstation"11040"[OK]Computingindex"SU"onstation"11045"[OK]Computingindex"SU"onstation"11053"[OK]Computingindex"SU"onstation"11095"[OK]The output of the.compute_index()method consists of JSON and PNG files. There is a JSON, and optionally a PNG file, per any station/index pair. Output files can be listed using.contents()as in previous examples.>>>test.contents()...[/home/climex/.climex/PROJECTS/TEST/INDEX]11020_1971_2000_02_SU.json11020_1971_2000_02_SU.png11025_1971_2000_02_SU.json11025_1971_2000_02_SU.png11040_1971_2000_02_SU.json11040_1971_2000_02_SU.png11045_1971_2000_02_SU.json11045_1971_2000_02_SU.png11053_1971_2000_02_SU.json11053_1971_2000_02_SU.png11095_1971_2000_02_SU.json11095_1971_2000_02_SU.png...Figure 2 contains the graphical output of the SU index. Note the absence of data points in years 1992 to 1997. The plot includes the data and the regression line so that users can see the trend of the index over the years (for a discussion of hypotehsis testing of the regression slope see thisstattreklink).Another useful way of visualising climate data is by using a map. CLIMEX provides basic map visualisation with the method.osm()using theOSMbase map on an HTML file:>>> test.osm(browser=True, climate_index='su', missing=True)The.osm()method has three parameters to:Show the HTML code on a web browser. The default value is True, which means that the HTML will be shown on the default wbe browser in the local system. Set to False only specific working environments such as Jupyter, which do not need a browser to render HTML files.Set the climate index data joined to weather stations.Print points in different colours, depending on the number of missing data in the climate index dataset.The result of.osm()is an HTML pointmapof the stations included in the project.7. ExportThe last step in a CLIMEX project is to export the data to a specific format. Theexport()method allows exporting geographic coordinates, index values and other
attributes to CSV, GeoJSON and Spahefile formats. These formats allows users to process climate datasets in other computing environments and combine them with other external datasets. Statistical packages and geographic information systems are known examples of such computing environments.8. SSL certificates