biosnicar Classes

This page contains definitions for all the classes used in biosnicar, including:

• Impurity
• Ice
• Illumination
• RTConfig
• ModelConfig
• PlotConfig
• Outputs
• BioOpticalConfig

These classes are used as convenient, mutable containers for the necessary data required to run BioSNICAR. They are automatically instantiated by calling setup_snicar() using values provided in inputs.yaml. Class functions are available for recalculating derived attributes when the user changes attributes of Ice or Illumination classes.

Note that there are two classes - Illumination and Ice that have associated class functions.

Impurity (class)

Light absorbing impurity.

Instances of Impurity are one discrete type of light absorbing impurity with a distinct set of optical properties.

Attributes

• name: name of impurity
• unit: the unit the concentration should be represented in (0 = ppb, 1 = cells/mL)
• conc: concentration of the impurity in each layer (in units of self.unit)
• file: name of netCDF file containing optical properties and size distribution
• impurity_properties: instance of opened file self.file
• mac: mass absorption coefficient (m2/kg or m2/cell)
• ssa: single scattering albedo
• g: asymmetry parameter

Ice (class)

Snow or ice column physical properties.

Instances of Ice contain all the physical properties of each vertical layer of the snow or ice column and the underlying surface.

Attributes

• dz: array containing thickness of each layer in m
• layer_type: array containing type (0 = grains, 1 = solid ice) in each layer
• cdom: array containing Boolean (1/0) toggling presence of cdom in each layer
• rho: array containing density of each layer in kg/m3
• sfc: array with reflectance of underlying surface per wavelength
• rf: refractive index to use, 0,1,2 or 3 (see docs for definition)
• shp: grain shape per layer where layer_type==1
• rds: grain radius (layer_type==0) or bubble radius (layer_type==0) in each layer
• water: radius of grain+water coating in each layer where layer_type==0
• hex_side: length of each side of hexagonal face for grain_shp==4
• hex_length: column length for hexagonal face for grain_shp==4
• shp_fctr: ratio of nonspherical eff radii to equal vol sphere, in each layer
• ar: aspect ratio of grains in each layer where layer_type==0
• nbr_lyr: number of vertical layers

functions

calculate_refractive_index

Calculates ice refractive index from initialized class attributes.

Takes self.rf and config from inputs.yaml and uses them to calculate new attributes related to the ice refractive index.

Args

self

Returns

• ref_idx_im: imaginary part of refractive index
• ref_idx_re: real part of refractive index
• fl_r_dif_a: precomputed diffuse reflectance "perpendicular polarized)
• fl_r_dif_b: precomputed diffuse reflectance "parallel polarized)
• op_dir: directory containing optical properties

Raises

ValueError if rf out of range

Illumination (class)

Properties of incoming irradiance. Instances of Illumination contain all data relating to the incoming irradiance.

Attributes

• direct: Boolean toggling between direct and diffuse irradiance
• solzen: solar zenith angle in degrees from the vertical
• incoming: choice of spectral distribution from file 0-6
• flx_dir: directory containing irradiance files
• stubs: array of stub strings for selecting irradiance files
• nbr_wvl: number fo wavelengths (default 480)

Functions

calculate_irradiance

Calculates irradiance from initialized attributes.

Takes mu_not, incoming and stubs from self and calculates irradiance.

Args

self

Returns:

• flx_slr: incoming flux from file
• Fd: diffuse irradiance
• Fs: direct irradiance

Raises

ValueError is incoming is out of range

RTConfig

Radiative transfer configuration.

Attributes:

• aprx_type: choice of two-stream approximation (0-2)
• delta: Boolean to toggle delta transformation (0/1)

ModelConfig (class)

Model configuration.

Attributes

• smooth: Boolean to toggle savitsky-golay filter to smooth albedo
• window_size: window size to use for smoothing func
• poly_order: order of polynomial used to smooth albedo
• dir_base: base directory
• dir_wvl: path to wavelengths in csv file
• sphere_ice_path: directory containing OPs for spherical ice grains
• hex_ice_path: directory containing OPs for hexagonal ice grains
• bubbly_ice_path: directory containing OPs for bubbly ice
• ri_ice_path: path to file containing pure ice refractive index
• op_dir_stubs: string stubs for ice optical property files
• illumination_file_stubs: string stubs for irradiance optical property files
• wavelengths: array of wavelengths in nm (default 0.205 - 4.995 um)
• nbr_wvl: number of wavelengths (default 480)
• vis_max_idx: index for upper visible wavelength (default 0.75 um)
• nir_max_idx: index for upper NIR wavelength (default 4.995 um)

Outputs (class)

Output data from radiative transfer calculations.

Attributes

