pyvalues¶

class pyvalues.AttainmentScore(*, attained: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, constrained: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0)¶

Bases: BaseModel

A total Score for a value, split into a score for value (partially) attained and value (partially) constrained.

A score represents an effect size, confidence, or something else between (both inclusive) 0 (no effect/confidence/etc.) and 1 (maximum effect/confidence/etc.).

attained: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])]¶: Score for partially attaining a value (in some way).

constrained: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])]¶: Score for partially constraining a value (in some way).

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyvalues.Document(*, id: str | None = None, language: LanguageAlpha2 = 'en', segments: list[str] | None = None)¶

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

static read_tsv(input_file: str | ~pathlib.Path, segmenter: ~typing.Callable[[str, ~pydantic_extra_types.language_code.LanguageAlpha2], ~typing.Iterable[str]] = <function Document.<lambda>>, document_id: str | None = None, language: ~pydantic_extra_types.language_code.LanguageAlpha2 | str = 'en', delimiter: str = '\t', document_id_field: str | None = None, language_field: str | None = None, text_field: str = 'Text', **kwargs) → Generator[Document, None, None]¶

Reads a tab-separated file (or one with a different delimiter).

By default, each row is treated as its own document unless either (1) the document_id_field parameter is set and specifies a column name of the file, in which case consecutive rows with the same ID are treated as one document; or (2) the document_id parameter is set, in which case the set value is used for rows without ID.

Parameters:

input_file (str | Path) – The tab-separated values file to read.
segmenter (Callable[[str, LanguageAlpha2], Iterable[str]]) – Segmenter used to split the text into segments. Takes a the text to split and the text language as parameters. Default: use complete text as single segment.
document_id (str | None) – Default document ID to use when no ID is found in the row or when document_id_field is not specified.
language (LanguageAlpha2 | str) – Default language (ISO 639-1 / alpha-2) to use when no language is found in the row or when language_field is not specified.
delimiter (str) – Field delimiter used in the file (defaults to tab).
document_id_field (str | None) – Name of the column containing document IDs. When provided, consecutive rows with the same ID are grouped into a single document; Default: None
language_field (str | None) – Name of the column containing language codes. When provided, the value in this column overrides the default language for the current row (and thus the current document); Default: None
text_field (str) – Name of the column containing segment text. Values from this column are collected into the segments attribute of the resulting document after running them through the segmenter; Default: “Text”
kwargs – Additional keyword arguments passed to csv.DictReader.

Returns:

A generator yielding the read documents.

Return type:

Generator[Document, None, None]

static read_txt(input_file: str | ~pathlib.Path, segmenter: ~typing.Callable[[str], ~typing.Iterable[str]] = <function Document.<lambda>>, document_id: str | None = None, language: ~pydantic_extra_types.language_code.LanguageAlpha2 | str = 'en') → Document¶

Reads a text file.

By default, the text file is read as one segment, but a segmenter can be provided to split the text content.

Parameters:

input_file (str | Path) – The text file to read.
segmenter (Callable[[str], Iterable[str]]) – Segmenter used to split the text into segments. Default: use complete text as single segment.
document_id (str | None) – Identifier for the document.
language (LanguageAlpha2 | str) – Language of the document in ISO 639-1 / alpha-2.

class pyvalues.OriginalValues(*, self_direction: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, stimulation: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, hedonism: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, achievement: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, power: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, security: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, tradition: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, conformity: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, benevolence: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, universalism: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0)¶

Bases: ValuesWithoutAttainment

Scores for the ten values from Schwartz original system.

convert(target: Type[VALUES2]) → VALUES2¶

Converts the scores to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted scores
Return type:: Values

classmethod from_list(scores: list[float], cap_at_one: bool = False) → OriginalValues¶

Creates a value scores object from a list of scores (in the order of names())

Parameters:

scores (list[float]) – The scores in the order of names()
cap_at_one – Whether to cap the scores at 1 - for scores with attainment, scale attained and constrained down to have at most 1 total; Default: False (throw an error instead of capping)

