Code Reference¶

ExposureMap module¶

class python_tamer.ExposureMap.ExposureMap(units='SED', exposure_schedule=1, statistic='mean', bin_width=None, date_selection=None, map_options=None, src_filename_format='UVery.AS_ch02.lonlat_yyyy01010000.nc', src_directory='C:/Data/UV/')[source]¶

Bases: object

A class for calculating maps based on user specifications

Each instance of this class contains information required to calculate and illustrate a map of exposure information, be that simple averages or more advanced mathematical representations of exposure risk. The class is designed to have three core functions run in sequence, with room for flexibility should more advanced users desire it. First, the data is read and a pixel histogram is calculated. This allows much more data to be stored in memory and is the basis for performing this kind of data analysis on personal computers.

Parameters

units (str) – The units of the quantity to be mapped. Must be “SED”, “J m-2” or “UVIh” for doses or “UVI”, “W m-2” or “mW m-2” for irradiances. Defaults to “SED”.
exposure_schedule (array) – A vector of values describing the relative exposure of each hour of the day. 0 indicates no exposure, 1 indicates full exposure, and a fractional value such as 0.5 would indicate exposure for a total of 30 minutes within the hour, or a 50% partial exposure for the full hour, or anything equivalent. Values greater than 1 are allowed. Must have a length of 24 (for each hour of the day) although a length of 1 is also allowed, in which case that number will be immediately replicated across a 24-length vector. When not calculating doses, hours with any non-zero entry in this vector are included, with the irradiance values being multiplied by the corresponding non-zero value in the exposure schedule.
bin_width (float) – The width of each bin in the pixel histogram. Value assumed to be in the same units as defined by the units parameter. Making bin_width excessively small can lead to high memory usage, consider the underlying accuracy of the source data and be sure not to substantially exceed its precision with this parameter.
statistic (str) –
The statistical descriptor to be calculated from the pixel histograms to be later represented on the rendered map. Must contain at least one of these keywords: “mean”, “median” or “med”, “sd” or “std” or “stdev”, “max” or “maximum”, “min” or “minimum”.

Planned: the string can be a formula using any of the keywords above, as well at “prct” or “percentile” preceeded by a number between 0 and 100, and basic mathematical operators (+, -, , /, *) and numeric factors.
date_selection (list of dates) – The dates for which the irradiances are retrieved or the daily doses are calculated. Defaults to None whereby the program selects all data within the src_directory that matches the src_filename_format.
src_filename_format (str) – Describes the filename of the netCDF files containing the data with ‘yyyy’ in place of the year.
src_directory (str) – The directory where the data is stored. Must end with a slash.

Example

The code below shows a typical use case for the ExposureMap class. The long-term average daily doses (i.e. the chronic doses) for typical school children are calculated across Switzerland asssuming certain hours of exposure for journeying to and from school and having breaks for morning tea and lunch time.

import python_tamer as pt
import pandas as pd
import numpy as np
src_directory = 'C:/enter_your_src_directory_here'
ER = pt.ER_Vernez_2015("Forehead","Standing") # Long-term average ER for foreheads in standing posture
map = pt.ExposureMap(
    src_directory=src_directory,
    units = "J m-2",
    exposure_schedule = np.array([0  ,0  ,0  ,0  ,0  ,0  ,
                        0  ,0  ,0.5,0  ,0.5,0  ,
                        0.5,0.5,0  ,0  ,0.5,0  ,
                        0  ,0  ,0  ,0  ,0  ,0  ])*ER,
    bin_width = 25,
    date_selection = pd.date_range(start="2005-01-01",end="2014-12-31"),
    statistic = "mean",
    map_options={"title": "Chronic daily UV dose for typical school children, 2005-2014",
                "save": False})
map = map.collect_data().calculate_map()
map.plot_map()

calculate_map(pix_hist=None, statistic=None, bin_centers=None)[source]¶

Calculates statistical descriptor values for pixel histograms to produce a map

This function interprets the statistic string, which can either be a simple command such as “mean” or a more advanced formula of keywords. The corresponding function is applied to each pixel of the pix_hist object within the ExposureMap class, essentially removing the first dimension and resulting in straightforward map to be plotted.

Parameters

pix_hist (array) – A 3D array with the first dimension containing vectors of counts for histograms and the next two dimensions serving as pixel coordinates. See ExposureMap.collect_data() for more information.
statistic (str) –
The statistical descriptor to be calculated from the pixel histograms to be later represented on the rendered map. Must contain at least one of these keywords: “mean”, “median” or “med”, “sd” or “std” or “stdev”, “max” or “maximum”, “min” or “minimum”.

Planned: the string can be a formula using any of the keywords above, as well at “prct” or “percentile” preceeded by a number between 0 and 100, and basic mathematical operators (+, -, , /, *) and numeric factors.
bin_centers (array) – The central numeric values corresponding to the bins in pix_hist. The ExposureMap.collect_data function typically calculates these values from the given bin_width input.

Returns

The ExposureMap class object is appended with a map field containing a 2D array

