species.util package

Submodules

species.util.data_util module

Utility functions for data processing.

species.util.data_util.add_missing(model: str, parameters: List[str], database: h5py._hl.files.File) → None[source]

Function for adding missing grid points with a linear interpolation.

Parameters:
  • model (str) – Atmosphere model.
  • parameters (list(str, )) – Model parameters.
  • database (h5py._hl.files.File) – Database.
Returns:

None

Return type:

NoneType

species.util.data_util.correlation_to_covariance(cor_matrix, spec_sigma)[source]
Parameters:
  • cor_matrix (np.ndarray) – Correlation matrix of the spectrum.
  • spec_sigma (np.ndarray) – Uncertainties (W m-2 um-1).
Returns:

Covariance matrix of the spectrum.

Return type:

np.ndarrays

species.util.data_util.sort_data(param_teff: numpy.ndarray, param_logg: Optional[numpy.ndarray], param_feh: Optional[numpy.ndarray], param_co: Optional[numpy.ndarray], param_fsed: Optional[numpy.ndarray], wavelength: numpy.ndarray, flux: numpy.ndarray) → List[numpy.ndarray][source]
Parameters:
  • param_teff (np.ndarray) – Array with the effective temperature (K) of each spectrum.
  • param_logg (np.ndarray, None) – Array with the log10 surface gravity (cgs) of each spectrum.
  • param_feh (np.ndarray, None) – Array with the metallicity of each spectrum. Not used if set to None.
  • param_co (np.ndarray, None) – Array with the carbon-to-oxygen ratio of each spectrum. Not used if set to None.
  • param_fsed (np.ndarray, None) – Array with the sedimentation parameter of each spectrum. Not used if set to None.
  • wavelength (np.ndarray) – Array with the wavelengths (um).
  • flux (np.ndarray) – Array with the spectra with dimensions (n_spectra, n_wavelengths).
Returns:

List with the unique values of the atmosphere parameters (each in a separate array), an array with the wavelengths, and a multidimensional array with the sorted spectra.

Return type:

list(np.ndarray, )

species.util.data_util.update_filter(filter_in)[source]

Function to update a filter ID from the Vizier Photometry viewer VOTable to the filter ID from the SVO Filter Profile Service.

Parameters:filter_in (str) – Filter ID in the format of the Vizier Photometry viewer.
Returns:Filter ID in the format of the SVO Filter Profile Service.
Return type:str
species.util.data_util.update_sptype(sptypes: numpy.ndarray) → List[str][source]

Function to update a list with spectral types to two characters (e.g., M8, L3, or T1). The spectral to is set to NaN in case the first character is not recognized or the second character is not a numerical value.

Parameters:sptypes (np.ndarray) – Input spectral types.
Returns:Output spectral types.
Return type:list(str)
species.util.data_util.write_data(model: str, parameters: List[str], database: h5py._hl.files.File, data_sorted: List[numpy.ndarray]) → None[source]

Function for writing the model spectra and parameters to the database.

Parameters:
  • model (str) – Atmosphere model.
  • parameters (list(str, )) – Model parameters.
  • database (h5py._hl.files.File) – Database.
  • data_sorted (list(np.ndarray, )) – Sorted model data with the parameter values, wavelength points (um), and flux densities (W m-2 um-1).
Returns:

None

Return type:

NoneType

species.util.dust_util module

Utility functions for dust cross sections and extinction.

species.util.dust_util.calc_reddening(filters_color: Tuple[str, str], extinction: Tuple[str, float], composition: str = 'MgSiO3', structure: str = 'crystalline', radius_g: float = 1.0) → Tuple[float, float][source]

Function for calculating the reddening of a color given the extinction for a given filter. A log-normal size distribution with a geometric standard deviation of 2 is used as parametrization for the grain sizes (Ackerman & Marley 2001).

Parameters:
  • filters_color (tuple(str, str)) – Filter names for which the extinction is calculated.
  • extinction (str) – Filter name and extinction (mag).
  • composition (str) – Dust composition (‘MgSiO3’ or ‘Fe’).
  • structure (str) – Grain structure (‘crystalline’ or ‘amorphous’).
  • radius_g (float) – Geometric radius of the grain size distribution (um).
Returns:

  • float – Extinction (mag) for filters_color[0].
  • float – Extinction (mag) for filters_color[1].

