# pydicom.dataelem.DataElement

class `pydicom.dataelem.``DataElement`(tag, VR, value, file_value_tell=None, is_undefined_length=False, already_converted=False)

  Contain and manipulate a DICOM Element.

  Examples

  While its possible to create a new `DataElement` directly and add it to a `Dataset`:

      >>> from pydicom import Dataset
      >>> elem = DataElement(0x00100010, 'PN', 'CITIZEN^Joan')
      >>> ds = Dataset()
      >>> ds.add(elem)

  Its far more convenient to use a `Dataset` to add a new `DataElement`, as the VR and tag are determined automatically from the DICOM dictionary:

      >>> ds = Dataset()
      >>> ds.PatientName = 'CITIZEN^Joan'

  Empty DataElement objects (e.g. with VM = 0) show an empty string as value for text VRs and None for non-text (binary) VRs:

      >>> ds = Dataset()
      >>> ds.PatientName = None
      >>> ds.PatientName
      ''

      >>> ds.BitsAllocated = None
      >>> ds.BitsAllocated

      >>> str(ds.BitsAllocated)
      'None'

  `descripWidth`

    For string display, this is the maximum width of the description field (default `35`).

    Type: | int

  `is_retired`

    For officially registered DICOM Data Elements this will be `True` if the retired status as given in the DICOM Standard, Part 6, Table 6-1 is ‘RET’. For private or unknown elements this will always be `False`.

    Type: | bool

  `is_undefined_length`

    Indicates whether the length field for the element was `0xFFFFFFFFL` (ie undefined).

    Type: | bool

  `keyword`

    For officially registered DICOM Data Elements this will be the Keyword as given in Table 6-1. For private or unknown elements this will return an empty string `''`.

    Type: | str

  `maxBytesToDisplay`

    For string display, elements with values containing data which is longer than this value will display `"array of # bytes"` (default `16`).

    Type: | int

  `name`

    For officially registered DICOM Data Elements this will be the Name as given in Table 6-1. For private elements known to pydicom this will be the Name in the format `'[name]'`. For unknown private elements this will be `'Private Creator'`. For unknown elements this will return an empty string `''`.

    Type: | str

  `showVR`

    For string display, include the element’s VR just before it’s value (default `True`).

    Type: | bool

  `tag`

    The element’s tag.

    Type: | BaseTag

  `value`

    The element’s stored value(s).

  `VM`

    The Value Multiplicity of the element’s stored value(s).

    Type: | int

  `VR`

    The element’s Value Representation.

    Type: | str

  `__init__`(tag, VR, value, file_value_tell=None, is_undefined_length=False, already_converted=False)

    Create a new `DataElement`.

    Parameters:

    - tag (int or or str or list or tuple) – The DICOM (group, element) tag in any form accepted by `Tag()` such as `[0x0010, 0x0010]`, `(0x10, 0x10)`, `0x00100010`, etc.
    - VR (str) – The 2 character DICOM value representation (see DICOM Standard, Part 5, Section 6.2).
    - value –

      The value of the data element. One of the following:

      - a single string value
      - a number
      - a `list` or `tuple` with all strings or all numbers
      - a multi-value string with backslash separator
    - file_value_tell (int or None) – Used internally by `Dataset` to store the write position for the `ReplaceDataElementValue()` method. Default is `None`.
    - is_undefined_length (bool) – Used internally to store whether the length field for this element was `0xFFFFFFFFL`, i.e. ‘undefined length’. Default is `False`.
    - already_converted (bool) – Used to determine whether or not the element’s value requires conversion to a value with VM > 1. Default is `False`.

  Methods

  `__init__`(tag, VR, value[, file_value_tell, …]) | Create a new `DataElement`.
  `clear`() | Clears the value, e.g.
  `description`() | Return the DICOM dictionary name for the element as `str`.
  `from_json`(dataset_class, tag, vr, value, …) | Return a `DataElement` from JSON.
  `to_json`([bulk_data_threshold, …]) | Return a JSON representation of the `DataElement`.
  `to_json_dict`(bulk_data_element_handler, …) | Return a dictionary representation of the `DataElement` conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, Annex F.

  Attributes

  `VM` | Return the value multiplicity of the element as `int`.
  `descripWidth` |
  `empty_value` | Return the value for an empty element.
  `is_empty` | Return `True` if the element has no value.
  `is_raw` |
  `is_retired` | Return the element’s retired status as `bool`.
  `keyword` | Return the element’s keyword (if known) as `str`.
  `maxBytesToDisplay` |
  `name` | Return the DICOM dictionary name for the element as `str`.
  `repval` | Return a `str` representation of the element’s value.
  `showVR` |
  `value` | Return the element’s value.

  `VM`

    Return the value multiplicity of the element as `int`.

  `clear`()

    Clears the value, e.g. sets it to the configured empty value.

    New in version 1.4.

    See `empty_value_for_VR()`.

  `description`()

    Return the DICOM dictionary name for the element as `str`.

  `empty_value`

    Return the value for an empty element.

    New in version 1.4.

    See `empty_value_for_VR()` for more information.

    Returns: | The value this data element is assigned on decoding if it is empty.
    Return type: | str or None

  classmethod `from_json`(dataset_class, tag, vr, value, value_key, bulk_data_uri_handler=None)

    Return a `DataElement` from JSON.

    New in version 1.3.

    Parameters:

    - dataset_class (dataset.Dataset derived class) – Class used to create sequence items.
    - tag (BaseTag or int) – The data element tag.
    - vr (str) – The data element value representation.
    - value (list) – The data element’s value(s).
    - value_key (str or None) – Key of the data element that contains the value (options: `{"Value", "InlineBinary", "BulkDataURI"}`)
    - bulk_data_uri_handler (callable or None) – Callable function that accepts the “BulkDataURI” of the JSON representation of a data element and returns the actual value of that data element (retrieved via DICOMweb WADO-RS)

    Returns: |
    Return type: | DataElement

  `is_empty`

    Return `True` if the element has no value.

    New in version 1.4.

  `is_retired`

    Return the element’s retired status as `bool`.

  `keyword`

    Return the element’s keyword (if known) as `str`.

  `name`

    Return the DICOM dictionary name for the element as `str`.

  `repval`

    Return a `str` representation of the element’s value.

  `to_json`(bulk_data_threshold=1024, bulk_data_element_handler=None, dump_handler=None)

    Return a JSON representation of the `DataElement`.

    New in version 1.3.

    Parameters:

    - bulk_data_element_handler (callable or None) – Callable that accepts a bulk data element and returns the “BulkDataURI” for retrieving the value of the data element via DICOMweb WADO-RS
    - bulk_data_threshold (int) – Size of base64 encoded data element above which a value will be provided in form of a “BulkDataURI” rather than “InlineBinary”. Ignored if no bulk data handler is given.
    - dump_handler (callable, optional) – Callable function that accepts a `dict` and returns the serialized (dumped) JSON string (by default uses `json.dumps()`).

    Returns: | Mapping representing a JSON encoded data element
    Return type: | dict

    See also

    `Dataset.to_json()`

  `to_json_dict`(bulk_data_element_handler, bulk_data_threshold)

    Return a dictionary representation of the `DataElement` conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, Annex F.

    New in version 1.4.

    Parameters:

    - bulk_data_element_handler (callable or None) – Callable that accepts a bulk data element and returns the “BulkDataURI” for retrieving the value of the data element via DICOMweb WADO-RS
    - bulk_data_threshold (int) – Size of base64 encoded data element above which a value will be provided in form of a “BulkDataURI” rather than “InlineBinary”. Ignored if no bulk data handler is given.

    Returns: | Mapping representing a JSON encoded data element
    Return type: | dict

  `value`

    Return the element’s value.