Return type

python_tamer.ExposureMap

Example

In the example below, the user imports some pre-calculated pixel histograms, thereby completing the ExposureMap workflow without using the ExposureMap.ExposureMap.collect_data() function. This can be useful if the data collection is timely and the user wants to produce multiple different maps. Note that the “custom data” used in this example is not included in the python-TAMER package, this simply illustrates a unique use-case.

import python_tamer as pt
# load custom data from an external file (not included)
from custom_user_data import pix_hist, bin_centers, map_options
map = pt.ExposureMap(map_options = map_options)
map = map.calculate_map(
    statistic = "median",
    pix_hist = data,
    bin_centers = bin_centers
).plot_map(save = False)
map.calculate_map(statistic = "max").plot_map(map_options={"save" = False})
map.calculate_map(statistic = "std").plot_map(map_options={"save" = False})

collect_data(src_directory=None, src_filename_format=None, date_selection=None, units=None, exposure_schedule=None, bin_width=None)[source]¶

Loads and manipulates data into histograms for each pixel of the underlying data

In order to handle large amounts of data without exceeding memory limitations, files are loaded one at a time and the time dimension is removed, either by calculating daily doses or by simply taking the data as is. The resulting information is then stored not as a list of specific values but rather binned into a histogram for each pixel. This process is repeated for each file required by the user input, building up the pixel histograms with more information that does not require additional memory.

Parameters

src_filename_format (str) – Describes the filename of the netCDF files containing the data with ‘yyyy’ in place of the year.
src_directory (str) – The directory where the data is stored. Must end with a slash.
date_selection (list of dates) – The dates for which the irradiances are retrieved or the daily doses are calculated. Defaults to None whereby the program selects all data within the src_directory that matches the src_filename_format.
units (str) – Name of units of desired output. This also indicates whether daily doses must be calculated or not. Units of “SED”, “J m-2”, or “UVIh” will produce daily doses, units of “UVI”, “W m-2” or “mW m-2” will not.
exposure_schedule (array) – A vector of values describing the relative exposure of each hour of the day. 0 indicates no exposure, 1 indicates full exposure, and a fractional value such as 0.5 would indicate exposure for a total of 30 minutes within the hour, or a 50% partial exposure for the full hour, or anything equivalent. Values greater than 1 are allowed. Must have a length of 24 (for each hour of the day) although a length of 1 is also allowed, in which case that number will be immediately replicated across a 24-length vector. When not calculating doses, hours with any non-zero entry in this vector are included, with the irradiance values being multiplied by the corresponding non-zero value in the exposure schedule.
bin_width (float) – The width of each bin in the pixel histogram. Value assumed to be in the same units as defined by the units parameter. Making bin_width excessively small can lead to high memory usage, consider the underlying accuracy of the source data and be sure not to substantially exceed its precision with this parameter.

Returns

The input ExposureMap object is appended with new fields, pix_hist contains the counts for the histogram, and bin_edges, bin_centers, and num_bins all serve as metadata for the pixel histograms. lat and lon are also added from the multi-file dataset to inform the pixel locations for map making further down the typical pipeline.

Return type

python_tamer.ExposureMap

Example

The example code below shows how an ExposureMap class can be declared with the default parameters that can then be later redefined by collect_data() and the other class functions.

import python_tamer as pt
import pandas as pd
import numpy as np
src_directory = 'C:/enter_your_src_directory_here'
ER = pt.ER_Vernez_2015("Forehead","Standing") # Long-term average ER for foreheads in standing posture
map = pt.ExposureMap()
map = map.collect_data(
    src_directory=src_directory,
    units = "J m-2",
    exposure_schedule = np.array([0  ,0  ,0  ,0  ,0  ,0  ,
                         0  ,0  ,0.5,0  ,0.5,0  ,
                         0.5,0.5,0  ,0  ,0.5,0  ,
                         0  ,0  ,0  ,0  ,0  ,0  ])*ER,
    bin_width = 25,
    date_selection = pd.date_range(start="2005-01-01",end="2014-12-31")
)
map = map.calculate_map(statistic = "mean")
map.plot_map(map_options={"title": "Chronic daily UV dose for typical school children, 2005-2014",
                          "save": False})

plot_map(map_options=None)[source]¶

Renders and optionally saves a map of the map field in an ExposureMap object

This function caps off the typical workflow for the ExposureMap class by rendering the contents of the map field. Many aesthetic factors are accounted for, contained within the ExposureMap.map_options dictionary.

Parameters

map_options (dict, optional) –

A collection of many typical options such as image and font sizes, colormaps, etc. The full range of options is listed below with their default values.

”title” : “Test map” The title to be rendered above the map. Can be left blank for no title. Can be used to inform img_filename

”save” : True Boolean to declare whether the map should be saved as an image file or not.

”img_size” : [20,15] The size [width,height] of the image in cm.

”img_dpi” : 300 The dots per inch of the saved image.

”img_dir” : “” The directory for the image to be saved in, leaving it blank should result in images being saved in the working directory.