Returns:

The value scores object

Return type:

Self

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'serialize_by_alias': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod names() → list[str]¶

Gets the names of the value scores.

If the scores have attainment, one is returned for value (partially) attained (with suffix “ attained”) and another one for value (partially) constrained (” constrained”).

The order is the same as for to_list().

Returns:: The list of names
Return type:: list[str]

to_list() → list[float]¶

Gets the single scores, in the same order as names().

Returns:: The list of scores
Return type:: list[float]

class pyvalues.OriginalValuesWithAttainment(*, self_direction: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), stimulation: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), hedonism: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), achievement: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), power: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), security: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), tradition: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), conformity: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), benevolence: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), universalism: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0))¶

Bases: ValuesWithAttainment

Scores with attainment for the ten values from Schwartz original system.

attained() → OriginalValues¶

Takes the scores of the values for attained only, dropping for constrained.

Returns:: The attained scores
Return type:: OriginalValues

constrained() → OriginalValues¶

Takes the scores of the values for constrained only, dropping for attained.

Returns:: The constrained scores
Return type:: OriginalValues

convert(target: Type[VALUES2]) → VALUES2¶

Converts the scores to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted scores
Return type:: Values

classmethod from_list(scores: list[float], cap_at_one: bool = False) → OriginalValuesWithAttainment¶

Creates a value scores object from a list of scores (in the order of names())

Parameters:

scores (list[float]) – The scores in the order of names()
cap_at_one – Whether to cap the scores at 1 - for scores with attainment, scale attained and constrained down to have at most 1 total; Default: False (throw an error instead of capping)

Returns:

The value scores object

Return type:

Self

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'serialize_by_alias': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod names() → list[str]¶

Gets the names of the value scores.

If the scores have attainment, one is returned for value (partially) attained (with suffix “ attained”) and another one for value (partially) constrained (” constrained”).

The order is the same as for to_list().

Returns:: The list of names
Return type:: list[str]

to_list() → list[float]¶

Gets the single scores, in the same order as names().

Returns:: The list of scores
Return type:: list[float]

without_attainment() → OriginalValues¶

Combines the scores of the values with the same attainment by taking their sum.

E.g., ‘Achievement attained’ and ‘Achievement constrained’ to ‘Achievement’.

Returns:: The combined and scores
Return type:: OriginalValues

class pyvalues.RefinedCoarseValues(*, self_direction: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, stimulation: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, hedonism: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, achievement: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, power: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, face: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, security: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, tradition: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, conformity: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, humility: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, benevolence: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, universalism: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0)¶

Bases: ValuesWithoutAttainment

Scores for the twelve values from Schwartz refined system (19 values) when combining values with same name prefix.

convert(target: Type[VALUES2]) → VALUES2¶

Converts the scores to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted scores
Return type:: Values

classmethod from_list(scores: list[float], cap_at_one: bool = False) → RefinedCoarseValues¶

Creates a value scores object from a list of scores (in the order of names())

Parameters:

scores (list[float]) – The scores in the order of names()
cap_at_one – Whether to cap the scores at 1 - for scores with attainment, scale attained and constrained down to have at most 1 total; Default: False (throw an error instead of capping)

Returns:

The value scores object

Return type:

Self

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'serialize_by_alias': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod names() → list[str]¶

Gets the names of the value scores.

If the scores have attainment, one is returned for value (partially) attained (with suffix “ attained”) and another one for value (partially) constrained (” constrained”).

The order is the same as for to_list().

Returns:: The list of names
Return type:: list[str]

original_values() → OriginalValues¶

Drops Face and Humility scores.

Returns:: The reduced scores
Return type:: OriginalValues

to_list() → list[float]¶

Gets the single scores, in the same order as names().

Returns:: The list of scores
Return type:: list[float]

class pyvalues.RefinedCoarseValuesWithAttainment(*, self_direction: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), stimulation: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), hedonism: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), achievement: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), power: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), face: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), security: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), tradition: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), conformity: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), humility: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), benevolence: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), universalism: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0))¶