species.util.dust_util.check_dust_database() → str[source]

Function to check if the dust data is present in the database and add the data if needed.

Returns:The database path from the configuration file.
Return type:str
species.util.dust_util.dust_cross_section(dn_grains: numpy.ndarray, radii: numpy.ndarray, wavelength: float, n_index: float, k_index: float) → numpy.float64[source]

Function for calculating the extinction cross section for a size distribution of dust grains.

Parameters:
  • dn_grains (np.ndarray) – Number of grains in each radius bin, normalized to a total of 1 grain.
  • radii (np.ndarray) – Grain radii (um).
  • wavelength (float) – Wavelength (um).
  • n_index (float) – Real part of the refractive index.
  • k_index (float) – Imaginary part of the refractive index.
Returns:

Extinction cross section (um2)

Return type:

float

species.util.dust_util.interp_lognorm(inc_phot: List[str], inc_spec: List[str], spec_data: Optional[Dict[str, Tuple[numpy.ndarray, Optional[numpy.ndarray], Optional[numpy.ndarray], float]]]) → Tuple[Dict[str, Union[scipy.interpolate.interpolate.interp2d, List[scipy.interpolate.interpolate.interp2d]]], numpy.ndarray, numpy.ndarray][source]

Function for interpolating the log-normal dust cross sections for each filter and spectrum.

Parameters:
  • inc_phot (list(str)) – List with filter names. Not used if the list is empty.
  • inc_spec (list(str)) – List with the spectrum names (as stored in the database with add_object()). Not used if the list is empty.
  • spec_data (dict, None) – Dictionary with the spectrum data. Only required in combination with inc_spec, otherwise the argument needs to be set to None,.
Returns:

  • dict – Dictionary with the extinction cross section for each filter and spectrum
  • np.ndarray – Grid points of the geometric mean radius.
  • np.ndarray – Grid points of the geometric standard deviation.

species.util.dust_util.interp_powerlaw(inc_phot: List[str], inc_spec: List[str], spec_data: Optional[Dict[str, Tuple[numpy.ndarray, Optional[numpy.ndarray], Optional[numpy.ndarray], float]]]) → Tuple[Dict[str, Union[scipy.interpolate.interpolate.interp2d, List[scipy.interpolate.interpolate.interp2d]]], numpy.ndarray, numpy.ndarray][source]

Function for interpolating the power-law dust cross sections for each filter and spectrum.

Parameters:
  • inc_phot (list(str)) – List with filter names. Not used if the list is empty.
  • inc_spec (list(str)) – List with the spectrum names (as stored in the database with add_object()). Not used if the list is empty.
  • spec_data (dict, None) – Dictionary with the spectrum data. Only required in combination with inc_spec, otherwise the argument needs to be set to None,.
Returns:

  • dict – Dictionary with the extinction cross section for each filter and spectrum
  • np.ndarray – Grid points of the maximum radius.
  • np.ndarray – Grid points of the power-law exponent.

species.util.dust_util.ism_extinction(av_mag: float, rv_red: float, wavelengths: numpy.ndarray) → numpy.ndarray[source]

Function for calculating the optical and IR extinction with the empirical relation from Cardelli et al. (1989).

Parameters:
  • av_mag (float) – Extinction (mag) in the V band.
  • rv_red (float) – Reddening in the V band, R_V = A_V / E(B-V).
  • wavelengths (np.ndarray) – Array with the wavelengths (um) for which the extinction is calculated.
Returns:

Extinction (mag) at wavelengths.

Return type:

np.ndarray

species.util.dust_util.log_normal_distribution(radius_g: float, sigma_g: float, n_bins: int) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Function for returning a log-normal size distribution. See Eq. 9 in Ackerman & Marley (2001).

Parameters:
  • radius_g (float) – Mean geometric radius (um).
  • sigma_g (float) – Geometric standard deviation (dimensionless).
  • n_bins (int) – Number of logarithmically-spaced radius bins.
Returns:

  • np.ndarray – Number of grains in each radius bin, normalized to a total of 1 grain.
  • np.ndarray – Widths of the radius bins (um).
  • np.ndarray – Grain radii (um).

species.util.dust_util.power_law_distribution(exponent: float, radius_min: float, radius_max: float, n_bins: int) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Function for returning a power-law size distribution.

