Sample Class

class sitesyncro.Sample.Sample(*args, **kwargs)

A class representing a single radiocarbon sample.

The constructor accepts a single dictionary argument or multiple arguments to initialize the object with the provided data.

Parameters:

  • name (str) – Sample ID (required, unique identifier)

  • age (float) – C-14 age (years BP) for date_type ‘R’; mean calendar age (years BP) for date_type ‘U’ (required)

  • uncertainty (float) – Uncertainty (years BP) for date_type ‘R’; 1/2 range (years BP) for date_type ‘U’ (required)

  • date_type (str, optional) – ‘R’ for radiocarbon date; ‘U’ for calendar date as a uniform distribution

  • long_lived (bool, optional) – True if sample could be older than the examined deposition event due to e.g. old wood effect

  • redeposited (bool, optional) – True if sample could be redeposited from a different context

  • outlier (bool, optional) – True if sample is an outlier and should not be used for modeling

  • context (str, optional) – Name of the context where sample was found

  • area (str, optional) – Excavation area

  • excavation_area_phase (str, optional) – Chronological phase of the context within the excavation area (format: “1” or “1a” or “1-2” or “1a-b” or “1a-2b”, higher = earlier (older) phase)

  • earlier_than (List[str], optional) – List of names of samples which this sample is stratigraphically earlier (older) than

  • site_phase (str, optional) – Chronological phase of the context within the site (format: “1” or “1a” or “1-2” or “1a-b” or “1a-2b”, lower = earlier (older) phase)

  • curve (np.ndarray, optional) – Radiocarbon calibration curve in format np.array([[calendar year BP, C-14 year, uncertainty], …])

property age: float

The C-14 age or mean calendar age of the sample in years BP.

Returns:

The C-14 age or mean calendar age of the sample or None if it’s not set.

Return type:

float or None

property area: str

The excavation area where the sample was found.

Returns:

The name of the excavation area where the sample was found or None if it’s not set.

Return type:

str or None

calibrate(curve: ndarray) → None

Calibrates the sample using the provided calibration curve.

Parameters:

curve (np.ndarray) – The calibration curve to be used for calibration. Format: np.array([[calendar year BP, C-14 year, uncertainty], …]).

Raises:

Exception – If the calibration curve is not provided or if the necessary sample data (age, uncertainty, date_type) is not set.

property context: str

The context where the sample was found.

Returns:

The name of the context where the sample was found or None if it’s not set.

Return type:

str or None

copy() → Sample

Creates a copy of the sample instance.

Returns:

A new instance of the Sample class with the same data as the current instance.

Return type:

Sample

property date_type: str

The type of the date for the sample.

Returns:

The type of the date (‘R’ for radiocarbon date; ‘U’ for calendar date as a uniform distribution) or None if it’s not set.

Return type:

str or None

property earlier_than: List[str]

List of names of samples which this sample is stratigraphically earlier (older) than.

Returns:

List of names of samples which this sample is stratigraphically earlier (older) than or None if it’s not set.

Return type:

List[str] or None

property excavation_area_phase: str

The chronological phase of the context within the excavation area.

Returns:

The chronological phase of the context within the excavation area (format: “1” or “1a” or “1-2” or “1a-b” or “1a-2b”, higher = earlier (older) phase) or None if it’s not set.

Return type:

str or None

from_dict(data: dict) → None

Loads the sample data from a dictionary.

The method updates the sample data with the provided dictionary. It also converts keys to integers and numpy arrays to lists for JSON serialization.

Parameters:

data (dict) – A dictionary containing the sample data.

get_range() → [<class 'float'>, <class 'float'>]

Gets the 2-sigma (95.45%) range of the dating of the sample in calendar years BP.

If the sample has been modeled, it returns the posterior range. If the sample is not calibrated, it returns [None, None]. If the sample is long-lived and the date type is ‘R’, it keeps the lower boundary and doubles the range. Otherwise, it returns the likelihood range.

Returns:

A list containing the lower and upper bounds of the 2-sigma range, or [None, None] if it’s not set.

Return type:

list

property group: str

The group that the sample belongs to based on stratigraphic interconnection with other samples.

Returns:

The group that the sample belongs to or None if it’s not set.

Return type:

str or None

property is_calibrated: bool

Checks if the sample has been calibrated.

Returns:

True if the sample has been calibrated, False otherwise.

Return type:

bool

property is_modeled: bool

Checks if the posterior has been calculated using Bayesian modeling.

Returns:

True if the posterior has been calculated, False otherwise.

Return type:

bool

property likelihood: ndarray

The probability distribution of the dating of the sample before Bayesian modeling.

Returns:

An array representing the probability distribution of the dating of the sample before Bayesian modeling, where each element is the probability of the corresponding calendar year. Returns None if it’s not set.

Return type:

np.ndarray or None

property likelihood_mean: float

The mean calendar age of the sample in calendar years BP before Bayesian modeling.

Returns:

The mean calendar age of the sample before Bayesian modeling or None if it’s not set.

Return type:

float or None

property likelihood_range: [<class 'float'>, <class 'float'>]

The 2-sigma (95.45%) range of the dating of the sample in calendar years BP before Bayesian modeling.

Returns:

A list containing the lower and upper bounds of the 2-sigma range, or [None, None] if it’s not set.