Bases: ValuesWithAttainment

Scores with attainment for the twelve values from Schwartz refined system (19 values) when combining values with same name prefix.

attained() → RefinedCoarseValues¶

Takes the scores of the values for attained only, dropping for constrained.

Returns:: The attained scores
Return type:: RefinedCoarseValues

constrained() → RefinedCoarseValues¶

Takes the scores of the values for constrained only, dropping for attained.

Returns:: The constrained scores
Return type:: RefinedCoarseValues

convert(target: Type[VALUES2]) → VALUES2¶

Converts the scores to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted scores
Return type:: Values

classmethod from_list(scores: list[float], cap_at_one: bool = False) → RefinedCoarseValuesWithAttainment¶

Creates a value scores object from a list of scores (in the order of names())

Parameters:

scores (list[float]) – The scores in the order of names()
cap_at_one – Whether to cap the scores at 1 - for scores with attainment, scale attained and constrained down to have at most 1 total; Default: False (throw an error instead of capping)

Returns:

The value scores object

Return type:

Self

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'serialize_by_alias': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod names() → list[str]¶

Gets the names of the value scores.

If the scores have attainment, one is returned for value (partially) attained (with suffix “ attained”) and another one for value (partially) constrained (” constrained”).

The order is the same as for to_list().

Returns:: The list of names
Return type:: list[str]

original_values() → OriginalValuesWithAttainment¶

Drops Face and Humility scores.

Returns:: The reduced scores
Return type:: OriginalValuesWithAttainment

to_list() → list[float]¶

Gets the single scores, in the same order as names().

Returns:: The list of scores
Return type:: list[float]

without_attainment() → RefinedCoarseValues¶

Combines the scores of the values with the same attainment by taking their sum.

E.g., ‘Achievement attained’ and ‘Achievement constrained’ to ‘Achievement’.

Returns:: The combined scores
Return type:: RefinedCoarseValues

class pyvalues.RefinedValues(*, self_direction_thought: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, self_direction_action: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, stimulation: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, hedonism: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, achievement: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, power_dominance: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, power_resources: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, face: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, security_personal: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, security_societal: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, tradition: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, conformity_rules: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, conformity_interpersonal: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, humility: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, benevolence_caring: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, benevolence_dependability: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, universalism_concern: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, universalism_nature: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, universalism_tolerance: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0)¶

Bases: ValuesWithoutAttainment

Scores for the 19 values from Schwartz refined system.

coarse_values(mode: ~typing.Callable[[~typing.Iterable[float]], float] = <built-in function max>) → RefinedCoarseValues¶

Combines the scores of the values with the same prefix.

E.g., ‘Universalism: concern’, ‘Universalism: nature’, and ‘Universalism: tolerance’ to ‘Universalism’.

Parameters:: mode (Callable[[Iterable[float]], float]) – Function to combine the scores (default: max)
Returns:: The combined scores
Return type:: RefinedCoarseValues

convert(target: Type[VALUES2]) → VALUES2¶

Converts the scores to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted scores
Return type:: Values

classmethod from_list(scores: list[float], cap_at_one: bool = False) → RefinedValues¶

Creates a value scores object from a list of scores (in the order of names())

Parameters:

scores (list[float]) – The scores in the order of names()
cap_at_one – Whether to cap the scores at 1 - for scores with attainment, scale attained and constrained down to have at most 1 total; Default: False (throw an error instead of capping)

Returns:

The value scores object

Return type:

Self

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'serialize_by_alias': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod names() → list[str]¶

Gets the names of the value scores.

If the scores have attainment, one is returned for value (partially) attained (with suffix “ attained”) and another one for value (partially) constrained (” constrained”).

The order is the same as for to_list().

Returns:: The list of names
Return type:: list[str]

original_values(mode: ~typing.Callable[[~typing.Iterable[float]], float] = <built-in function max>) → OriginalValues¶

Combines the scores of the values with the same prefix and drops Face and Humility.

