Label module
Queries
Set of Label queries.
Source code in kili/queries/label/__init__.py
class QueriesLabel:
"""Set of Label queries."""
# pylint: disable=too-many-arguments,too-many-locals
def __init__(self, auth):
"""Initialize the subclass.
Args:
auth: KiliAuth object
"""
self.auth = auth
# pylint: disable=dangerous-default-value
@typechecked
def labels(
self,
project_id: str,
asset_id: Optional[str] = None,
asset_status_in: Optional[List[str]] = None,
asset_external_id_in: Optional[List[str]] = None,
author_in: Optional[List[str]] = None,
created_at: Optional[str] = None,
created_at_gte: Optional[str] = None,
created_at_lte: Optional[str] = None,
fields: List[str] = [
"author.email",
"author.id",
"id",
"jsonResponse",
"labelType",
"secondsToLabel",
],
first: Optional[int] = None,
honeypot_mark_gte: Optional[float] = None,
honeypot_mark_lte: Optional[float] = None,
id_contains: Optional[List[str]] = None,
label_id: Optional[str] = None,
skip: int = 0,
type_in: Optional[List[str]] = None,
user_id: Optional[str] = None,
disable_tqdm: bool = False,
as_generator: bool = False,
category_search: Optional[str] = None,
) -> Union[List[dict], Generator[dict, None, None]]:
# pylint: disable=line-too-long
"""Get a label list or a label generator from a project based on a set of criteria.
Args:
project_id: Identifier of the project.
asset_id: Identifier of the asset.
asset_status_in: Returned labels should have a status that belongs to that list, if given.
Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
author_in: Returned labels should have a label whose status belongs to that list, if given.
created_at: Returned labels should have a label whose creation date is equal to this date.
created_at_gte: Returned labels should have a label whose creation date is greater than this date.
created_at_lte: Returned labels should have a label whose creation date is lower than this date.
fields: All the fields to request among the possible fields for the labels.
See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
first: Maximum number of labels to return.
honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
label_id: Identifier of the label.
skip: Number of labels to skip (they are ordered by their date of creation, first to last).
type_in: Returned labels should have a label whose type belongs to that list, if given.
user_id: Identifier of the user.
disable_tqdm: If `True`, the progress bar will be disabled
as_generator: If `True`, a generator on the labels is returned.
!!! info "Dates format"
Date strings should have format: "YYYY-MM-DD"
Returns:
A result object which contains the query if it was successful, else an error message.
Examples:
>>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
>>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project
!!! example "How to filter based on label categories"
The search query is composed of logical expressions following this format:
[job_name].[category_name].count [comparaison_operator] [value]
where:
- `[job_name]` is the name of the job in the interface
- `[category_name]` is the name of the category in the interface for this job
- `[comparaison_operator]` can be one of: [`==`, `>=`, `<=`, `<`, `>`]
- `[value]` is an integer that represents the count of such objects of the given category in the label
These operations can be separated by OR and AND operators
Example:
category_search = `JOB_CLASSIF.CATEGORY_A.count > 0`
category_search = `JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0`
category_search = `(JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0) AND JOB_BBOX.CATEGORY_C.count > 10`
"""
saved_args = locals()
count_args = {
k: v
for (k, v) in saved_args.items()
if k
not in [
"as_generator",
"disable_tqdm",
"fields",
"first",
"id_contains",
"self",
"skip",
"message",
]
}
# using tqdm with a generator is messy, so it is always disabled
disable_tqdm = disable_tqdm or as_generator
if category_search:
validate_category_search_query(category_search)
payload_query = {
"where": {
"id": label_id,
"asset": {
"id": asset_id,
"externalIdStrictlyIn": asset_external_id_in,
"statusIn": asset_status_in,
},
"project": {
"id": project_id,
},
"user": {
"id": user_id,
},
"createdAt": created_at,
"createdAtGte": created_at_gte,
"createdAtLte": created_at_lte,
"authorIn": author_in,
"honeypotMarkGte": honeypot_mark_gte,
"honeypotMarkLte": honeypot_mark_lte,
"idIn": id_contains,
"search": category_search,
"typeIn": type_in,
},
}
labels_generator = row_generator_from_paginated_calls(
skip,
first,
self.count_labels,
count_args,
self._query_labels,
payload_query,
fields,
disable_tqdm,
)
if as_generator:
return labels_generator
return list(labels_generator)
def _query_labels(
self, skip: int, first: int, payload: dict, fields: List[str]
) -> Iterable[Dict]:
payload.update({"skip": skip, "first": first})
_gql_labels = gql_labels(fragment_builder(fields, LabelType))
result = self.auth.client.execute(_gql_labels, payload)
return format_result("data", result, _object=List[LabelType]) # type:ignore
# pylint: disable=dangerous-default-value
@typechecked
def export_labels_as_df(
self,
project_id: str,
fields: List[str] = [
"author.email",
"author.id",
"createdAt",
"id",
"labelType",
],
asset_fields: List[str] = ["externalId"],
) -> pd.DataFrame:
# pylint: disable=line-too-long
"""Get the labels of a project as a pandas DataFrame.
Args:
project_id: Identifier of the project
fields: All the fields to request among the possible fields for the labels.
See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
asset_fields: All the fields to request among the possible fields for the assets.
See [the documentation](https://docs.kili-technology.com/reference/graphql-api#asset) for all possible fields.
Returns:
pandas DataFrame containing the labels.
"""
projects = QueriesProject(self.auth).projects(project_id)
assert len(list(projects)) == 1, NO_ACCESS_RIGHT
assets = QueriesAsset(self.auth).assets(
project_id=project_id,
fields=asset_fields + ["labels." + field for field in fields],
)
labels = [
dict(
label,
**dict((f"asset_{key}", asset[key]) for key in asset if key != "labels"),
)
for asset in assets
for label in asset["labels"]
]
labels_df = pd.DataFrame(labels)
return labels_df
@typechecked
def count_labels(
self,
project_id: str,
asset_id: Optional[str] = None,
asset_status_in: Optional[List[str]] = None,
asset_external_id_in: Optional[List[str]] = None,
author_in: Optional[List[str]] = None,
created_at: Optional[str] = None,
created_at_gte: Optional[str] = None,
created_at_lte: Optional[str] = None,
honeypot_mark_gte: Optional[float] = None,
honeypot_mark_lte: Optional[float] = None,
label_id: Optional[str] = None,
type_in: Optional[List[str]] = None,
user_id: Optional[str] = None,
category_search: Optional[str] = None,
) -> int:
# pylint: disable=line-too-long
"""Get the number of labels for the given parameters.
Args:
asset_id: Identifier of the asset.
asset_status_in: Returned labels should have a status that belongs to that list, if given.
Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
author_in: Returned labels should have a label whose status belongs to that list, if given.
created_at: Returned labels should have a label whose creation date is equal to this date.
created_at_gte: Returned labels should have a label whose creation date is greater than this date.
created_at_lte: Returned labels should have a label whose creation date is lower than this date.
honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
label_id: Identifier of the label.
project_id: Identifier of the project.
type_in: Returned labels should have a label whose type belongs to that list, if given.
user_id: Identifier of the user.
!!! info "Dates format"
Date strings should have format: "YYYY-MM-DD"
Returns:
The number of labels with the parameters provided
"""
if category_search:
validate_category_search_query(category_search)
variables = {
"where": {
"id": label_id,
"asset": {
"id": asset_id,
"externalIdStrictlyIn": asset_external_id_in,
"statusIn": asset_status_in,
},
"project": {
"id": project_id,
},
"user": {
"id": user_id,
},
"createdAt": created_at,
"createdAtGte": created_at_gte,
"createdAtLte": created_at_lte,
"authorIn": author_in,
"honeypotMarkGte": honeypot_mark_gte,
"honeypotMarkLte": honeypot_mark_lte,
"search": category_search,
"typeIn": type_in,
}
}
result = self.auth.client.execute(GQL_LABELS_COUNT, variables)
return format_result("data", result, int)
def export_labels(
self,
project_id: str,
filename: str,
fmt: LabelFormat,
asset_ids: Optional[List[str]] = None,
layout: SplitOption = "split",
single_file: bool = False,
disable_tqdm: bool = False,
):
"""
Export the project labels with the requested format into the requested output path.
Args:
filename: Relative or full path of the archive that will contain
the exported data.
fmt: Format of the exported labels.
asset_ids: Optional list of the assets from which to export the labels.
layout: Layout of the exported files: "split" means there is one folder
per job, "merged" that there is one folder with every labels.
disable_tqdm: Disable the progress bar if True.
!!! Info
The supported formats are:
- Yolo V4, V5, V7 for object detection tasks (bounding box)
- Kili for all tasks.
- COCO for semantic segmentation tasks (bounding box and semantic segmentation)
- Pascal VOC (coming soon) for object detection tasks.
!!! Example
```
from kili.client import Kili
kili = Kili()
kili.export_labels("your_project_id", "export.zip", "yolo_v4")
```
"""
try:
services.export_labels(
self,
asset_ids=asset_ids,
project_id=cast(ProjectId, project_id),
export_type="latest",
label_format=fmt,
split_option=layout,
single_file=single_file,
output_file=filename,
disable_tqdm=disable_tqdm,
log_level="WARNING",
)
except NoCompatibleJobError as excp:
print(str(excp))
count_labels(self, project_id, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, honeypot_mark_gte=None, honeypot_mark_lte=None, label_id=None, type_in=None, user_id=None, category_search=None)
Get the number of labels for the given parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset_id |
Optional[str] |
Identifier of the asset. |
None |
asset_status_in |
Optional[List[str]] |
Returned labels should have a status that belongs to that list, if given.
Possible choices : |
None |
asset_external_id_in |
Optional[List[str]] |
Returned labels should have an external id that belongs to that list, if given. |
None |
author_in |
Optional[List[str]] |
Returned labels should have a label whose status belongs to that list, if given. |
None |
created_at |
Optional[str] |
Returned labels should have a label whose creation date is equal to this date. |
None |
created_at_gte |
Optional[str] |
Returned labels should have a label whose creation date is greater than this date. |
None |
created_at_lte |
Optional[str] |
Returned labels should have a label whose creation date is lower than this date. |
None |
honeypot_mark_gte |
Optional[float] |
Returned labels should have a label whose honeypot is greater than this number. |
None |
honeypot_mark_lte |
Optional[float] |
Returned labels should have a label whose honeypot is lower than this number. |
None |
label_id |
Optional[str] |
Identifier of the label. |
None |
project_id |
str |
Identifier of the project. |
required |
type_in |
Optional[List[str]] |
Returned labels should have a label whose type belongs to that list, if given. |
None |
user_id |
Optional[str] |
Identifier of the user. |
None |
Dates format
Date strings should have format: "YYYY-MM-DD"
Returns:
| Type | Description |
|---|---|
int |
The number of labels with the parameters provided |
Source code in kili/queries/label/__init__.py
@typechecked
def count_labels(
self,
project_id: str,
asset_id: Optional[str] = None,
asset_status_in: Optional[List[str]] = None,
asset_external_id_in: Optional[List[str]] = None,
author_in: Optional[List[str]] = None,
created_at: Optional[str] = None,
created_at_gte: Optional[str] = None,
created_at_lte: Optional[str] = None,
honeypot_mark_gte: Optional[float] = None,
honeypot_mark_lte: Optional[float] = None,
label_id: Optional[str] = None,
type_in: Optional[List[str]] = None,
user_id: Optional[str] = None,
category_search: Optional[str] = None,
) -> int:
# pylint: disable=line-too-long
"""Get the number of labels for the given parameters.
Args:
asset_id: Identifier of the asset.
asset_status_in: Returned labels should have a status that belongs to that list, if given.
Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
author_in: Returned labels should have a label whose status belongs to that list, if given.
created_at: Returned labels should have a label whose creation date is equal to this date.
created_at_gte: Returned labels should have a label whose creation date is greater than this date.
created_at_lte: Returned labels should have a label whose creation date is lower than this date.
honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
label_id: Identifier of the label.
project_id: Identifier of the project.
type_in: Returned labels should have a label whose type belongs to that list, if given.
user_id: Identifier of the user.
!!! info "Dates format"
Date strings should have format: "YYYY-MM-DD"
Returns:
The number of labels with the parameters provided
"""
if category_search:
validate_category_search_query(category_search)
variables = {
"where": {
"id": label_id,
"asset": {
"id": asset_id,
"externalIdStrictlyIn": asset_external_id_in,
"statusIn": asset_status_in,
},
"project": {
"id": project_id,
},
"user": {
"id": user_id,
},
"createdAt": created_at,
"createdAtGte": created_at_gte,
"createdAtLte": created_at_lte,
"authorIn": author_in,
"honeypotMarkGte": honeypot_mark_gte,
"honeypotMarkLte": honeypot_mark_lte,
"search": category_search,
"typeIn": type_in,
}
}
result = self.auth.client.execute(GQL_LABELS_COUNT, variables)
return format_result("data", result, int)
export_labels(self, project_id, filename, fmt, asset_ids=None, layout='split', single_file=False, disable_tqdm=False)
Export the project labels with the requested format into the requested output path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filename |
str |
Relative or full path of the archive that will contain the exported data. |
required |
fmt |
typing_extensions.Literal['raw', 'kili', 'yolo_v4', 'yolo_v5', 'yolo_v7', 'coco'] |
Format of the exported labels. |
required |
asset_ids |
Optional[List[str]] |
Optional list of the assets from which to export the labels. |
None |
layout |
typing_extensions.Literal['split', 'merged'] |
Layout of the exported files: "split" means there is one folder per job, "merged" that there is one folder with every labels. |
'split' |
disable_tqdm |
bool |
Disable the progress bar if True. |
False |
Info
The supported formats are:
-
Yolo V4, V5, V7 for object detection tasks (bounding box)
-
Kili for all tasks.
-
COCO for semantic segmentation tasks (bounding box and semantic segmentation)
-
Pascal VOC (coming soon) for object detection tasks.
Example
from kili.client import Kili
kili = Kili()
kili.export_labels("your_project_id", "export.zip", "yolo_v4")
Source code in kili/queries/label/__init__.py
def export_labels(
self,
project_id: str,
filename: str,
fmt: LabelFormat,
asset_ids: Optional[List[str]] = None,
layout: SplitOption = "split",
single_file: bool = False,
disable_tqdm: bool = False,
):
"""
Export the project labels with the requested format into the requested output path.
Args:
filename: Relative or full path of the archive that will contain
the exported data.
fmt: Format of the exported labels.
asset_ids: Optional list of the assets from which to export the labels.
layout: Layout of the exported files: "split" means there is one folder
per job, "merged" that there is one folder with every labels.
disable_tqdm: Disable the progress bar if True.
!!! Info
The supported formats are:
- Yolo V4, V5, V7 for object detection tasks (bounding box)
- Kili for all tasks.
- COCO for semantic segmentation tasks (bounding box and semantic segmentation)
- Pascal VOC (coming soon) for object detection tasks.
!!! Example
```
from kili.client import Kili
kili = Kili()
kili.export_labels("your_project_id", "export.zip", "yolo_v4")
```
"""
try:
services.export_labels(
self,
asset_ids=asset_ids,
project_id=cast(ProjectId, project_id),
export_type="latest",
label_format=fmt,
split_option=layout,
single_file=single_file,
output_file=filename,
disable_tqdm=disable_tqdm,
log_level="WARNING",
)
except NoCompatibleJobError as excp:
print(str(excp))
export_labels_as_df(self, project_id, fields=['author.email', 'author.id', 'createdAt', 'id', 'labelType'], asset_fields=['externalId'])
Get the labels of a project as a pandas DataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id |
str |
Identifier of the project |
required |
fields |
List[str] |
All the fields to request among the possible fields for the labels. See the documentation for all possible fields. |
['author.email', 'author.id', 'createdAt', 'id', 'labelType'] |
asset_fields |
List[str] |
All the fields to request among the possible fields for the assets. See the documentation for all possible fields. |
['externalId'] |
Returns:
| Type | Description |
|---|---|
DataFrame |
pandas DataFrame containing the labels. |
Source code in kili/queries/label/__init__.py
@typechecked
def export_labels_as_df(
self,
project_id: str,
fields: List[str] = [
"author.email",
"author.id",
"createdAt",
"id",
"labelType",
],
asset_fields: List[str] = ["externalId"],
) -> pd.DataFrame:
# pylint: disable=line-too-long
"""Get the labels of a project as a pandas DataFrame.
Args:
project_id: Identifier of the project
fields: All the fields to request among the possible fields for the labels.
See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
asset_fields: All the fields to request among the possible fields for the assets.
See [the documentation](https://docs.kili-technology.com/reference/graphql-api#asset) for all possible fields.
Returns:
pandas DataFrame containing the labels.
"""
projects = QueriesProject(self.auth).projects(project_id)
assert len(list(projects)) == 1, NO_ACCESS_RIGHT
assets = QueriesAsset(self.auth).assets(
project_id=project_id,
fields=asset_fields + ["labels." + field for field in fields],
)
labels = [
dict(
label,
**dict((f"asset_{key}", asset[key]) for key in asset if key != "labels"),
)
for asset in assets
for label in asset["labels"]
]
labels_df = pd.DataFrame(labels)
return labels_df
labels(self, project_id, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, fields=['author.email', 'author.id', 'id', 'jsonResponse', 'labelType', 'secondsToLabel'], first=None, honeypot_mark_gte=None, honeypot_mark_lte=None, id_contains=None, label_id=None, skip=0, type_in=None, user_id=None, disable_tqdm=False, as_generator=False, category_search=None)
Get a label list or a label generator from a project based on a set of criteria.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id |
str |
Identifier of the project. |
required |
asset_id |
Optional[str] |
Identifier of the asset. |
None |
asset_status_in |
Optional[List[str]] |
Returned labels should have a status that belongs to that list, if given.
Possible choices : |
None |
asset_external_id_in |
Optional[List[str]] |
Returned labels should have an external id that belongs to that list, if given. |
None |
author_in |
Optional[List[str]] |
Returned labels should have a label whose status belongs to that list, if given. |
None |
created_at |
Optional[str] |
Returned labels should have a label whose creation date is equal to this date. |
None |
created_at_gte |
Optional[str] |
Returned labels should have a label whose creation date is greater than this date. |
None |
created_at_lte |
Optional[str] |
Returned labels should have a label whose creation date is lower than this date. |
None |
fields |
List[str] |
All the fields to request among the possible fields for the labels. See the documentation for all possible fields. |
['author.email', 'author.id', 'id', 'jsonResponse', 'labelType', 'secondsToLabel'] |
first |
Optional[int] |
Maximum number of labels to return. |
None |
honeypot_mark_gte |
Optional[float] |
Returned labels should have a label whose honeypot is greater than this number. |
None |
honeypot_mark_lte |
Optional[float] |
Returned labels should have a label whose honeypot is lower than this number. |
None |
id_contains |
Optional[List[str]] |
Filters out labels not belonging to that list. If empty, no filtering is applied. |
None |
label_id |
Optional[str] |
Identifier of the label. |
None |
skip |
int |
Number of labels to skip (they are ordered by their date of creation, first to last). |
0 |
type_in |
Optional[List[str]] |
Returned labels should have a label whose type belongs to that list, if given. |
None |
user_id |
Optional[str] |
Identifier of the user. |
None |
disable_tqdm |
bool |
If |
False |
as_generator |
bool |
If |
False |
Dates format
Date strings should have format: "YYYY-MM-DD"
Returns:
| Type | Description |
|---|---|
Union[List[dict], Generator[dict, NoneType]] |
A result object which contains the query if it was successful, else an error message. |
Examples:
>>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
>>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project
How to filter based on label categories
The search query is composed of logical expressions following this format:
[job_name].[category_name].count [comparaison_operator] [value]
where:
[job_name]is the name of the job in the interface[category_name]is the name of the category in the interface for this job[comparaison_operator]can be one of: [==,>=,<=,<,>][value]is an integer that represents the count of such objects of the given category in the label
These operations can be separated by OR and AND operators
Example:
category_search = `JOB_CLASSIF.CATEGORY_A.count > 0`
category_search = `JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0`
category_search = `(JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0) AND JOB_BBOX.CATEGORY_C.count > 10`
Source code in kili/queries/label/__init__.py
@typechecked
def labels(
self,
project_id: str,
asset_id: Optional[str] = None,
asset_status_in: Optional[List[str]] = None,
asset_external_id_in: Optional[List[str]] = None,
author_in: Optional[List[str]] = None,
created_at: Optional[str] = None,
created_at_gte: Optional[str] = None,
created_at_lte: Optional[str] = None,
fields: List[str] = [
"author.email",
"author.id",
"id",
"jsonResponse",
"labelType",
"secondsToLabel",
],
first: Optional[int] = None,
honeypot_mark_gte: Optional[float] = None,
honeypot_mark_lte: Optional[float] = None,
id_contains: Optional[List[str]] = None,
label_id: Optional[str] = None,
skip: int = 0,
type_in: Optional[List[str]] = None,
user_id: Optional[str] = None,
disable_tqdm: bool = False,
as_generator: bool = False,
category_search: Optional[str] = None,
) -> Union[List[dict], Generator[dict, None, None]]:
# pylint: disable=line-too-long
"""Get a label list or a label generator from a project based on a set of criteria.
Args:
project_id: Identifier of the project.
asset_id: Identifier of the asset.
asset_status_in: Returned labels should have a status that belongs to that list, if given.
Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
author_in: Returned labels should have a label whose status belongs to that list, if given.
created_at: Returned labels should have a label whose creation date is equal to this date.
created_at_gte: Returned labels should have a label whose creation date is greater than this date.
created_at_lte: Returned labels should have a label whose creation date is lower than this date.
fields: All the fields to request among the possible fields for the labels.
See [the documentation](https://docs.kili-technology.com/reference/graphql-api#label) for all possible fields.
first: Maximum number of labels to return.
honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
label_id: Identifier of the label.
skip: Number of labels to skip (they are ordered by their date of creation, first to last).
type_in: Returned labels should have a label whose type belongs to that list, if given.
user_id: Identifier of the user.
disable_tqdm: If `True`, the progress bar will be disabled
as_generator: If `True`, a generator on the labels is returned.
!!! info "Dates format"
Date strings should have format: "YYYY-MM-DD"
Returns:
A result object which contains the query if it was successful, else an error message.
Examples:
>>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
>>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project
!!! example "How to filter based on label categories"
The search query is composed of logical expressions following this format:
[job_name].[category_name].count [comparaison_operator] [value]
where:
- `[job_name]` is the name of the job in the interface
- `[category_name]` is the name of the category in the interface for this job
- `[comparaison_operator]` can be one of: [`==`, `>=`, `<=`, `<`, `>`]
- `[value]` is an integer that represents the count of such objects of the given category in the label
These operations can be separated by OR and AND operators
Example:
category_search = `JOB_CLASSIF.CATEGORY_A.count > 0`
category_search = `JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0`
category_search = `(JOB_CLASSIF.CATEGORY_A.count > 0 OR JOB_NER.CATEGORY_B.count > 0) AND JOB_BBOX.CATEGORY_C.count > 10`
"""
saved_args = locals()
count_args = {
k: v
for (k, v) in saved_args.items()
if k
not in [
"as_generator",
"disable_tqdm",
"fields",
"first",
"id_contains",
"self",
"skip",
"message",
]
}
# using tqdm with a generator is messy, so it is always disabled
disable_tqdm = disable_tqdm or as_generator
if category_search:
validate_category_search_query(category_search)
payload_query = {
"where": {
"id": label_id,
"asset": {
"id": asset_id,
"externalIdStrictlyIn": asset_external_id_in,
"statusIn": asset_status_in,
},
"project": {
"id": project_id,
},
"user": {
"id": user_id,
},
"createdAt": created_at,
"createdAtGte": created_at_gte,
"createdAtLte": created_at_lte,
"authorIn": author_in,
"honeypotMarkGte": honeypot_mark_gte,
"honeypotMarkLte": honeypot_mark_lte,
"idIn": id_contains,
"search": category_search,
"typeIn": type_in,
},
}
labels_generator = row_generator_from_paginated_calls(
skip,
first,
self.count_labels,
count_args,
self._query_labels,
payload_query,
fields,
disable_tqdm,
)
if as_generator:
return labels_generator
return list(labels_generator)
Mutations
Set of Label mutations.
Source code in kili/mutations/label/__init__.py
class MutationsLabel:
"""Set of Label mutations."""
# pylint: disable=too-many-arguments,too-many-locals
def __init__(self, auth):
"""Initializes the subclass.
Args:
auth: KiliAuth object
"""
self.auth = auth
@typechecked
def create_predictions(
self,
project_id: str,
external_id_array: List[str],
model_name_array: List[str],
json_response_array: List[dict],
):
# pylint: disable=line-too-long
"""Create predictions for specific assets.
Args:
project_id: Identifier of the project
external_id_array: The external identifiers of the assets for which we want to add predictions
model_name_array: In case you want to precise from which model the label originated
json_response_array: The predictions are given here. For examples,
see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).
Returns:
A result object which indicates if the mutation was successful, or an error message.
!!! example "Recipe"
For more detailed examples on how to create predictions, see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).
"""
assert len(external_id_array) == len(
json_response_array
), "IDs list and predictions list should have the same length"
assert len(external_id_array) == len(
model_name_array
), "IDs list and model names list should have the same length"
if len(external_id_array) == 0:
warnings.warn("Empty IDs and prediction list")
properties_to_batch = {
"external_id_array": external_id_array,
"model_name_array": model_name_array,
"json_response_array": json_response_array,
}
def generate_variables(batch):
return {
"data": {
"modelNameArray": batch["model_name_array"],
"jsonResponseArray": [dumps(elem) for elem in batch["json_response_array"]],
},
"where": {
"externalIdStrictlyIn": batch["external_id_array"],
"project": {"id": project_id},
},
}
results = _mutate_from_paginated_call(
self,
properties_to_batch,
generate_variables,
GQL_CREATE_PREDICTIONS,
)
return format_result("data", results[0], Label)
@deprecate(
msg=(
"append_to_labels method is deprecated. Please use append_labels instead. This new"
" function allows to import several labels 10 times faster."
)
)
@typechecked
def append_to_labels(
self,
json_response: dict,
author_id: Optional[str] = None,
label_asset_external_id: Optional[str] = None,
label_asset_id: Optional[str] = None,
label_type: str = "DEFAULT",
project_id: Optional[str] = None,
seconds_to_label: Optional[int] = 0,
):
"""
!!! danger "[DEPRECATED]"
append_to_labels method is deprecated. Please use append_labels instead.
This new function allows to import several labels 10 times faster.
Append a label to an asset.
Args:
json_response: Label is given here
author_id: ID of the author of the label
label_asset_external_id: External identifier of the asset
label_asset_id: Identifier of the asset
project_id: Identifier of the project
label_type: Can be one of `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`
seconds_to_label: Time to create the label
!!! warning
Either provide `label_asset_id` or `label_asset_external_id` and `project_id`
Returns:
A result object which indicates if the mutation was successful,
or an error message.
Examples:
>>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})
"""
if author_id is None:
author_id = self.auth.user_id
label_asset_id = infer_id_from_external_id(
self, label_asset_id, label_asset_external_id, project_id
)
variables = {
"data": {
"authorID": author_id,
"jsonResponse": dumps(json_response),
"labelType": label_type,
"secondsToLabel": seconds_to_label,
},
"where": {"id": label_asset_id},
}
result = self.auth.client.execute(GQL_APPEND_TO_LABELS, variables)
return format_result("data", result, Label)
@typechecked
def append_labels(
self,
asset_id_array: List[str],
json_response_array: List[Dict],
author_id_array: Optional[List[str]] = None,
seconds_to_label_array: Optional[List[int]] = None,
model_name: Optional[str] = None,
label_type: LabelType = "DEFAULT",
):
"""Append labels to assets.
Args:
asset_id_array: list of asset ids to append labels on
json_response_array: list of labels to append
author_id_array: list of the author id of the labels
seconds_to_label_array: list of times taken to produce the label, in seconds
model_name: Only useful when uploading predictions.
Name of the model when uploading predictions
label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`
Returns:
A result object which indicates if the mutation was successful,
or an error message.
Examples:
>>> kili.append_to_labels(
asset_id_array=['cl9wmlkuc00050qsz6ut39g8h', 'cl9wmlkuw00080qsz2kqh8aiy'],
json_response_array=[{...}, {...}]
)
"""
if label_type == "PREDICTION" and model_name is None:
raise ValueError("You must provide model_name when uploading predictions")
if len(asset_id_array) != len(json_response_array):
raise ValueError("asset_id_array and json_response_array should have the same length")
for array in [seconds_to_label_array, author_id_array]:
if array is not None and len(array) != len(asset_id_array):
raise ValueError("All arrays should have the same length")
labels = [
{
"asset_id": asset_id,
"json_response": json_response,
"seconds_to_label": seconds_to_label,
"model_name": model_name,
"author_id": author_id,
}
for (asset_id, json_response, seconds_to_label, author_id, model_name) in list(
zip(
asset_id_array,
json_response_array,
seconds_to_label_array or [None] * len(asset_id_array),
author_id_array or [None] * len(asset_id_array),
repeat(model_name),
)
)
]
return import_labels_from_dict(self, labels, label_type)
@typechecked
def update_properties_in_label(
self,
label_id: str,
seconds_to_label: Optional[int] = None,
model_name: Optional[str] = None,
json_response: Optional[dict] = None,
):
"""Update properties of a label.
Args:
label_id: Identifier of the label
seconds_to_label: Time to create the label
model_name: Name of the model
json_response: The label is given here
Returns:
A result object which indicates if the mutation was successful,
or an error message.
Examples:
>>> kili.update_properties_in_label(label_id=label_id, json_response={...})
"""
formatted_json_response = None if json_response is None else dumps(json_response)
variables = {
"labelID": label_id,
"secondsToLabel": seconds_to_label,
"modelName": model_name,
"jsonResponse": formatted_json_response,
}
result = self.auth.client.execute(GQL_UPDATE_PROPERTIES_IN_LABEL, variables)
return format_result("data", result, Label)
@typechecked
def create_honeypot(
self,
json_response: dict,
asset_external_id: Optional[str] = None,
asset_id: Optional[str] = None,
project_id: Optional[str] = None,
):
"""Create honeypot for an asset.
!!! info
Uses the given `json_response` to create a `REVIEW` label.
This enables Kili to compute a`honeypotMark`,
which measures the similarity between this label and other labels.
Args:
json_response: The JSON response of the honeypot label of the asset
asset_id: Identifier of the asset
Either provide asset_id or asset_external_id and project_id
asset_external_id: External identifier of the asset
Either provide asset_id or asset_external_id and project_id
project_id: Identifier of the project
Either provide asset_id or asset_external_id and project_id
Returns:
A result object which indicates if the mutation was successful,
or an error message.
"""
asset_id = infer_id_from_external_id(self, asset_id, asset_external_id, project_id)
variables = {
"data": {"jsonResponse": dumps(json_response)},
"where": {"id": asset_id},
}
result = self.auth.client.execute(GQL_CREATE_HONEYPOT, variables)
return format_result("data", result, Label)
append_labels(self, asset_id_array, json_response_array, author_id_array=None, seconds_to_label_array=None, model_name=None, label_type='DEFAULT')
Append labels to assets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
asset_id_array |
List[str] |
list of asset ids to append labels on |
required |
json_response_array |
List[Dict] |
list of labels to append |
required |
author_id_array |
Optional[List[str]] |
list of the author id of the labels |
None |
seconds_to_label_array |
Optional[List[int]] |
list of times taken to produce the label, in seconds |
None |
model_name |
Optional[str] |
Only useful when uploading predictions. Name of the model when uploading predictions |
None |
label_type |
typing_extensions.Literal['AUTOSAVE', 'DEFAULT', 'INFERENCE', 'PREDICTION', 'REVIEW'] |
Can be one of |
'DEFAULT' |
Returns:
| Type | Description |
|---|---|
A result object which indicates if the mutation was successful, or an error message. |
Examples:
>>> kili.append_to_labels(
asset_id_array=['cl9wmlkuc00050qsz6ut39g8h', 'cl9wmlkuw00080qsz2kqh8aiy'],
json_response_array=[{...}, {...}]
)
Source code in kili/mutations/label/__init__.py
@typechecked
def append_labels(
self,
asset_id_array: List[str],
json_response_array: List[Dict],
author_id_array: Optional[List[str]] = None,
seconds_to_label_array: Optional[List[int]] = None,
model_name: Optional[str] = None,
label_type: LabelType = "DEFAULT",
):
"""Append labels to assets.
Args:
asset_id_array: list of asset ids to append labels on
json_response_array: list of labels to append
author_id_array: list of the author id of the labels
seconds_to_label_array: list of times taken to produce the label, in seconds
model_name: Only useful when uploading predictions.
Name of the model when uploading predictions
label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`
Returns:
A result object which indicates if the mutation was successful,
or an error message.
Examples:
>>> kili.append_to_labels(
asset_id_array=['cl9wmlkuc00050qsz6ut39g8h', 'cl9wmlkuw00080qsz2kqh8aiy'],
json_response_array=[{...}, {...}]
)
"""
if label_type == "PREDICTION" and model_name is None:
raise ValueError("You must provide model_name when uploading predictions")
if len(asset_id_array) != len(json_response_array):
raise ValueError("asset_id_array and json_response_array should have the same length")
for array in [seconds_to_label_array, author_id_array]:
if array is not None and len(array) != len(asset_id_array):
raise ValueError("All arrays should have the same length")
labels = [
{
"asset_id": asset_id,
"json_response": json_response,
"seconds_to_label": seconds_to_label,
"model_name": model_name,
"author_id": author_id,
}
for (asset_id, json_response, seconds_to_label, author_id, model_name) in list(
zip(
asset_id_array,
json_response_array,
seconds_to_label_array or [None] * len(asset_id_array),
author_id_array or [None] * len(asset_id_array),
repeat(model_name),
)
)
]
return import_labels_from_dict(self, labels, label_type)
append_to_labels(self, json_response, author_id=None, label_asset_external_id=None, label_asset_id=None, label_type='DEFAULT', project_id=None, seconds_to_label=0)
[DEPRECATED]
append_to_labels method is deprecated. Please use append_labels instead. This new function allows to import several labels 10 times faster.
Append a label to an asset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
json_response |
dict |
Label is given here |
required |
author_id |
Optional[str] |
ID of the author of the label |
None |
label_asset_external_id |
Optional[str] |
External identifier of the asset |
None |
label_asset_id |
Optional[str] |
Identifier of the asset |
None |
project_id |
Optional[str] |
Identifier of the project |
None |
label_type |
str |
Can be one of |
'DEFAULT' |
seconds_to_label |
Optional[int] |
Time to create the label |
0 |
Warning
Either provide label_asset_id or label_asset_external_id and project_id
Returns:
| Type | Description |
|---|---|
A result object which indicates if the mutation was successful, or an error message. |
Examples:
>>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})
Source code in kili/mutations/label/__init__.py
@deprecate(
msg=(
"append_to_labels method is deprecated. Please use append_labels instead. This new"
" function allows to import several labels 10 times faster."
)
)
@typechecked
def append_to_labels(
self,
json_response: dict,
author_id: Optional[str] = None,
label_asset_external_id: Optional[str] = None,
label_asset_id: Optional[str] = None,
label_type: str = "DEFAULT",
project_id: Optional[str] = None,
seconds_to_label: Optional[int] = 0,
):
"""
!!! danger "[DEPRECATED]"
append_to_labels method is deprecated. Please use append_labels instead.
This new function allows to import several labels 10 times faster.
Append a label to an asset.
Args:
json_response: Label is given here
author_id: ID of the author of the label
label_asset_external_id: External identifier of the asset
label_asset_id: Identifier of the asset
project_id: Identifier of the project
label_type: Can be one of `DEFAULT`, `PREDICTION`, `REVIEW` or `INFERENCE`
seconds_to_label: Time to create the label
!!! warning
Either provide `label_asset_id` or `label_asset_external_id` and `project_id`
Returns:
A result object which indicates if the mutation was successful,
or an error message.
Examples:
>>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})
"""
if author_id is None:
author_id = self.auth.user_id
label_asset_id = infer_id_from_external_id(
self, label_asset_id, label_asset_external_id, project_id
)
variables = {
"data": {
"authorID": author_id,
"jsonResponse": dumps(json_response),
"labelType": label_type,
"secondsToLabel": seconds_to_label,
},
"where": {"id": label_asset_id},
}
result = self.auth.client.execute(GQL_APPEND_TO_LABELS, variables)
return format_result("data", result, Label)
create_honeypot(self, json_response, asset_external_id=None, asset_id=None, project_id=None)
Create honeypot for an asset.
Info
Uses the given json_response to create a REVIEW label.
This enables Kili to compute ahoneypotMark,
which measures the similarity between this label and other labels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
json_response |
dict |
The JSON response of the honeypot label of the asset |
required |
asset_id |
Optional[str] |
Identifier of the asset Either provide asset_id or asset_external_id and project_id |
None |
asset_external_id |
Optional[str] |
External identifier of the asset Either provide asset_id or asset_external_id and project_id |
None |
project_id |
Optional[str] |
Identifier of the project Either provide asset_id or asset_external_id and project_id |
None |
Returns:
| Type | Description |
|---|---|
A result object which indicates if the mutation was successful, or an error message. |
Source code in kili/mutations/label/__init__.py
@typechecked
def create_honeypot(
self,
json_response: dict,
asset_external_id: Optional[str] = None,
asset_id: Optional[str] = None,
project_id: Optional[str] = None,
):
"""Create honeypot for an asset.
!!! info
Uses the given `json_response` to create a `REVIEW` label.
This enables Kili to compute a`honeypotMark`,
which measures the similarity between this label and other labels.
Args:
json_response: The JSON response of the honeypot label of the asset
asset_id: Identifier of the asset
Either provide asset_id or asset_external_id and project_id
asset_external_id: External identifier of the asset
Either provide asset_id or asset_external_id and project_id
project_id: Identifier of the project
Either provide asset_id or asset_external_id and project_id
Returns:
A result object which indicates if the mutation was successful,
or an error message.
"""
asset_id = infer_id_from_external_id(self, asset_id, asset_external_id, project_id)
variables = {
"data": {"jsonResponse": dumps(json_response)},
"where": {"id": asset_id},
}
result = self.auth.client.execute(GQL_CREATE_HONEYPOT, variables)
return format_result("data", result, Label)
create_predictions(self, project_id, external_id_array, model_name_array, json_response_array)
Create predictions for specific assets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id |
str |
Identifier of the project |
required |
external_id_array |
List[str] |
The external identifiers of the assets for which we want to add predictions |
required |
model_name_array |
List[str] |
In case you want to precise from which model the label originated |
required |
json_response_array |
List[dict] |
The predictions are given here. For examples, see the recipe. |
required |
Returns:
| Type | Description |
|---|---|
A result object which indicates if the mutation was successful, or an error message. |
Recipe
For more detailed examples on how to create predictions, see the recipe.
Source code in kili/mutations/label/__init__.py
@typechecked
def create_predictions(
self,
project_id: str,
external_id_array: List[str],
model_name_array: List[str],
json_response_array: List[dict],
):
# pylint: disable=line-too-long
"""Create predictions for specific assets.
Args:
project_id: Identifier of the project
external_id_array: The external identifiers of the assets for which we want to add predictions
model_name_array: In case you want to precise from which model the label originated
json_response_array: The predictions are given here. For examples,
see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).
Returns:
A result object which indicates if the mutation was successful, or an error message.
!!! example "Recipe"
For more detailed examples on how to create predictions, see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).
"""
assert len(external_id_array) == len(
json_response_array
), "IDs list and predictions list should have the same length"
assert len(external_id_array) == len(
model_name_array
), "IDs list and model names list should have the same length"
if len(external_id_array) == 0:
warnings.warn("Empty IDs and prediction list")
properties_to_batch = {
"external_id_array": external_id_array,
"model_name_array": model_name_array,
"json_response_array": json_response_array,
}
def generate_variables(batch):
return {
"data": {
"modelNameArray": batch["model_name_array"],
"jsonResponseArray": [dumps(elem) for elem in batch["json_response_array"]],
},
"where": {
"externalIdStrictlyIn": batch["external_id_array"],
"project": {"id": project_id},
},
}
results = _mutate_from_paginated_call(
self,
properties_to_batch,
generate_variables,
GQL_CREATE_PREDICTIONS,
)
return format_result("data", results[0], Label)
update_properties_in_label(self, label_id, seconds_to_label=None, model_name=None, json_response=None)
Update properties of a label.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
label_id |
str |
Identifier of the label |
required |
seconds_to_label |
Optional[int] |
Time to create the label |
None |
model_name |
Optional[str] |
Name of the model |
None |
json_response |
Optional[dict] |
The label is given here |
None |
Returns:
| Type | Description |
|---|---|
A result object which indicates if the mutation was successful, or an error message. |
Examples:
>>> kili.update_properties_in_label(label_id=label_id, json_response={...})
Source code in kili/mutations/label/__init__.py
@typechecked
def update_properties_in_label(
self,
label_id: str,
seconds_to_label: Optional[int] = None,
model_name: Optional[str] = None,
json_response: Optional[dict] = None,
):
"""Update properties of a label.
Args:
label_id: Identifier of the label
seconds_to_label: Time to create the label
model_name: Name of the model
json_response: The label is given here
Returns:
A result object which indicates if the mutation was successful,
or an error message.
Examples:
>>> kili.update_properties_in_label(label_id=label_id, json_response={...})
"""
formatted_json_response = None if json_response is None else dumps(json_response)
variables = {
"labelID": label_id,
"secondsToLabel": seconds_to_label,
"modelName": model_name,
"jsonResponse": formatted_json_response,
}
result = self.auth.client.execute(GQL_UPDATE_PROPERTIES_IN_LABEL, variables)
return format_result("data", result, Label)
Subscriptions
Set of Label subscriptions.
Source code in kili/subscriptions/label/__init__.py
class SubscriptionsLabel:
"""Set of Label subscriptions."""
# pylint: disable=too-many-arguments,too-many-locals
def __init__(self, auth):
"""Initialize the subclass.
Args:
auth: KiliAuth object
"""
self.auth = auth
@typechecked
def label_created_or_updated(self, project_id: str, callback: Callable[[str, str], None]):
# pylint: disable=line-too-long
"""
Subscribe a callback to a project, which is executed when a label is created or updated.
Args:
project_id: Identifier of the project
callback: This function takes as input the id of the asset and its content.
Returns:
A subscription client
!!! example "Recipe"
For more detailed examples on how to use Webhooks,
See [the related recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/webhooks.ipynb)
"""
ws_endpoint = self.auth.client.endpoint.replace("http", "ws")
websocket = SubscriptionGraphQLClient(ws_endpoint)
headers = {"Accept": "application/json", "Content-Type": "application/json"}
authorization = f"{self.auth.client.token}"
headers["Authorization"] = authorization
variables = {"projectID": project_id}
websocket.subscribe(
GQL_LABEL_CREATED_OR_UPDATED,
variables=variables,
callback=callback,
headers=headers,
authorization=authorization,
)
return websocket
label_created_or_updated(self, project_id, callback)
Subscribe a callback to a project, which is executed when a label is created or updated.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id |
str |
Identifier of the project |
required |
callback |
Callable[[str, str], NoneType] |
This function takes as input the id of the asset and its content. |
required |
Returns:
| Type | Description |
|---|---|
A subscription client |
Recipe
For more detailed examples on how to use Webhooks, See the related recipe
Source code in kili/subscriptions/label/__init__.py
@typechecked
def label_created_or_updated(self, project_id: str, callback: Callable[[str, str], None]):
# pylint: disable=line-too-long
"""
Subscribe a callback to a project, which is executed when a label is created or updated.
Args:
project_id: Identifier of the project
callback: This function takes as input the id of the asset and its content.
Returns:
A subscription client
!!! example "Recipe"
For more detailed examples on how to use Webhooks,
See [the related recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/webhooks.ipynb)
"""
ws_endpoint = self.auth.client.endpoint.replace("http", "ws")
websocket = SubscriptionGraphQLClient(ws_endpoint)
headers = {"Accept": "application/json", "Content-Type": "application/json"}
authorization = f"{self.auth.client.token}"
headers["Authorization"] = authorization
variables = {"projectID": project_id}
websocket.subscribe(
GQL_LABEL_CREATED_OR_UPDATED,
variables=variables,
callback=callback,
headers=headers,
authorization=authorization,
)
return websocket