Parameters:
  • exponent (float) – Exponent of the power-law size distribution, dn/dr = r**exponent.
  • radius_min (float) – Minimum grain radius (um).
  • radius_max (float) – Maximum grain radius (um).
  • n_bins (int) – Number of logarithmically-spaced radius bins.
Returns:

  • np.ndarray – Number of grains in each radius bin, normalized to a total of 1 grain.
  • np.ndarray – Widths of the radius bins (um).
  • np.ndarray – Grain radii (um).

species.util.phot_util module

Utility functions for photometry.

species.util.phot_util.absolute_to_apparent(abs_mag: Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]], distance: Union[Tuple[float, float], Tuple[numpy.ndarray, numpy.ndarray]]) → Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]][source]

Function for converting an absolute magnitude into an apparent magnitude.

Parameters:
  • abs_mag (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Absolute magnitude and uncertainty (mag). The same uncertainty is used for the apparent magnitude.
  • distance (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Distance and uncertainty (pc).
Returns:

  • float, np.ndarray – Apparent magnitude (mag).
  • float, np.ndarray, None – Uncertainty (mag).

species.util.phot_util.apparent_to_absolute(app_mag: Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]], distance: Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]]) → Union[Tuple[float, Optional[float]], Tuple[numpy.ndarray, Optional[numpy.ndarray]]][source]

Function for converting an apparent magnitude into an absolute magnitude. The uncertainty on the distance is propagated into the uncertainty on the absolute magnitude.