E.g., ‘Universalism: concern’, ‘Universalism: nature’, and ‘Universalism: tolerance’ to ‘Universalism’.

Parameters:: mode (Callable[[Iterable[float]], float]) – Function to combine the scores (default: max)
Returns:: The combined and reduced scores
Return type:: OriginalValues

to_list() → list[float]¶

Gets the single scores, in the same order as names().

Returns:: The list of scores
Return type:: list[float]

class pyvalues.RefinedValuesWithAttainment(*, self_direction_thought: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), self_direction_action: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), stimulation: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), hedonism: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), achievement: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), power_dominance: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), power_resources: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), face: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), security_personal: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), security_societal: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), tradition: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), conformity_rules: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), conformity_interpersonal: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), humility: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), benevolence_caring: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), benevolence_dependability: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), universalism_concern: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), universalism_nature: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0), universalism_tolerance: AttainmentScore = AttainmentScore(attained=0.0, constrained=0.0))¶

Bases: ValuesWithAttainment

Scores with attainment for the 19 values from Schwartz refined system.

attained() → RefinedValues¶

Takes the scores of the values for attained only, dropping for constrained.

Returns:: The attained scores
Return type:: RefinedValues

coarse_values(mode: ~typing.Callable[[~typing.Iterable[float]], float] = <built-in function max>) → RefinedCoarseValuesWithAttainment¶

Combines the scores of the values with the same prefix and attainment.

E.g., ‘Universalism: concern attained’, ‘Universalism: nature attained’, and ‘Universalism: tolerance attained’ to ‘Universalism attained’.

Parameters:: mode (Callable[[Iterable[float]], float]) – Function to combine the scores (default: max)
Returns:: The combined scores
Return type:: RefinedCoarseValuesWithAttainment

constrained() → RefinedValues¶

Takes the scores of the values for constrained only, dropping for attained.

Returns:: The constrained scores
Return type:: RefinedValues

convert(target: Type[VALUES2]) → VALUES2¶

Converts the scores to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted scores
Return type:: Values

classmethod from_list(scores: list[float], cap_at_one: bool = False) → RefinedValuesWithAttainment¶

Creates a value scores object from a list of scores (in the order of names())

Parameters:

scores (list[float]) – The scores in the order of names()
cap_at_one – Whether to cap the scores at 1 - for scores with attainment, scale attained and constrained down to have at most 1 total; Default: False (throw an error instead of capping)

Returns:

The value scores object

Return type:

Self

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'serialize_by_alias': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod names() → list[str]¶

Gets the names of the value scores.

If the scores have attainment, one is returned for value (partially) attained (with suffix “ attained”) and another one for value (partially) constrained (” constrained”).

The order is the same as for to_list().

Returns:: The list of names
Return type:: list[str]

original_values(mode: ~typing.Callable[[~typing.Iterable[float]], float] = <built-in function max>) → OriginalValuesWithAttainment¶

Combines the scores of the values with the same prefix and attainment, and drops Face and Humility.

E.g., ‘Universalism: concern attained’, ‘Universalism: nature attained’, and ‘Universalism: tolerance attained’ to ‘Universalism attained’.

Parameters:: mode (Callable[[Iterable[float]], float]) – Function to combine the scores (default: max)
Returns:: The combined and reduced scores
Return type:: OriginalValuesWithAttainment

to_list() → list[float]¶

Gets the single scores, in the same order as names().

Returns:: The list of scores
Return type:: list[float]

without_attainment() → RefinedValues¶

Combines the scores of the values with the same attainment by taking their sum.

E.g., ‘Achievement attained’ and ‘Achievement constrained’ to ‘Achievement’.

Returns:: The combined scores
Return type:: RefinedValues

class pyvalues.Values¶

Bases: ABC, BaseModel

Scores (with or without attainment) for any system of values.

classmethod average(value_scores_list: Iterable[Self]) → Self¶

Creates a new values score object with each score being the average of the respective scores in the input

Parameters:: value_scores_list (Iterable[Self]) – The scores to average
Returns:: The averaged scores
Return type:: Self

