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
@Compatible(['v1', 'v2'])
@typechecked
@deprecate(removed_in="2.115")
def labels(self,
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', 'skipped'],
first: Optional[int] = None,
honeypot_mark_gte: Optional[float] = None,
honeypot_mark_lte: Optional[float] = None,
id_contains: Optional[List[str]] = None,
json_response_contains: Optional[List[str]] = None,
label_id: Optional[str] = None,
project_id: Optional[str] = None,
skip: int = 0,
skipped: Optional[bool] = None,
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:
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.
json_response_contains: Returned labels should have a substring of the jsonResponse that belongs
to that list, if given.
label_id: Identifier of the label.
project_id: Identifier of the project.
skip: Number of labels to skip (they are ordered by their date of creation, first to last).
skipped: Returned labels should have a label which is skipped
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',
]
}
# 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,
'externalIdIn': 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,
'jsonResponseContains': json_response_contains,
'search': category_search,
'skipped': skipped,
'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]):
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, Label)
# 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',
'skipped'
],
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(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
@Compatible(['v1', 'v2'])
@typechecked
@deprecate(removed_in="2.115")
def count_labels(self,
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,
json_response_contains: Optional[List[str]] = None,
label_id: Optional[str] = None,
project_id: Optional[str] = None,
skipped: Optional[bool] = 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.
json_response_contains: Returned labels should have a substring of the jsonResponse that
belongs to that list, if given.
label_id: Identifier of the label.
project_id: Identifier of the project.
skipped: Returned labels should have a label which is skipped
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 json_response_contains is not None:
message = """
The field `json_response_contains` is deprecated since: 2.113
It will be removed in: 2.115
Please use `category_search` to filter based on categories in labels
"""
warnings.warn(message, DeprecationWarning)
if category_search:
validate_category_search_query(category_search)
variables = {
'where': {
'id': label_id,
'asset': {
'id': asset_id,
'externalIdIn': 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,
'jsonResponseContains': json_response_contains,
'search': category_search,
'skipped': skipped,
'typeIn': type_in,
}
}
result = self.auth.client.execute(GQL_LABELS_COUNT, variables)
count = format_result('data', result)
return count
count_labels(self, 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, json_response_contains=None, label_id=None, project_id=None, skipped=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 |
json_response_contains |
Optional[List[str]] |
Returned labels should have a substring of the jsonResponse that belongs to that list, if given. |
None |
label_id |
Optional[str] |
Identifier of the label. |
None |
project_id |
Optional[str] |
Identifier of the project. |
None |
skipped |
Optional[bool] |
Returned labels should have a label which is skipped |
None |
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
@Compatible(['v1', 'v2'])
@typechecked
@deprecate(removed_in="2.115")
def count_labels(self,
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,
json_response_contains: Optional[List[str]] = None,
label_id: Optional[str] = None,
project_id: Optional[str] = None,
skipped: Optional[bool] = 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.
json_response_contains: Returned labels should have a substring of the jsonResponse that
belongs to that list, if given.
label_id: Identifier of the label.
project_id: Identifier of the project.
skipped: Returned labels should have a label which is skipped
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 json_response_contains is not None:
message = """
The field `json_response_contains` is deprecated since: 2.113
It will be removed in: 2.115
Please use `category_search` to filter based on categories in labels
"""
warnings.warn(message, DeprecationWarning)
if category_search:
validate_category_search_query(category_search)
variables = {
'where': {
'id': label_id,
'asset': {
'id': asset_id,
'externalIdIn': 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,
'jsonResponseContains': json_response_contains,
'search': category_search,
'skipped': skipped,
'typeIn': type_in,
}
}
result = self.auth.client.execute(GQL_LABELS_COUNT, variables)
count = format_result('data', result)
return count
export_labels_as_df(self, project_id, fields=['author.email', 'author.id', 'createdAt', 'id', 'labelType', 'skipped'], 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', 'skipped'] |
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',
'skipped'
],
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(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, 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', 'skipped'], first=None, honeypot_mark_gte=None, honeypot_mark_lte=None, id_contains=None, json_response_contains=None, label_id=None, project_id=None, skip=0, skipped=None, 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 |
|---|---|---|---|
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', 'skipped'] |
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 |
json_response_contains |
Optional[List[str]] |
Returned labels should have a substring of the jsonResponse that belongs to that list, if given. |
None |
label_id |
Optional[str] |
Identifier of the label. |
None |
project_id |
Optional[str] |
Identifier of the project. |
None |
skip |
int |
Number of labels to skip (they are ordered by their date of creation, first to last). |
0 |
skipped |
Optional[bool] |
Returned labels should have a label which is skipped |
None |
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
@Compatible(['v1', 'v2'])
@typechecked
@deprecate(removed_in="2.115")
def labels(self,
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', 'skipped'],
first: Optional[int] = None,
honeypot_mark_gte: Optional[float] = None,
honeypot_mark_lte: Optional[float] = None,
id_contains: Optional[List[str]] = None,
json_response_contains: Optional[List[str]] = None,
label_id: Optional[str] = None,
project_id: Optional[str] = None,
skip: int = 0,
skipped: Optional[bool] = None,
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:
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.
json_response_contains: Returned labels should have a substring of the jsonResponse that belongs
to that list, if given.
label_id: Identifier of the label.
project_id: Identifier of the project.
skip: Number of labels to skip (they are ordered by their date of creation, first to last).
skipped: Returned labels should have a label which is skipped
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',
]
}
# 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,
'externalIdIn': 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,
'jsonResponseContains': json_response_contains,
'search': category_search,
'skipped': skipped,
'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
@Compatible(['v1', 'v2'])
@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)
@Compatible(['v1', 'v2'])
@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,
skipped: Optional[bool] = False):
"""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 `AUTOSAVE`, `DEFAULT`, `PREDICTION` or `REVIEW`
seconds_to_label: Time to create the label
skipped: Describe if the label is skipped or not
!!! 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,
'skipped': skipped},
'where': {'id': label_asset_id}
}
result = self.auth.client.execute(GQL_APPEND_TO_LABELS, variables)
return format_result('data', result, Label)
@Compatible(['v1', 'v2'])
@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)
@Compatible(['v1', 'v2'])
@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_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, skipped=False)
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 |
skipped |
Optional[bool] |
Describe if the label is skipped or not |
False |
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
@Compatible(['v1', 'v2'])
@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,
skipped: Optional[bool] = False):
"""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 `AUTOSAVE`, `DEFAULT`, `PREDICTION` or `REVIEW`
seconds_to_label: Time to create the label
skipped: Describe if the label is skipped or not
!!! 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,
'skipped': skipped},
'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
@Compatible(['v1', 'v2'])
@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
@Compatible(['v1', 'v2'])
@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
@Compatible(['v1', 'v2'])
@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
@dataclass
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