”img_filename” : “timestamp” The image filename as a string. The default value of “timestamp” is a keyword indicating that the function should generate a filename based on the time at the moment of the calculation, specified with the format %Y%m%d_%H%M%S_%f which includes millisecond precision.

”img_filetype” : “png” The image filetype, must be acceptable to matplotlib.pyplot.savefig().

”brdr_nation” : True Boolean for drawing national borders on the map.

”brdr_nation_rgba” : [0,0,0,0] The red, green, blue, and alpha values for the national borders.

”brdr_state” : False Boolean for drawing state borders as defined by Natural Earth dataset.

”brdr_state_rgba” : [0,0,0,0.67] The red, green, blue, and alpha values for the national borders.

”cmap” : “jet” The name of the colourmap to be used when rendering the map.

”cmap_limits” : None The numeric limits of the colourmap. Defaults to None, where the lower and upper limits of the plotted data are used as the colourmap limits.

”cbar” : True Boolean for rendering a colourbar.

”cbar_limits” : None The numeric limits of the colourbar. Defaults to None, where the lower and upper limits of the plotted data are used as the colourbar limits.

Returns

Returns the ExposureMap object that was input with an updated map_options field (if the user has specificied any changes to the default map_options).

Return type

python_tamer.ExposureMap

class python_tamer.ExposureMap.ExposureMapSequence(src_filename_format='UVery.AS_ch02.lonlat_yyyy01010000.nc', src_directory='C:/Data/UV/', units=None, bin_width=None, map_options=None)[source]¶

Bases: object

Class for generating multiple Exposure Maps in a single operation

The ExposureMapSequence class is a framework for generating multiple maps following a given sequence. The basic workflow begins by declaring an object of this class and collecting the data from the source NetCDF files. The process is designed with memory efficiency in mind, so data is loaded one year at a time and put into pixel histograms akin to the ExposureMap class behaviour. However, in this class we allow for multiple histograms to be stored within a single ExposureMapSequence object. Next, the maps are calculated by the calculate_maps function. Multiple maps can be calculated for each histogram if the user has specified multiple statistics that they want to calculate. Lastly, the maps are rendered and saved by the save_maps function.

Parameters

src_filename_format (str) – Describes the filename of the netCDF files containing the data with ‘yyyy’ in place of the year.
src_directory (str) – The directory where the data is stored. Must end with a slash.

Example

In this example, we produce a basic sequence of monthly average doses for 2020:

example = ExposureMapSequence()
example = example.collect_data('monthly',year_selection=[2020],units=["SED"])
example = example.calculate_maps(statistic='Mean')
example.save_maps(save=True,show=True)

In this example, we produce a basic sequence of annual average doses for each year of the dataset:

example = ExposureMapSequence()
example = example.collect_data(['annual'],year_selection=[0],units=["SED"])
example = example.calculate_maps(statistic='Mean')
example.save_maps(save=True,show=True)

calculate_maps(statistic=None, titles=None, filenames='auto')[source]¶

Calcualte the maps from the pixel histograms

This function calculates maps from the pixel histograms and generates titles and filenames for each map. Note that the number of maps can be greater than the number of pixel histograms if more than one statistic is specified.

Parameters

statistic (list, str) –
The statistical descriptor to be calculated from the pixel histograms to be later represented on the rendered map. Must contain at least one of these keywords: “mean”, “median” or “med”, “sd” or “std” or “stdev”, “max” or “maximum”, “min” or “minimum”. The keyword “prct” or “percentile” is also accepted so long as it is preceded by a two-digit integer specifying the desired percentile from 01 to 99.

Planned: the string can be a formula using any of the keywords above, and basic mathematical operators (+, -, , /, *) and numeric factors.
titles (list, optional) – If the user does not wish to use the automatically generated map titles, they can enter them with this parameter. This must be a list of strings with a length equal to the number of maps produced.
filenames (str, optional) – Filenames are generated to match the titles by default, but the user can alternatively enter them manually with this parameter.

Returns

The object is appended with maps, map_specs, and num_maps fields.

Return type

ExposureMapSequence

Example

In this example, we produce a basic sequence of annual average doses for each year of the dataset:

example = ExposureMapSequence()
example = example.collect_data(['annual'],year_selection=[0],units=["SED"])
example = example.calculate_maps(statistic='Mean')
example.save_maps(save=True,show=True)

collect_data(day_selection, exposure_schedule=[1.0], year_selection=[0], units=['SED'], bin_width=None)[source]¶

Loads data into multiple pixel histograms

This function loads all of the necessary data and compiles it into one or multiple histograms. All parameters are designed to be interpreted as lists of arrays or lists of strings, where each list entry corresponding to a different histogram in the sequence. So to create a sequence of maps corresponding to the months of the year, the day_selection input would be a list of 12 arrays, the first containing numbers from 1 to 31, the second containing numbers from 32 to 59, and so on.

The user specifies the day_selection and the year_selection as two separate numerical inputs, rather than specifying dates. This make the interpretation of the sequence simpler. However, to simplify the user experience, the day_selection input can include keywords to be automatically interpreted as days of the year.

