Usage

Currently, python-TAMER is only compatiable with the Vuilleumier et al. 2020 UV climatology for Switzerland. This dataset is currently only availabe on request, but will soon be released publicly.

To use python-TAMER in a project:

import python_tamer

There are currently two major classes in python-TAMER, SpecificDoses and ExposureMap. Each class has an associated workflow designed to produce tablular and map outputs respectively. Every object created by one of these classes has two critical properties, data_directory and src_filename_format. These describe the location and filename format of the Vuilleumier et al. UV climatology. Users must ensure these properties are correct for each class object they create. Below we describe in general terms the approach taken by these classes. For examples of raw code, see the Code Reference.

Calculating specific doses

The SpecificDoses class is essentially a table listing the key information to perform a dose estimation. In the context of UV, this can be used in tandem with or as a substitute for tradition dosimetry measurements. See Harris et al. 2021 for more information on this approach.

To get started with the SpecificDoses class, prepare a pandas DataFrame (i.e. a table) with columns for Latitude, Longitude, Date, ER, and Schedule. Each row of this table represents an exposed individual and the columns provide the corresponding details needed to estimate their total daily UV dose. The ER column refers to the Exposure Ratio of the exposed individual. This information is not always readily available, and so the SpecificDoses class includes the ER_from_posture() function that calculates an ER column based on Posture and Anatomic_zone columns. Similarly, the Schedule column refers to the Exposure Schedule, a 24-length vector describing the proportion of each hour spent outdoors. Often it is easier to simply list and start time and end time for a given exposure period, so we have included the schedule_constant_exposure() function which generates a Schedule column based on Time_start and Time_end columns.

Once the SpecificDoses table is prepared, the calculate_specific_doses() function can be applied to append Ambient_dose and Personal_dose columns to the table.

Generating maps of exposure information

The ExposureMap class is designed to calculate more general information about doses or UV radiation intensity. The idea is to generate what we refer to as “pixel histograms”, those are histograms of UV intensity or UV doses for each spatial pixel available in the dataset. By using histograms, python-TAMER is able to collect large distributions of data per pixel with relatively low memory requirements, ensuring that these calculations can be performed on personal computers with as little as 4GB of RAM. The data is loaded using the collect_data() function, which goes through the dataset one file at a time, loading the relevant data, performing any necessary calculations (such as applying an exposure schedule to calculate a dose or performing unit conversions), and then discretising the results and adding that information to the pixel histograms.

Once the relevant data has been collected into pixel histograms, the calculate_map() function can be used to calculate a descriptor quantity for each histogram. These descriptors can be simple, such as the mean or median of the histograms. They can also be more advanced, such as percentiles or the standard deviation. This gives a single number per pixel, stored as an array, that can then be rendered as a colour map using the plot_map() function.