Parameters:
  • app_mag (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Apparent magnitude and uncertainty (mag). The returned error on the absolute magnitude is set to None if the error on the apparent magnitude is set to None, for example app_mag=(15., None).
  • distance (tuple(float, float), tuple(np.ndarray, np.ndarray)) – Distance and uncertainty (pc). The error is not propagated into the error on the absolute magnitude if set to None, for example distance=(20., None).
Returns:

  • float, np.ndarray – Absolute magnitude (mag).
  • float, np.ndarray, None – Uncertainty (mag).

species.util.phot_util.get_residuals(datatype: str, spectrum: str, parameters: Dict[str, float], objectbox: species.core.box.ObjectBox, inc_phot: Union[bool, List[str]] = True, inc_spec: Union[bool, List[str]] = True, **kwargs_radtrans) → species.core.box.ResidualsBox[source]
Parameters:
  • datatype (str) – Data type (‘model’ or ‘calibration’).
  • spectrum (str) – Name of the atmospheric model or calibration spectrum.
  • parameters (dict) – Parameters and values for the spectrum
  • objectbox (species.core.box.ObjectBox) – Box with the photometry and/or spectra of an object. A scaling and/or error inflation of the spectra should be applied with update_spectra() beforehand.
  • inc_phot (bool, list(str)) – Include photometric data in the fit. If a boolean, either all (True) or none (False) of the data are selected. If a list, a subset of filter names (as stored in the database) can be provided.
  • inc_spec (bool, list(str)) – Include spectroscopic data in the fit. If a boolean, either all (True) or none (False) of the data are selected. If a list, a subset of spectrum names (as stored in the database with add_object()) can be provided.
Keyword Arguments:
 

kwargs_radtrans (dict) – Dictionary with the keyword arguments for the ReadRadtrans object, containing line_species, cloud_species, and scattering.

Returns:

Box with the residuals.

Return type:

species.core.box.ResidualsBox

species.util.phot_util.multi_photometry(datatype: str, spectrum: str, filters: List[str], parameters: Dict[str, float]) → species.core.box.SynphotBox[source]
Parameters:
  • datatype (str) – Data type (‘model’ or ‘calibration’).
  • spectrum (str) – Spectrum name (e.g., ‘drift-phoenix’, ‘planck’, ‘powerlaw’).
  • filters (list(str, )) – List with the filter names.
  • parameters (dict) – Dictionary with the model parameters.
Returns:

Box with synthetic photometry.

Return type:

species.core.box.SynphotBox

species.util.plot_util module

Utility functions for plotting data.

species.util.plot_util.field_bounds_ticks(field_range)[source]
Parameters:field_range (tuple(str, str), None) – Range of the discrete colorbar for the field dwarfs. The tuple should contain the lower and upper value (‘early M’, ‘late M’, ‘early L’, ‘late L’, ‘early T’, ‘late T’, ‘early Y). The full range is used if set to None.
Returns:
  • np.ndarray
  • np.ndarray
  • list(str, )
species.util.plot_util.model_name(key: str) → str[source]

Function for updating a model name for use in plots.

Parameters:key (str) – Model name as used by species.
Returns:Updated model name for plots.
Return type:str
species.util.plot_util.quantity_unit(param: List[str], object_type: str) → Tuple[List[str], List[Optional[str]], List[str]][source]

Function for creating lists with quantities, units, and labels for fitted parameter.

Parameters:
  • param (list) – List with parameter names.
  • object_type (str) – Object type ('planet' or 'star').
Returns:

  • list – List with the quantities.
  • list – List with the units.
  • list – List with the parameter labels for plots.

species.util.plot_util.remove_color_duplicates(object_names: List[str], empirical_names: numpy.ndarray) → List[int][source]

” Function for deselecting young/low-gravity objects that will already be plotted individually as directly imaged objects.

Parameters:
  • object_names (list(str)) – List with names of directly imaged planets and brown dwarfs.
  • empirical_names (np.ndarray) – Array with names of young/low-gravity objects.
Returns:

List with selected indices of the young/low-gravity objects.

Return type:

list

species.util.plot_util.sptype_stellar(sptype: numpy.ndarray, shape: Tuple[int]) → numpy.ndarray[source]

Function for mapping all spectral types (O through Y) to numbers.

Parameters:
  • sptype (np.ndarray) – Array with spectral types.
  • shape (tuple(int)) – Shape (1D) of the output array
Returns:

Array with spectral types mapped to numbers.

Return type:

np.ndarray

species.util.plot_util.sptype_substellar(sptype: numpy.ndarray, shape: Tuple[int]) → numpy.ndarray[source]

Function for mapping the spectral types of substellar objects (M, L, T, and Y) to numbers.

Parameters:
  • sptype (np.ndarray) – Array with spectral types.
  • shape (tuple(int)) – Shape (1D) of the output array
Returns:

Array with spectral types mapped to numbers.

Return type:

np.ndarray

species.util.plot_util.update_labels(param: List[str]) → List[str][source]

Function for updating the fitted parameters to labels used in plots.

Parameters:param (list) – List with parameter names.
Returns:List with parameter labels for plots.
Return type:list

species.util.query_util module

Text

class species.util.query_util.NoStdStreams(stdout=None, stderr=None)[source]

Bases: object

Text

species.util.query_util.get_distance(target)[source]
Parameters:target (str) – Target name.
Returns:
  • str – SIMBAD name.
  • tuple(float, float) – Distance and uncertainty (pc).
species.util.query_util.get_parallax()[source]
species.util.query_util.get_simbad(name)[source]

Function for getting the SIMBAD identifier of an object.

Parameters:name (np.ndarray) –
Returns:SIMBAD name.
Return type:np.ndarray

species.util.read_util module

Utility functions for reading data.

species.util.read_util.add_luminosity(modelbox)[source]

Function to add the luminosity of a model spectrum to the parameter dictionary of the box.

Parameters:modelbox (species.core.box.ModelBox) – Box with the model spectrum. Should also contain the dictionary with the model parameters, the radius in particular.
Returns:The input box with the luminosity added in the parameter dictionary.
Return type:species.core.box.ModelBox
species.util.read_util.create_wavelengths(wavel_range: Tuple[Union[float, numpy.float32], Union[float, numpy.float32]], spec_res: float) → numpy.ndarray[source]

Function for creating logarithmically-spaced wavelengths at a constant spectral resolution.

Parameters:
  • wavel_range (tuple(float, float)) – Wavelength range (um). Tuple with the minimum and maximum wavelength.
  • spec_res (float) – Spectral resolution at which the wavelengths are sampled.
Returns:

Array with the wavelength points and a fixed spectral resolution. Since the wavelength boundaries are fixed, the output spectral resolution is slightly different from the spec_res value.

Return type:

np.ndarray

species.util.read_util.gaussian_spectrum(wavel_range: Union[Tuple[float, float], Tuple[numpy.float32, numpy.float32]], model_param: Dict[str, float], spec_res: float = 100.0, double_gaussian: bool = False) → species.core.box.ModelBox[source]

Function for calculating a Gaussian spectrum (i.e. for an emission line).

Parameters:
  • wavel_range (tuple(float, float)) – Tuple with the minimum and maximum wavelength (um).
  • model_param (dict) – Dictionary with the model parameters. Should contain 'gauss_amplitude', 'gauss_mean', 'gauss_sigma', and optionally 'gauss_offset'.
  • spec_res (float) – Spectral resolution (default: 100).
  • double_gaussian (bool) – Set to True for returning a double Gaussian function. In that case, model_param should also contain 'gauss_amplitude_2', 'gauss_mean_2', and 'gauss_sigma_2'.
Returns:

Box with the Gaussian spectrum.

Return type:

species.core.box.ModelBox

species.util.read_util.get_mass(logg: Union[float, numpy.ndarray], radius: Union[float, numpy.ndarray]) → Union[float, numpy.ndarray][source]

Function for converting a \(\log(g)\) and a radius into a mass.

Parameters:
  • logg (float, np.ndarray) – Log10 of the surface gravity (cgs).
  • radius (float, np.ndarray) – Radius (Rjup).
Returns:

Mass (Mjup).

Return type:

float, np.ndarray

species.util.read_util.get_radius(logg: Union[float, numpy.ndarray], mass: Union[float, numpy.ndarray]) → Union[float, numpy.ndarray][source]

Function for converting a \(\log(g)\) and a mass into a radius.

Parameters:
  • logg (float, np.ndarray) – Log10 of the surface gravity (cgs).
  • mass (float, np.ndarray) – Mass (Mjup).
Returns:

Radius (Rjup).

Return type:

float, np.ndarray

species.util.read_util.powerlaw_spectrum(wavel_range: Union[Tuple[float, float], Tuple[numpy.float32, numpy.float32]], model_param: Dict[str, float], spec_res: float = 100.0) → species.core.box.ModelBox[source]

Function for calculating a power-law spectrum. The power-law function is calculated in log(wavelength)-log(flux) space but stored in the ModelBox in linear wavelength-flux space.

Parameters:
  • wavel_range (tuple(float, float)) – Tuple with the minimum and maximum wavelength (um).
  • model_param (dict) – Dictionary with the model parameters. Should contain ‘log_powerlaw_a’, ‘log_powerlaw_b’, and ‘log_powerlaw_c’.
  • spec_res (float) – Spectral resolution (default: 100).
Returns:

Box with the power-law spectrum.

Return type:

species.core.box.ModelBox

species.util.read_util.smooth_spectrum(wavelength: numpy.ndarray, flux: numpy.ndarray, spec_res: float, size: int = 11, force_smooth: bool = False) → numpy.ndarray[source]

Function for smoothing a spectrum with a Gaussian kernel to a fixed spectral resolution. The kernel size is set to 5 times the FWHM of the Gaussian. The FWHM of the Gaussian is equal to the ratio of the wavelength and the spectral resolution. If the kernel does not fit within the available wavelength grid (i.e. at the edge of the array) then the flux values are set to NaN.

Parameters:
  • wavelength (np.ndarray) – Wavelength points (um). Should be sampled with a uniform spectral resolution or a uniform wavelength spacing (slow).
  • flux (np.ndarray) – Flux (W m-2 um-1).
  • spec_res (float) – Spectral resolution.
  • size (int) – Kernel size (odd integer).
  • force_smooth (bool) – Force smoothing for constant spectral resolution
Returns:

Smoothed spectrum (W m-2 um-1).

Return type:

np.ndarray

species.util.read_util.update_spectra(objectbox: species.core.box.ObjectBox, model_param: Dict[str, float], model: Optional[str] = None) → species.core.box.ObjectBox[source]

Function for applying a flux scaling and/or error inflation to the spectra of an ObjectBox.

Parameters:
  • objectbox (species.core.box.ObjectBox) – Box with the object’s data, including the spectra.
  • model_param (dict) – Dictionary with the model parameters. Should contain the value(s) of the flux scaling and/or the error inflation.
  • model (str, None) – Name of the atmospheric model. Only required for inflating the errors. Otherwise, the argument can be set to None.
Returns:

The input box which includes the spectra with the scaled fluxes and/or inflated errors.

Return type:

species.core.box.ObjectBox

species.util.test_util module

Utility functions for running the unit tests.

species.util.test_util.create_config(test_path)[source]

Function for creating a configuration file in the test folder.

Parameters:test_path (str) – Folder where the unit tests are located.
Returns:None
Return type:NoneType

Module contents