Element VRs and Python types¶

DICOM elements can contain anything from ASCII strings to unicode text, decimals, floats, signed and unsigned integers of different byte-depth and even encoded data. The format of the value of an element is given by its Value Representation or VR, and a list of VRs is given in the DICOM Standard in Part 5, Table 6.2-1.

So when using pydicom, what Python type should be used with a given VR to ensure that the value gets written correctly?

Elements of any VR:
- Can be set as empty by using None
- Can have their values set using their set using or stored as type from the table below
Non-SQ element values:
- Can also be set using a list of their set using type - for Value Multiplicity (VM) > 1, the value will be stored as a MultiValue of their stored as type
- However, according to the DICOM Standard, elements with VR LT, OB, OD, OF, OL, OW, ST, UN, UR and UT should never have a VM greater than 1.
SQ element values should be set using a list of zero or more Dataset instances.
To ensure AT elements are encoded correctly, their values should be set using the 8-byte integer form of the tag - such as 0x00100020 for the tag (0010,0020) - and not as a 2-tuple or 2-list.

VR	Name	Set using	Stored as
AE	Application Entity	`str`	`str`
AS	Age String	`str`	`str`
AT	Attribute Tag	`int`	`int`
CS	Code String	`str`	`str`
DA	Date	`str`	`str` or `DA`¹
DS	Decimal String	`str`, `float` or `int`	`DSfloat` or `DSdecimal`²
DT	Date Time	`str`	`str` or `DT`¹
FL	Floating Point Single	`float`	`float`
FD	Floating Point Double	`float`	`float`
IS	Integer String	`str` or `int`	`IS`
LO	Long String	`str`	`str`
LT	Long Text	`str`	`str`
OB	Other Byte	`bytes`	`bytes`
OD	Other Double	`bytes`	`bytes`
OF	Other Float	`bytes`	`bytes`
OL	Other Long	`bytes`	`bytes`
OV	Other 64-bit Very Long	`bytes`	`bytes`
OW	Other Word	`bytes`	`bytes`
PN	Person Name	`str`	`PersonName`
SH	Short String	`str`	`str`
SL	Signed Long	`int`	`int`
SQ	Sequence of Items	`list`	`Sequence`
SS	Signed Short	`int`	`int`
ST	Short Text	`str`	`str`
SV	Signed 64-bit Very Long	`int`	`int`
TM	Time	`str`	`str` or `TM`¹
UC	Unlimited Characters	`str`	`str`
UI	Unique Identifier (UID)	`str`	`UID`
UL	Unsigned Long	`int`	`int`
UN	Unknown	`bytes`	`bytes`
UR	URI/URL	`str`	`str`
US	Unsigned Short	`int`	`int`
UT	Unlimited Text	`str`	`str`
UV	Unsigned 64-bit Very Long	`int`	`int`

¹ If config.datetime_conversion = True (default False)

² If config.use_DS_decimal = True (default False)