Parameters

day_selection (list, str, array) –
A list of arrays and/or strings. Keywords interpretable in such a list include the (english) names of the 12 months (at least the first three letters), the names of the four seasons (fall or autumn is accepted), or the words “year” or “annual” to indicate the full year. These keywords are replaced by the corresponding array of days in the year. Note that the 29th of February is removed from consideration should it arise. Note also that the seasons are the meteorological seasons, i.e. the three month blocks JJA, SON, DJF, and MAM for summer, autumn, winter, and spring respectively.

The user can alternatively enter a special string instead of a list. The string “monthly” generates a list of 12 arrays according to the months whereas the string “seasons” generates a list of 4 arrays according to the four seasons.
exposure_schedule (list, float, int, dict, array) –
If the user enters a float, this float value will be repeated across a length-24 array to make the exposure schedule. For example, entering 1.0 (not 1) will generate an array of 24 ones.

If the user enters an int, i, a length-24 array of zeroes will be generated with the ith entry being set to 1. For example, entering 1 (not 1.0) will generate an array that reads [0,1,0,0…] (length 24).

If the user enters a dict, they can specify the values of a few particular entries in a length-24 array where unspecified entries have a value of zero. For example, entering {0:0.5, 2:0.8, 3:1} will generate and array the reads [0.5, 0, 0.8, 1, 0…] (length 24).

If the user enters an array, it must be 1 dimensional with length 24 or 2 dimensional with the second dimension having length 24 (allowing the user to specify multiple schedules).

If the user enters a list, each entry of that list is interpreted using the rules listed above, with the caveat that arrays within a list cannot be 2 dimensional.

year_selectionlist, array, int: The years across which the data should be pulled. Input should be a list of arrays of ints corresponding to years available in the dataset. Each list entry corresponds to a pixel histogram. The user can enter 0 as a shortcut for using all available years. For example, an input might be [numpy.arange(2010,2020),[0],0]. The first list entry is an array of a decade of years, straightforward enough. The second list entry is [0]. This is equivalent to writing numpy.arange(2004,2021) i.e. it produces an array of the available years of the dataset. The last entry is 0, this produces a sequence of individual years. So the input could be equivalently written as [numpy.arange(2010,2020),numpy.arange(2004,2021), numpy.array([2004]),numpy.array([2005]),numpy.array([2006])…] and so on until 2020.
unitslist, optional: The list of units for each pixel histogram. Acceptable strings are “SED”, “J m-2”, “UVIh”, “UVI”, “W m-2”, and “mW m-2”. Defaults to SED.
bin_widthlist, optional: The bin width for each histogram. By default, these values are defined automatically according to the units input.

Returns: The object has the hist_specs and hists fields added detailing the pixel histograms.
Return type: ExposureMapSequence

Example

In this example, we produce a basic sequence of monthly average doses for 2020:

example = ExposureMapSequence()
example = example.collect_data('monthly',year_selection=[2020],units=["SED"])
example = example.calculate_maps(statistic='Mean')
example.save_maps(save=True,show=True)

In this example, we produce a basic sequence of annual average doses for each year of the dataset:

example = ExposureMapSequence()
example = example.collect_data(['annual'],year_selection=[0],units=["SED"])
example = example.calculate_maps(statistic='Mean')
example.save_maps(save=True,show=True)

interpret_parameters()[source]¶

Interprets some parameter inputs and adjusts for consistency

This function will check that parameters are correctly entered and do some basic interpretation. It checks the exposure_schedule, year_selection, units, and bin_width input. All input is converted to lists as required.

save_maps(map_options=None, save=None, show=True, match_cmap_limits=True, schedule_diagram=True)[source]¶

Renders and saves the pre-calculated maps stored in the object

With the maps calculated, this function renders the maps with broad flexibility on aesthetic options. It is mostly a wrapper for the render_map function.

Parameters

map_options (dict, optional) – A dictionary containing options for the render map function.
save (bool, optional) – Although technically contained within map_options, this option is here so users can more easily say whether they want the images to be saved or not.
show (bool, optional) – An option to show the maps in a python figure window or not.
match_cmap_limits (bool, optional) – When producing multiple maps, it can sometimes be desirable for the colormap limits to be consistent across the set of images. This boolean enables that.
schedule_diagram (bool, optional) – If true, a circular diagram is rendered on the map illustrating the schedule that generated the map.

python_tamer.ExposureMap.calculate_map_from_hists(pix_hist, statistic, bin_centers)[source]¶

python_tamer.ExposureMap.gen_map_title(statistic=None, exposure_schedule=None, hour=None, units=None, year_selection=None, day_selection=None, filename=False, **kwargs)[source]¶

