Skip to content

Survey Instruments

Instrument dataclass 

Instrument(scales, anchors, details, norms=None, _data=None)

A class for representing circumplex instruments.

ATTRIBUTE DESCRIPTION
scales

Scales

TYPE: Scales

anchors

Anchors

TYPE: Anchors

details

InstrumentDetails

TYPE: InstrumentDetails

inst_items

Items | None = None
_data

pd.DataFrame | None = None

TYPE: DataFrame | None

from_dict 

from_dict(inst_dict)

Compose an Instrument object from a dictionary.

Typically this would be used to load an instrument from one of our built in JSON files. Args: inst_dict: A dictionary containing the instrument's details, scales, anchors, and items.

RETURNS DESCRIPTION
Instrument

An Instrument object.

TYPE: Instrument

Source code in circumplex/instrument.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def from_dict(inst_dict: dict) -> Instrument:
    """
    Compose an Instrument object from a dictionary.

    Typically this would be used to load an instrument from one of our built in JSON files.
    Args:
        inst_dict: A dictionary containing the instrument's details, scales, anchors, and items.

    Returns:
        Instrument: An Instrument object.
    """
    items_exist = sum(
        ["inst_items" in scale.keys() for scale in inst_dict["scales"].values()]
    )
    scales = Scales(
        abbrev=list(inst_dict["scales"].keys()),
        label=[scale["label"] for scale in inst_dict["scales"].values()],
        angle=[scale["angle"] for scale in inst_dict["scales"].values()],
        inst_items=[
            inst_dict["scales"][scale]["inst_items"] for scale in inst_dict["scales"].keys()
        ]
        if items_exist
        else None,
    )
    anchors = Anchors(
        value=[int(key) for key in inst_dict["anchors"].keys()],
        label=list(inst_dict["anchors"].values()),
    )
    norms = Norms(
        table=pd.DataFrame.from_dict(inst_dict["norms"]),
        src=pd.DataFrame.from_dict(inst_dict["norms_src"])
    ) if "norms" in inst_dict else None
    details = InstrumentDetails(**inst_dict["details"])
    return Instrument(scales, anchors, details, norms)

instruments 

instruments()

Print a list of the instruments included in the circumplex package.

RETURNS DESCRIPTION
None

None
Source code in circumplex/instrument.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def instruments() -> None:
    """
    Print a list of the instruments included in the circumplex package.

    Args:
        None

    Returns:
        None
    """
    ins = {name: load_instrument(name) for name in INSTRUMENT_JSONS.keys()}
    print(f"The circumplex package currently includes {len(ins)} instruments:")
    i = 1
    for name, inst in ins.items():
        print(f"{i}. {name}: {inst.details.name} ({inst.details.abbrev})")
        i += 1

    return None

load_instrument 

load_instrument(instrument)

Load an instrument from one of our built-in JSON files.

PARAMETER DESCRIPTION
instrument

The name of the instrument to load. Must be one of the following: - CSIP

TYPE: str

RETURNS DESCRIPTION
Instrument

An Instrument object.

TYPE: Instrument

Source code in circumplex/instrument.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def load_instrument(instrument: str) -> Instrument:
    """
    Load an instrument from one of our built-in JSON files.

    Args:
        instrument: The name of the instrument to load. Must be one of the following:
            - CSIP

    Returns:
        Instrument: An Instrument object.
    """
    with open(INSTRUMENT_JSONS[instrument], "r") as f:
        instrument = json.load(f)

    return from_dict(instrument)