classmethod average_documents(documents: Iterable[ValuesAnnotatedDocument[Self]]) → Self¶

Creates a new values score object with each score being the average of the respective average score of each document in the input

Parameters:: documents (Iterable[ValuesAnnotatedDocument[Self]]) – The documents to average
Returns:: The averaged scores
Return type:: Self

binarize(threshold: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | Self = 0.5) → Self¶

Gets the scores as either 1 (if at least at threshold) or 0 (otherwise).

If the scores are with attainment, the total (attained + constrained) is checked against the threshold and, if equal or higher, the higher one (attained or constrained) is set to 1 and the smaller one to 0.

Parameters:: threshold (Score | Self) – The threshold for becoming 1, either a single number for all values or a values score object with each score being the corresponding threshold for that value
Returns:: A new object with scores either 0 or 1
Return type:: Self

abstractmethod convert(target: Type[VALUES2]) → VALUES2¶

Converts the scores to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted scores
Return type:: Values

abstractmethod classmethod from_list(scores: list[float], cap_at_one: bool = False) → Self¶

Creates a value scores object from a list of scores (in the order of names())

Parameters:

scores (list[float]) – The scores in the order of names()
cap_at_one – Whether to cap the scores at 1 - for scores with attainment, scale attained and constrained down to have at most 1 total; Default: False (throw an error instead of capping)

Returns:

The value scores object

Return type:

Self

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

abstractmethod classmethod names() → list[str]¶

Gets the names of the value scores.

If the scores have attainment, one is returned for value (partially) attained (with suffix “ attained”) and another one for value (partially) constrained (” constrained”).

The order is the same as for to_list().

Returns:: The list of names
Return type:: list[str]

classmethod read_tsv(input_file: str | Path, document_id: str | None = None, language: LanguageAlpha2 | str = 'en', delimiter: str = '\t', document_id_field: str | None = None, language_field: str | None = None, segment_field: str | None = None, **kwargs) → Generator[ValuesAnnotatedDocument[Self], None, None]¶

Reads a tab-separated values file (or one with a different delimiter).

By default, each row is treated as its own document unless either (1) the document_id_field parameter is set and specifies a column name of the file, in which case consecutive rows with the same ID are treated as one document; or (2) the document_id parameter is set, in which case the set value is used for rows without ID.

Parameters:

input_file (str | Path) – The tab-separated values file to read.
document_id (str | None) – Default document ID to use when no ID is found in the row or when document_id_field is not specified.
language (LanguageAlpha2 | str) – Default language (ISO 639-1 / alpha-2) to use when no language is found in the row or when language_field is not specified.
delimiter (str) – Field delimiter used in the file (defaults to tab).
document_id_field (str | None) – Name of the column containing document IDs. When provided, consecutive rows with the same ID are grouped into a single document; Default: None
language_field (str | None) – Name of the column containing language codes. When provided, the value in this column overrides the default language for the current row (and thus the current document); Default: None
segment_field (str | None) – Name of the column containing segment text. When provided, values from this column are collected into the segments attribute of the resulting document; Default: None
kwargs – Additional keyword arguments passed to csv.DictReader.

Returns:

A generator yielding ValuesAnnotatedDocument[Self] instances.

Return type:

Generator[ValuesAnnotatedDocument[Self], None, None]

abstractmethod to_list() → list[float]¶

Gets the single scores, in the same order as names().

Returns:: The list of scores
Return type:: list[float]

abstractmethod top(k: int = 1, binarize: bool = False) → Self¶

Gets the k highest scores by setting all others to 0.

If the scores are with attainment, the total scores are used to determine the highest ones. The split score (attained and constrained) of the highest are kept as they are.

Parameters:

k (int) – The number of values for which to not set the scores to 0.
binarize (bool) – Whether to set the highest scores to 1 instead of just keeping them (default). If the scores are with attainment, the higher one (attained or constrained) is set to 1 and the smaller one to 0.

Returns:

A new object with only the k highest scores