python_tamer.ExposureMap.render_map(map, lat=None, lon=None, title=None, save=True, show=True, schedule=None, schedule_bbox=(- 0.03, 0, 1, 0.91), img_filename=None, img_dir='', img_size=[20, 15], img_dpi=300, img_filetype='png', brdr_nation=True, brdr_nation_rgba=[0, 0, 0, 1], brdr_state=True, brdr_state_rgba=[0, 0, 0, 0.75], cmap='gist_ncar', cmap_limits=None, cbar=True, cbar_limits=None, cbar_label=None, country_focus='CHE', gridlines=True, gridlines_dms=False, mch_logo=True)[source]¶

Renders and saves maps

Renders and saves maps with a wide variety of aesthetic options.

Parameters

map (array) – The map to be rendered
lat ([type], optional) – [description], by default None
lon ([type], optional) – [description], by default None
title ([type], optional) – [description], by default None
save (bool, optional) – [description], by default True
show (bool, optional) – [description], by default True
schedule ([type], optional) – [description], by default None
schedule_bbox (tuple, optional) – [description], by default (-0.03,0,1,0.91)
img_filename ([type], optional) – [description], by default None
img_dir (str, optional) – [description], by default “”
img_size (list, optional) – [description], by default [20,15]
img_dpi (int, optional) – [description], by default 300
img_filetype (str, optional) – [description], by default “png”
brdr_nation (bool, optional) – [description], by default True
brdr_nation_rgba (list, optional) – [description], by default [0,0,0,1]
brdr_state (bool, optional) – [description], by default True
brdr_state_rgba (list, optional) – [description], by default [0,0,0,0.75]
cmap (str, optional) – [description], by default “gist_ncar”
cmap_limits ([type], optional) – [description], by default None
cbar (bool, optional) – [description], by default True
cbar_limits ([type], optional) – [description], by default None
cbar_label ([type], optional) – [description], by default None
country_focus (str, optional) – [description], by default “CHE”
gridlines (bool, optional) – [description], by default True
gridlines_dms (bool, optional) – [description], by default False
mch_logo (bool, optional) – [description], by default True

python_tamer.ExposureMap.schedule_clock(axes, schedule, title=None, title_size=9, center=0.25, rmax=1)[source]¶

Generates a clock-style representation of an exposure schedule

[extended_summary]

Parameters

axes (matplotlib.axes.Axes) – The polar axes upon which the clock will be plotted
schedule (list or numpy.ndarray) – The exposure schedule - a length-24 vector of hourly exposure proportions
title (str, optional) – Title of the exposure clock
title_size (int, optional) – [description], by default 9
center (float, optional) – [description], by default 0.25
rmax (int, optional) – [description], by default 1

Returns

[description]

Return type

[type]

SpecificDoses module¶

class python_tamer.SpecificDoses.SpecificDoses(data=None, index: Optional[Collection] = None, columns: Optional[Collection] = None, dtype: Optional[Union[ExtensionDtype, str, numpy.dtype, Type[Union[str, float, int, complex, bool, object]]]] = None, copy: bool = False)[source]¶

Bases: pandas.core.frame.DataFrame

A class for specific dose estimates akin to dosimetry measurements