• heat_rt: heating rate in each layer
• BBAVIS: broadband albedo in visible range
• BBANIR: broadband albedo in NIR range
• BBA: broadband albedo across solar spectrum
• abs_slr_btm: absorbed solar energy at bottom surface
• abs_vis_btm: absorbed visible energy at bottom surface
• abs_nir_btm: absorbed NIR energy at bottom surface
• albedo: albedo of ice column
• total_insolation: energy arriving from atmosphere
• abs_slr_tot: total absorbed energy across solar spectrum
• abs_vis_tot: total absorbed energy across visible spectrum
• abs_nir_tot: total absorbed energy across NIR spectrum
• absorbed_flux_per_layer: total absorbed flux per layer

PlotConfig (class)

Configuration for plotting figures.

Attributes

• figsize: size of figure
• facecolor: colour of background
• grid: toggles grid visibility
• grid_color: color of grid lines
• xtick_width: frequency of xticks
• xtick_size: size of ticks on x axis
• ytick_width: frequency of yticks
• ytick_size: size of ticks on y axis
• linewidth: pixel width of line on plot
• fontsize: size of text labels
• xtick_btm: toggles tick positions
• ytick_left: toggle ytick position
• show: toggles showing plot on screen
• save: toggles saving figure to file

BioOpticalConfig (class)

Configuration class for bio-optical model.

Attributes

• wvl: (numpy array, default: np.arange(0.200, 4.999, 0.001)) wavelengths in spectral range of interest (in µm, 1nm step)
• wet_density: (int - used if biomass: True) density of wet biomass (kg/m3 - 1060 and 1160 for snow and glacier algae,Chevrollier et al. 2022)
• dry_density: (int - used if biomass: True) density of dry biomass (kg/m3 - 625 and 684 for snow and glacier algae, Chevrollier et al. 2022)
• ABS_CFF_CALC: toggles calculating abs_cff from pigments or loading from file.
• abs_cff_loaded_reconstructed: (boolean) True if the abs_cff is loaded as a reconstructed spectrum from pigment absorbance (see methods in Chevrollier et al. 2022)
• abs_cff_loaded_invivo: (boolean) True if the abs_cff is loaded as in vivo spectra of whole cells
• abs_cff_file: (string) directory to the abs_cff file if loaded
• pigment_data: dictionary with pigment file names and associated intracellular concentrations (ng/cell, ng/µm3 or ng/ng)
• pigment_dir: (string) used if abs_cff_calculated is True, directory to folder containing pigment mass absorption coefficients that must be csv file with size and resolution of wvl, and units in m2/mg
• packaging_correction_SA: (boolean - applied ONLY if abs_cff_loaded_reconstructed is True) If True, reconstructed SA abs_cff is corrected for pigment packaging following Chevrollier et al. 2022
• packaging_correction_GA: (boolean - applied ONLY if abs_cff_loaded_reconstructed is True) If True, reconstructed GA abs_cff is corrected for pigment packaging following Chevrollier et al. 2022
• dir_pckg: (string) directory to pigment packaging correction files
• k_water_dir: (string) path to file with imaginary part of the refractive index of water
• unit: unit for absorption cross section: 0 = m2/cell, 1 = m2/um3, 3 = m2/mg and/or pigment data: 0 = ng/cell, 1 = ng/um3, 3 = ng/mg
• cell_vol: (int - used if cellular: True) volume of the algae cell (um3)
• n_algae: (int) real part of cellular refractive index in the spectral range of wvl (constant 1.38 by default, Chevrollier et al. 2022)
• GO: (boolean) if True, uses geometric optics equations (Cook et al. 2020 adapted from Diedenhoven et al (2014)) to calculate single scattering OPs assuming cell shape: cylinder
• Mie: (boolean) if True, uses Mie theory to calculate single scattering OPs assuming cell shape: sphere
• radius: (int) radius of sphere (Mie)/cynlinder (GO) representing cell (µm)
• length: (int) depth of the cylinder representing the cell (GO option, µm)
• report_dims: (boolean) if True, cell dimensions printed to console
• plot_ssps: (boolean) if True, print plots with ssps
• savefig_ssps: if True, ssps plots saved in the directory savepath
• plot_n_k_abs_cff: (boolean) if True, plot with n,k and abs_cff printed
• saveplots_n_k_abs_cff: (boolean) if True, plots saved in the directory savepath
• savefiles_n_k_abs_cff: (boolean) if True, files with k,n and abs_cff saved in the directory savepath
• savepath: (boolean) directory for saving data if savefiles or saveplots toggled on
• smooth: (boolean) if True, apply optional smoothing filter
• window_size: (int) size of window of smoothing filter (dflt value: 25)
• `poly_order: (int) polynomial order of smoothing filter (dflt value: 3)
• save_netcdf: (boolean) if True, saves data in a netcdf file
• savepath_netcdf: (string) save path directory
• filename_netcdf: (string) name of the file containing the optical properties
• information: (string) containing any additional info for metadata in netcdf (e.g. 'Glacier algae OPs derived from GO calculations with empirical abs_cff')