Elements commands

The elements subcommands allow you to perform operations on existing Arkindex elements.

Listing elements

The list subcommand can be used to generate a CSV file containing all the elements, or elements of a specific type, from a given corpus or parent element. By default, this listing is not recursive.

Basic usage

arkindex elements list --parent $ARKINDEX_ELEMENT_ID

This command will list all the elements, of any type, that are direct children of the given parent element, and write the output to a CSV file.

Arguments

Required arguments

The only required argument when running the list command is the UUID of the object whose objects you want to retrieve. You can provide that UUID either with the --corpus or --parent arguments: they are mutually exclusive.

Optional arguments

  • --type: specify the type of the elements you wish to retrieve.
arkindex elements list --corpus $ARKINDEX_CORPUS_ID --type page
  • --recursive: recursively list elements from the corpus/parent element. If unspecified, the list subcommand only retrieves direct children of the corpus/parent element.
arkindex elements list --parent $ARKINDEX_ELEMENT_ID --type text_line --recursive
  • --with-classes: also retrieve the classifications of the listed elements.
arkindex elements list --corpus $ARKINDEX_CORPUS_ID --type page --with-classes
  • --with-metadata: also retrieve the metadata of the listed elements.
arkindex elements list --corpus $ARKINDEX_CORPUS_ID --with-metadata
  • --output: specify the path to the output CSV file. If unspecified the file will be saved as elements.csv in the current working directory.
arkindex elements list --parent $ARKINDEX_CORPUS_ID --output $PATH/TO/file.csv

CSV output

The list command outputs a CSV file with one line per retrieved element, containing the following columns/information:

  • the id, name and type of the element (columns id, name and type);
  • the id and url of the element's image (columns image_id and image_url);
  • the element's polygon (polygon);
  • the id of the worker version that created this element, if it was created by a worker; if the element was not created by a worker this column is left blank (worker_version_id);
  • the element's creation date (created).
id,name,type,image_id,image_url,polygon,worker_version_id,created
element_id_1,element_name_1,element_type_1,image_id_1,image_url_1,"[[0, 0], [0, 360], [290, 360], [290, 0], [0, 0]]",,2022-05-10T16:07:24.358758Z
element_id_2,element_name_2,element_type_1,image_id_1,image_url_1,"[[0, 0], [0, 288], [312, 288], [312, 0], [0, 0]]",,2022-05-10T16:07:54.831403Z
element_id_3,element_name_3,element_type_2,image_id_2,image_url_2,"[[0, 0], [0, 355], [45, 355], [45, 0], [0, 0]]",worker_version_id_1,2022-05-10T18:06:12.358258Z

If the elements were listed using the --with-classes option, then the output CSV file contains one line per classification. If some elements have more than one classification, then there will be multiple lines corresponding to these elements. The CSV contains 3 additional columns:

  • the classification's name (class_name);
  • the classification's id (class_id);
  • the classification's confidence score (classification_confidence).
id,name,type,image_id,image_url,polygon,worker_version_id,created,class_name,class_id,classification_confidence
element_id_1,element_name_1,element_type_1,image_id_1,image_url_1,"[[0, 0], [0, 360], [290, 360], [290, 0], [0, 0]]",,2022-05-10T16:07:24.358758Z,class_name_1,class_id_1,0.8
element_id_2,element_name_2,element_type_1,image_id_1,image_url_1,"[[0, 0], [0, 288], [312, 288], [312, 0], [0, 0]]",,2022-05-10T16:07:54.831403Z,class_name_1,class_id_1,0.2
element_id_2,element_name_2,element_type_1,image_id_1,image_url_1,"[[0, 0], [0, 288], [312, 288], [312, 0], [0, 0]]",,2022-05-10T16:07:54.831403Z,class_name_2,class_id_2,0.6
element_id_3,element_name_3,element_type_2,image_id_2,image_url_2,"[[0, 0], [0, 355], [45, 355], [45, 0], [0, 0]]",worker_version_id_1,2022-05-10T18:06:12.358258Z,class_name_1,class_id_1,0.9

If the elements were listed using the --with-metadata option, the the output CSV contains one or more column per metadata name, which is filled with the corresponding value if the metadata is present on the element, or left blank. There can be more than one column per metadata name because the same metadata can be set on the same element with different values. When this is the case, the metadata columns are named like this: {metadata_name}_1, {metadata_name}_2…

⚠️ If you are listing a lot of elements, this can take a long time and/or fail because the metadata are all stored in memory before being written to the CSV file. You should generate the CSV file from an sqlite export instead.

id,name,type,image_id,image_url,polygon,worker_version_id,created,metadata_1,metadata_2,metadata_3_1,metadata_3_2
element_id_1,element_name_1,element_type_1,image_id_1,image_url_1,"[[0, 0], [0, 360], [290, 360], [290, 0], [0, 0]]",,2022-05-10T16:07:24.358758Z,,0,"some text value",
element_id_2,element_name_2,element_type_1,image_id_1,image_url_1,"[[0, 0], [0, 288], [312, 288], [312, 0], [0, 0]]",,2022-05-10T16:07:54.831403Z,12.5,2,,,
element_id_3,element_name_3,element_type_2,image_id_2,image_url_2,"[[0, 0], [0, 355], [45, 355], [45, 0], [0, 0]]",worker_version_id_1,2022-05-10T18:06:12.358258Z,3,0,"some text value","another value"

Linking elements

The link subcommand can be used to create relations between parent and children elements, in order to organize your data on Arkindex.