High resolution data allows for personal and ambient dose estimation without the need for direct measurement. This class is structured like a table with a set of functions to add columns ultimately leading to dose estimates. Each row of this table represents a specific exposure instance, i.e. an individual at a specific location for a specific date and time with a specific exposure ratio. See Harris et al. 2021 (https://doi.org/10.3390/atmos12020268) for more information on calculations appropriate for this class.

Parameters

src_filename_format (str) – Describes the filename of the netCDF files containing the UV data with ‘yyyy’ in place of the year.
src_directory (str) – The directory where the data is stored. Must end with a slash.

Notes

Presently, the class is inherited from a pandas.DataFrame which is somewhat restrictive and will likely be revised in a later update. For the time being, this means that the parameters cannot be set when initialising a SpecificDoses object, they must instead be adjusted after initialisation, like so:

ExistingExposureMapObject.src_directory = "/new/data/directory/"

Example

In this example, we illustrate the process for calculating the doses in Harris et al. 2021 (https://doi.org/10.3390/atmos12020268) from the spreadsheet supplied as supplementary data (https://www.mdpi.com/2073-4433/12/2/268/s1). Note that results will differ as the spreadsheet contains only local Swiss time and not UTC time. There are four important functions as part of this class, three for standardising and preparing the columns, and one for actually loading the data and performing the dose calculations. See below:

import python_tamer as pt
import pandas as pd
example = pt.SpecificDoses(pd.read_excel(r'atmosphere-12-00268-s001.xlsx',
                                         header=2,index_col=0,usecols="B:K"))
example.src_directory = 'C:/enter_the_directory_of_your_dataset_here'
example = example.standard_column_names()
example = example.schedule_constant_exposure().ER_from_posture()
example = example.calculate_specific_dose()

ER_from_posture(Vis_table_path=None, Vis_table=None)[source]¶

ER_from_posture calculates Exposure Ratios for a given anatomic zone, posture, and date.

This function calculates ER as a percentage between 0 and 100 based on information from an input table. The input table must contain certain columns at a minimum. Those are: Date, Anatomic_zone, and Posture. This function contains hard-coded synonyms for certain anatomical zones, e.g. ‘Forehead” maps to “Face’. See Vernez et al., Journal of Exposure Science and Environmental Epidemiology (2015) 25, 113–118 (https://doi.org/10.1038/jes.2014.6) for further details on the model used for the calculation.

Parameters

Vis_table_path (str, optional) –

The full path to an alternative table for the Vis parameter.
Must be a csv file. Defaults to None.
Vis_table (str, optional) – An alternative table for the Vis parameter. Defaults to None.

Returns

Returns input table appended with ER column

Return type

SpecificDoses

Notes

The SpecificDoses table used must contain columns for Date, Anatomic_zone, and Posture. The Date column should contain DateTime entries. The Anatonic_zone column should contain one string per row describing the exposed body part. The Posture column should contain one string per row describing one of six accepted postures.

Example

In this example, we illustrate the process for calculating the doses in Harris et al. 2021 (https://doi.org/10.3390/atmos12020268) from the spreadsheet supplied as supplementary data (https://www.mdpi.com/2073-4433/12/2/268/s1). Note that results will differ as the spreadsheet contains only local Swiss time and not UTC time. There are four important functions as part of this class, three for standardising and preparing the columns, and one for actually loading the data and performing the dose calculations. See below:

import python_tamer as pt
import pandas as pd
example = pt.SpecificDoses(pd.read_excel(r'atmosphere-12-00268-s001.xlsx',
                                        header=2,index_col=0,usecols="B:K"))
example.src_directory = 'C:/enter_the_directory_of_your_dataset_here'
example = example.standard_column_names()
example = example.schedule_constant_exposure().ER_from_posture()
example = example.calculate_specific_dose()

analyse_variable(variable='UV_AS', statistic='Mean', src_filename_format=None, src_directory=None)[source]¶

Basic calculations for specific exposure instances

This function is for calculating information other than ambient and personal doses that corresponds to specific exposure instances.

Parameters

variable (str, optional) – The name of the variable to be analysed. This informs what data should be pulled from the source netCDF files. This also informs the name of the column(s) that will be created by this function. Defaults to “UV_AS”, i.e. the All-Sky UV data that is used in the calculate_specific_dose function.
statistic (str or list, optional) – The statistic to be calculated, options include: mean, median, stdev, variance, min, max, weighted_mean, and sum. Not case sensitive. Can be a single string or a list of strings whereby multiple columns will be calculated. Defaults to “Mean”.
src_filename_format (str, optional) – Allows the user to select different source data. This may be useful in cases where the user wants to compare doses calculated with one dataset to (say) cloud cover from another dataset. Defaults to None, where the function uses the source files specified by the object’s metadata.
src_directory (str, optional) – Allows the user to select different source data. This may be useful in cases where the user wants to compare doses calculated with one dataset to (say) cloud cover from another dataset. Defaults to None, where the function uses the source files specified by the object’s metadata.

Returns

The table is appended with new columns named [variable]_[statistic].

Return type

SpecificDoses

Example

In this example, we illustrate the process for calculating the doses in Harris et al. 2021 (https://doi.org/10.3390/atmos12020268) from the spreadsheet supplied as supplementary data (https://www.mdpi.com/2073-4433/12/2/268/s1). Note that results will differ as the spreadsheet contains only local Swiss time and not UTC time. Additionally, to demonstrate the analyse_variable function, we also calculate the weighted mean CMF assuming it to be an additional variable in the source data files. See below:

import python_tamer as pt
import pandas as pd
example = pt.SpecificDoses(pd.read_excel(r'atmosphere-12-00268-s001.xlsx',
                                        header=2,index_col=0,usecols="B:K"))
example.src_directory = 'C:/enter_the_directory_of_your_dataset_here'
example = example.standard_column_names()
example = example.schedule_constant_exposure().ER_from_posture()
example = example.calculate_specific_dose()
example = example.analyse_variable(variable="CMF",statistic="weighted_mean")

calculate_specific_dose()[source]¶

Calculates doses according to exposure schedule, ER, date, and location.

This function takes the SpecificDoseEstimationTable and calculates the specific ambient and personal doses according to the exposure schedule and ER. There are a few key steps to this function. First it reads the Date column to determine which years of data must be loaded. It then iterates through each year, loading only the necessary dates. It applies the exposure schedule and the ER to calculate the ambient and personal doses.

Returns: The input table is appended with a Ambient_dose and Personal_dose column.
Return type: SpecificDoses

Notes

The input SpecificDoses object must include Date, Schedule, ER, Latitude, and Longitude columns. Consult Harris et al. 2021 (https://doi.org/10.3390/atmos12020268) for more information on how this function can be used in the context of mimicking UV dosimetry measurements.

Example

In this example, we illustrate the process for calculating the doses in Harris et al. 2021 (https://doi.org/10.3390/atmos12020268) from the spreadsheet supplied as supplementary data (https://www.mdpi.com/2073-4433/12/2/268/s1). Note that results will differ as the spreadsheet contains only local Swiss time and not UTC time. There are four important functions as part of this class, three for standardising and preparing the columns, and one for actually loading the data and performing the dose calculations. See below:

import python_tamer as pt
import pandas as pd
example = pt.SpecificDoses(pd.read_excel(r'atmosphere-12-00268-s001.xlsx',
                                        header=2,index_col=0,usecols="B:K"))
example.src_directory = 'C:/enter_the_directory_of_your_dataset_here'
example = example.standard_column_names()
example = example.schedule_constant_exposure().ER_from_posture()
example = example.calculate_specific_dose()

schedule_constant_exposure()[source]¶

Generates exposure schedules given start and end times.

This function generates exposure schedules based on simple continuous exposure, i.e. with a start time and an end time. The exposure schedule is a vector with length 24 with each entry representing the proportion of the corresponding hour of the day that the subject is exposed.

Returns: An exposure_schedule column is created and is appended to the input SpecificDoses object or, if that column already exists, it is overwritten.
Return type: python_tamer.SpecificDoses

Notes

The input SpecificDoses object must contain the following columns: * Time_start * Time_end

Example

In this example, we illustrate the process for calculating the doses in Harris et al. 2021 (https://doi.org/10.3390/atmos12020268) from the spreadsheet supplied as supplementary data (https://www.mdpi.com/2073-4433/12/2/268/s1). Note that results will differ as the spreadsheet contains only local Swiss time and not UTC time. There are four important functions as part of this class, three for standardising and preparing the columns, and one for actually loading the data and performing the dose calculations. See below:

import python_tamer as pt
import pandas as pd
example = pt.SpecificDoses(pd.read_excel(r'atmosphere-12-00268-s001.xlsx',
                                        header=2,index_col=0,usecols="B:K"))
example.src_directory = 'C:/enter_the_directory_of_your_dataset_here'
example = example.standard_column_names()
example = example.schedule_constant_exposure().ER_from_posture()
example = example.calculate_specific_dose()

src_directory = 'C:/Data/UV/'¶

src_filename_format = 'UVery.AS_ch02.lonlat_yyyy01010000.nc'¶

standard_column_names()[source]¶

Limited function to standardise column names

When loading tables to use as the basis for a SpecificDoses table, some columns may have slightly names to what is expected. This function standardises the names but is very limited in terms of what it can recognise. The user is encourages to ensure the columns are correctly labelled themselves and not to rely on this function.

Returns: The table has its column names modified.
Return type: SpecificDoses

Subroutines module¶

python_tamer.subroutines.ER_Vernez_2015(Anatomic_zone, Posture, Date=None, Latitude=None, Vis_table_path=None, Vis_table=None)[source]¶

Calculates Exposure Ratios for a given anatomic zone, posture, and date.

This function calculates ER as a percentage between 0 and 100 based on Anatomic_zone, Posture, Date, and Latitude information. This function contains hard-coded synonyms for certain anatomical zones, e.g. ‘Forehead” maps to “Face’. See Vernez et al., Journal of Exposure Science and Environmental Epidemiology (2015) 25, 113–118 (https://doi.org/10.1038/jes.2014.6) for further details on the model used for the calculation.

Parameters

Anatomic_zone (list) – String or list of strings describing the anatomic zone for which the ER is to be calculated.
Posture (list) – String or list of strings describing the posture for which the ER is to be calculated.
Date (list, optional) – The date for which the ER is to be calculated. The date affects the minimum solar zenith angle in the Vernez et al. 2015 ER model. The specific year is not relevant. Defaults to March 20, the equinox.
Latitude (list, optional) – The latitude is important for calculating the ER. Defaults to None, wherein the latitude of the centroid of Switzerland (46.8 degrees) is used.
Vis_table_path (str, optional) – The full path to an alternative table for the Vis parameter. Must be a csv file. Defaults to None.
Vis_table (str, optional) – An alternative table for the Vis parameter. Defaults to None.

Returns

Returns ER values as a list

Return type

list

python_tamer.subroutines.ER_Vernez_model_equation(Vis, mSZA)[source]¶

ER_Vernez_model_equation calculates the Exposure Ratio according to the Vis parameter and the Solar Zenith Angle.

See Vernez et al., Journal of Exposure Science and Environmental Epidemiology (2015) 25, 113–118 (doi:10.1038/jes.2014.6) for further details on the model used for the calculation.

Parameters

Vis (pandas.DataFrame) – Values for the Vis parameter (percentages between 0 and 100)
mSZA (pandas.DataFrame) – Values of the minimal Solar Zenith Angle in degrees for the given date and latitude. Can be calculated using the min_solar_zenith_angle function

Returns

A single column DataFrame containing the calculated Exposure Ratios.

Return type

pandas.DataFrame

python_tamer.subroutines.assert_data_shape_24(data, reverse=False, force_second_dim=True)[source]¶: Simple function to check if first dimension is 24 hours and, if not, reshapes accordingly

python_tamer.subroutines.convert_swiss_time_to_UTC(input_table, name)[source]¶

python_tamer.subroutines.find_nearest(array, value)[source]¶

python_tamer.subroutines.format_filename(inp)[source]¶

Takes a string and return a valid filename constructed from the string.

Uses a whitelist approach: any characters not present in valid_chars are removed. Also spaces are replaced with underscores.

Note: this method may produce invalid filenames such as “”, “.” or “..” When using this method, prepend a date string like “2009_01_15_19_46_32_” and append a file extension like ‘.txt’, so to avoid the potential of using an invalid filename.

Parameters: s (str) – Input string to be converted to valid filename
Returns
Return type: str

python_tamer.subroutines.hist_max(counts, bin_centers)[source]¶

hist_max calculates the maximum value of a histogram

This function finds the maximum value of a histogram. It is built on the some basic functionality as hist_percentile.

Parameters

counts (array) – The quantity of numbers within each histogram bin
bin_centers (array) – The central value of each histogram bin. Note that this can be calculated as bin_edges[:-1]+0.5*np.diff(bin_edges) but we removed this calculation to optimise this function further.

Returns

The maximum value of the histogram

Return type

float

python_tamer.subroutines.hist_mean(counts, bin_centers)[source]¶

hist_mean calculates the mean of a histogram using numpy functions

This function is designed to calculate a histogram mean as efficiently as possible

Parameters

counts (array) – The quantity of numbers within each histogram bin
bin_centers (array) – The central value of each histogram bin. Note that this can be calculated as bin_edges[:-1]+0.5*np.diff(bin_edges) but we removed this calculation to optimise this function further.

Returns

the mean value of the histogram

Return type

float

python_tamer.subroutines.hist_min(counts, bin_centers)[source]¶

hist_min calculates the minimum value of a histogram

This function finds the minimum value of a histogram. It is built on the some basic functionality as hist_percentile.

Parameters

counts (array) – The quantity of numbers within each histogram bin
bin_centers (array) – The central value of each histogram bin. Note that this can be calculated as bin_edges[:-1]+0.5*np.diff(bin_edges) but we removed this calculation to optimise this function further.

Returns

The minimum value of the histogram

Return type

float

python_tamer.subroutines.hist_percentile(counts, bin_centers, prct)[source]¶

hist_percentile calculates percentiles of histogram data

This function takes discretised data, typical for histograms, and calculates the user-specified percentile quantity.

Parameters

counts (array) – The quantity of numbers within each histogram bin
bin_centers (array) – The central value of each histogram bin. Note that this can be calculated as bin_edges[:-1]+0.5*np.diff(bin_edges) but we removed this calculation to optimise this function further.
prct (float) – A fraction betwee 0.0 and 1.0 for the desired percentile.

Returns

The desired percentile value. In cases where the quantity falls: between two bins, their respective central values are averaged.

Return type

float

python_tamer.subroutines.hist_stdev(counts, bin_centers)[source]¶

hist_stdev calculates the standard deviation of a histogram

This function calculates the variance of a histogram as E[X^2] - E[X]^2 using the hist_mean function to efficiently calculate expectation values. It then returns the square root of the variance.

Parameters

counts (array) – The quantity of numbers within each histogram bin
bin_centers (array) – The central value of each histogram bin. Note that this can be calculated as bin_edges[:-1]+0.5*np.diff(bin_edges) but we removed this calculation to optimise this function further.

Returns

the standard deviation of the histogram

Return type

float

python_tamer.subroutines.hist_var(counts, bin_centers)[source]¶

hist_var calculates the variance of a histogram

This function calculates the variance of a histogram as E[X^2] - E[X]^2 using the hist_mean function to efficiently calculate expectation values.

Parameters

counts (array) – The quantity of numbers within each histogram bin
bin_centers (array) – The central value of each histogram bin. Note that this can be calculated as bin_edges[:-1]+0.5*np.diff(bin_edges) but we removed this calculation to optimise this function further.

Returns

the variance of the histogram

Return type

float

python_tamer.subroutines.min_solar_zenith_angle(date, lat)[source]¶

min_solar_zenith_angle calculates the minimal Solar Zenith Angle for a given date and latitude.

This function is adapted from the SACRaM_astr MATLAB function written by Laurent Vuilleumier for MeteoSwiss.

Parameters

date (pandas.DataFrame) – A datetime column describing the specific day of exposure
lat (panda.DataFrame) – A column of latitude values in decimal degrees

Returns

A column of minimal SZA values in degrees.

Return type

pandas.DataFrame

python_tamer.subroutines.str2daysofyear(inp)[source]¶

Interprets a string, list, or array into a list of arrays for days of the year

An ExposureMapSequence object requires of a list of arrays describing the days of the year to be used in the creation of each histogram. This function simplifies the process of entering this information. The user can enter keywords to automatically generate the appropriate list of days.

Parameters: inp (str or list or numpy.array) – The input to be interpreted. Numeric entries should be included in the output unmodified, while string entries should be replaced by numeric arrays.
Returns: Produces a list of arrays that is interpretable by the ExposureMapSequence code.
Return type: list