Return type:

Self

class pyvalues.ValuesAnnotatedDocument(*, id: str | None = None, language: LanguageAlpha2 = 'en', segments: list[str] | None = None)¶

Bases: Document, Generic[VALUES]

average() → ValuesAnnotatedDocument¶

Creates a new document with each score being the average of this document’s respective scores

Returns:: The averaged scores
Return type:: Self

binarize(threshold: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | VALUES = 0.5) → ValuesAnnotatedDocument¶

Gets the scores as either 1 (if at least at threshold) or 0 (otherwise).

Parameters:: threshold (Score | VALUES) – The threshold for becoming 1, either a single number for all values or a values score object with each score being the corresponding threshold for that value
Returns:: A new document with scores either 0 or 1
Return type:: Self

convert(target: Type[VALUES2]) → ValuesAnnotatedDocument[TypeVar]¶

Create a new document with all scores converted to the target class if possible.

If the scores can not be converted, a ValueError is raised.

Parameters:: target (Type[Values]) – The target class
Returns:: The converted document
Return type:: ValuesAnnotatedDocument[Values]

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyvalues.ValuesWithAttainment¶

Bases: Values

Scores with attainment for any system of values.

binarize(threshold: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=1)])] | Self = 0.5) → Self¶

Gets the scores as either 1 (if at least at threshold) or 0 (otherwise).

If the scores are with attainment, the total (attained + constrained) is checked against the threshold and, if equal or higher, the higher one (attained or constrained) is set to 1 and the smaller one to 0.

Parameters:: threshold (Score | Self) – The threshold for becoming 1, either a single number for all values or a values score object with each score being the corresponding threshold for that value
Returns:: A new object with scores either 0 or 1
Return type:: Self

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

top(k: int = 1, binarize: bool = False) → Self¶

Gets the k highest scores by setting all others to 0.

The total scores are used to determine the highest ones. The split score (attained and constrained) of the highest are kept as they are.

Parameters:

k (int) – The number of values for which to not set the scores to 0.
binarize (bool) – Whether to set the highest scores to 1 instead of just keeping them (default). Specifically, the higher one of attained or constrained is set to 1 and the smaller one to 0.

Returns:

A new object with only the k highest scores

Return type:

Self

class pyvalues.ValuesWithoutAttainment¶

Bases: Values

Scores without attainment for any system of values.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

plot(label=None, linecolor='black', fillcolor=None, fillalpha=0.25, **kwargs)¶

Plot theses scores in a radar plot.

Returns the matplotlib module, so one can directly use savefig(file) or show() on the returned value.

import pyvalues
values = pyvalues.OriginalValues.from_list([0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1.0])
values.plot(label="my values").show()

Parameters:

label (str | None) – The label to use in the legend, if any
linecolor (str) – The color of the line to draw
fillcolor (str | None) – The area fill to draw, if any
fillalpha (float) – The alpha channel of the fill color
kwargs – Arguments to pass on for plotting, especially gridlines (list[float])

static plot_all(value_scores_list: Sequence[ValuesWithoutAttainment], **kwargs)¶

Plot scores in a radar plot.

Returns the matplotlib module, so one can directly use savefig(file) or show() on the returned value.

import pyvalues
values = pyvalues.OriginalValues.from_list([0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1.0])
pyvalues.plot_all([values], labels=["my values"]).show()

Parameters:

value_scores_list (Sequence["ValuesWithoutAttainment"]) – The scores to plot
kwargs – Arguments to pass on for plotting, especially labels (list[str]), linecolors (list[str]), fillcolors (list[str]), fillalphas (list[str]), and gridlines (list[float])

top(k: int = 1, binarize: bool = False) → Self¶

Gets the k highest scores by setting all others to 0.

Parameters:

k (int) – The number of values for which to not set the scores to 0.
binarize (bool) – Whether to set the highest scores to 1 instead of just keeping them (default).

Returns:

A new object with only the k highest scores

Return type:

Self

pyvalues¶

pyvalues

Navigation

Related Topics