arkindex elements link --parent $PARENT_ELEMENT_ID --child $CHILD_ELEMENT_ID

You can only link elements that belong to the same corpus. The link subcommand only creates new relations between elements, it does not destroy/replace existing ones.

Parent element

You can use two (required, mutually exclusive) arguments when specifying the parent element.

  • --parent: the ID of an existing element on Arkindex.
arkindex elements link --parent $PARENT_ELEMENT_ID --child $CHILD_ELEMENT_ID
  • --create: instead of providing the ID of an Arkindex element, create that element and link the child element(s) to the newly created element. You will be prompted to enter the ID of the corpus in which to create the parent element (the same corpus the child element(s) belong to, for the link to work), an element type (one that exists in the target corpus) and a name for that new element.
arkindex elements link --create --child $CHILD_ELEMENT_ID

Child element(s)

You can use four (required, mutually exclusive) arguments as child inputs.

  • --child: one or more Arkindex element ID(s).
arkindex elements link --parent $PARENT_ELEMENT_ID --child $ID_1 $ID_2 $ID_3
  • --uuid-list: a path to a text file containing a list of element IDs, with one ID per line.
arkindex elements link --parent $PARENT_ELEMENT_ID --uuid-list $PATH/TO/file.txt
  • --selection: link the elements in your selection on Arkindex to the parent element.
arkindex elements link --parent $PARENT_ELEMENT_ID --selection
  • --stray-pages is specific to one operation: the linking of all the page elements that do not have a parent element, and are situated directly at the root of a corpus, to a parent element.
arkindex elements link --parent $PARENT_ELEMENT_ID --stray-pages

Unlinking elements

The unlink subcommand can be used to destroy relationships between parent and children elements, in order to organize your data on Arkindex.

arkindex elements unlink --parent $PARENT_ELEMENT_ID --child $CHILD_ELEMENT_ID

You can only unlink elements that belong to the same corpus. (Only elements belonging to the same corpus can be linked in the first place.)

Parent element

You have to specify the ID of the element from which you want to unlink the child element(s), using the --parent argument.

arkindex elements unlink --parent $PARENT_ELEMENT_ID --child $CHILD_ELEMENT_ID

Child element(s)

You can use three (required, mutually exclusive) arguments as child inputs.

  • --child: one or more Arkindex element ID(s).
arkindex elements unlink --parent $PARENT_ELEMENT_ID --child $ID_1 $ID_2 $ID_3
  • --uuid-list: a path to a text file containing a list of element IDs, with one ID per line.
arkindex elements unlink --parent $PARENT_ELEMENT_ID --uuid-list $PATH/TO/file.txt
  • --selection: unlink the elements in your selection on Arkindex from the parent element.
arkindex elements unlink --parent $PARENT_ELEMENT_ID --selection

Optional arguments

The --orphan flag allows you to unlink an element from the parent even if it does not have any other parent elements, which results in the element ending up directly at the root of the corpus.

arkindex elements unlink --parent $PARENT_ELEMENT_ID --child $CHILD_ELEMENT_ID --orphan

Without the --orphan argument, you cannot unlink an element and its parent if it has no other parent element.

Copying page elements

The page-copy subcommand can be used to copy Page elements to a folder, within or outside of their corpus of origin. It only copies Page elements, without any of their children. Technically, it creates a new Page element from the same Image, with the same name and type, inside another folder.

arkindex elements page-copy --folder $PARENT_ELEMENT_ID --pages $PAGE_ELEMENT_1 $PAGE_ELEMENT_2 $PAGE_ELEMENT_3

You can only copy pages to a folder-type element, using the --folder argument. It is not possible to create page elements at the root of a corpus using this subcommand.

The copied pages can be specified with three (required, mutually exclusive) arguments:

  • --pages: one or more page IDs as input.
arkindex elements page-copy --folder $PARENT_ELEMENT_ID --pages $PAGE_ELEMENT_ID
  • --selection: the pages to be copied are retrieved from your current selection on Arkindex.
arkindex elements page-copy --folder $PARENT_ELEMENT_ID --selection
  • --uuid-list: path to a text file containing a list of page IDs, one ID per line.
arkindex elements page-copy --folder $PARENT_ELEMENT_ID --uuid-list $PATH/TO/file.txt

Rejecting classifications

The reject-classifications subcommand can be used to reject (if the classification was created by a worker) or delete (if the classification was created manually) one or more classification(s) from one or more element(s).

arkindex elements reject-classifications --element $ELEMENT_ID_1 $ELEMENT_ID_2 --classes $ML_CLASS_NAME

Target elements

The elements to reject/remove classifications from can be retrieved using three (required, mutually exclusive) arguments:

  • --element: one or more element IDs.
arkindex elements reject-classifications --element $ELEMENT_ID --classes $ML_CLASS_NAME
  • --selection: the target elements are retrieved from your selection on Arkindex.
arkindex elements reject-classifications --selection --classes $ML_CLASS_NAME
  • --uuid-list: the target elements are retrieved from a text file containing a list of element IDs, with one ID per line.
arkindex elements reject-classifications --uuid-list $PATH/TO/file.txt --classes $ML_CLASS_NAME

Target classifications

The classes to reject/remove can be specified using two (required, mutually exclusive) arguments:

  • --all: all the classifications on the target elements will be rejected/deleted.
arkindex elements reject-classifications --element $ELEMENT_ID --all
  • --classes: specify which classes will be rejected/removed, using their names.
arkindex elements reject-classifications --element $ELEMENT_ID --classes $ML_CLASS_1 $ML_CLASS_2