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, thelist
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 aselements.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
andtype
); - the id and url of the element's image (columns
image_id
andimage_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 thelink
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 thepage
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