Return type:

list

property long_lived: bool

Indicates if the sample is long-lived.

True if the sample could be older than the examined deposition event due to factors like the old wood effect.

Returns:

True if the sample is long-lived. Returns None if it’s not set.

Return type:

bool or None

property name: str

Gets the unique identifier (ID) of the sample.

Returns:

The unique identifier of the sample or None if it’s not set.

Return type:

str or None

property outlier: bool

Indicates if the sample is an outlier and should not be used for modeling.

Returns:

True if the sample is an outlier, False otherwise. Returns None if it’s not set.

Return type:

bool or None

property phase: float

The stratigraphic phase of the sample within the group.

Returns:

The stratigraphic phase of the sample within the group (lower = earlier (older) phase) or None if it’s not set.

Return type:

float or None

property phasing_range: [<class 'float'>, <class 'float'>]

The range of possible stratigraphic phases of the sample within the group.

Returns:

A list containing the lower and upper bounds of the possible phases, or [None, None] if they are not set.

Return type:

list

property posterior: ndarray

The probability distribution of the dating of the sample after Bayesian modeling.

Returns:

An array representing the probability distribution of the dating of the sample after Bayesian modeling, where each element is the probability of the corresponding calendar year. Returns None if it’s not set.

Return type:

np.ndarray or None

property posterior_agreement: float

The agreement index generated by OxCal modeling.

Returns:

The agreement index generated by OxCal modeling or None if it’s not set.

Return type:

float or None

property posterior_mean: float

The mean calendar age of the sample in calendar years BP after Bayesian modeling.

Returns:

The mean calendar age of the sample after Bayesian modeling or None if it’s not set.

Return type:

float or None

property posterior_range: [<class 'float'>, <class 'float'>]

The 2-sigma (95.45%) range of the dating of the sample in calendar years BP after Bayesian modeling.

Returns:

A list containing the lower and upper bounds of the 2-sigma range, or [None, None] if it’s not set.

Return type:

list

property redeposited: bool

Indicates if the sample could be redeposited from a different context.

Returns:

True if the sample could be redeposited, False otherwise. Returns None if it’s not set.

Return type:

bool or None

set_group(group: str) → None

Sets the group that the sample belongs to based on stratigraphic interconnection with other samples.

Parameters:

group (str) – The group that the sample belongs to.

set_likelihood(distribution: ndarray, mean: float | None = None, rng: List[float] | None = None) → None

Sets the likelihood for the sample.

Parameters:

  • distribution (np.ndarray) – The likelihood distribution for the sample. It should be in the format np.array([p, …]), where p is the probability of the calendar year.

  • mean (float, optional) – The mean of the likelihood distribution. Defaults to None.

  • rng (List[float], optional) – The 2-sigma (95.45%) range of the likelihood distribution in calendar years BP. It should be in the format [from, to]. Defaults to None.

set_outlier(state: bool) → None

Sets the outlier status of the sample.

Parameters:

state (bool) – The outlier status to be set. True if the sample is an outlier and should not be used for modeling, False otherwise.

Raises:

Exception – If the provided state is not a boolean value.

set_phase(phase: float) → None

Sets the stratigraphic phase of the sample within the group.

Parameters:

phase (float) – The stratigraphic phase of the sample within the group (lower = earlier (older) phase).

set_phasing_range(rng: List[float]) → None

Sets the range of possible stratigraphic phases of the sample within the group.

Parameters:

rng (List[float]) – The range of possible stratigraphic phases of the sample within the group (lower = earlier (older) phase).

set_posterior(distribution: ndarray, mean: float | None = None, rng: List[float] | None = None, agreement: float = 0) → None

Sets the posterior for the sample.

Parameters:

  • distribution (np.ndarray) – The posterior distribution for the sample. It should be in the format np.array([p, …]), where p is the probability of the calendar year.

  • mean (float, optional) – The mean of the posterior distribution. Defaults to None.

  • rng (List[float], optional) – The 2-sigma (95.45%) range of the posterior distribution in calendar years BP. It should be in the format [from, to]. Defaults to None.

  • agreement (float, optional) – The agreement index generated by OxCal modeling. Defaults to 0.

property site_phase: str

The chronological phase of the context within the site.

Returns:

The chronological phase of the context within the site (format: “1” or “1a” or “1-2” or “1a-b” or “1a-2b”, lower = earlier (older) phase) or None if it’s not set.

Return type:

str or None

to_dict() → dict

Converts the sample data to a dictionary.

The method creates a deep copy of the sample data and converts numpy arrays to lists for JSON serialization.

Returns:

A dictionary containing the sample data.

Return type:

dict

to_oxcal() → str

Converts the sample to OxCal model format.

Returns:

The sample in OxCal model format or None if the necessary sample data (name, age, uncertainty, date_type, long_lived, outlier) is not set.

Return type:

str or None

property uncertainty: float

The uncertainty of the sample’s C-14 age in years BP.

Returns:

The uncertainty of the sample’s age or None if it’s not set.

Return type:

float or None

property years: ndarray

Calendar years BP corresponding to the probability distributions.

Returns:

An array of calendar years BP corresponding to the probability distributions or None if it’s not set.

Return type:

np.ndarray or None