Package: humannotator
HumannotatorLibrary for conveniently creating simple customizable annotators
for manual annotation of your dataJenia Kim, Lawrence VriendWorks well with Jupyter notebooks:Use caseThe humannotator provides an easy way to set up custom annotators.
This tool is for you if manual annotation is part of your workflow
and you are looking for a solution that is:LightweightCustomizableEasy to set upIntegrates with Jupyter/pandas/PythonQuick startInstall the humannotatorInstall with conda:conda install -c lcvriend humannotatorOr use pip:pip install humannotatorCreate a simple annotatorLoad the dataDefine the tasksInstantiate the annotatorimportpandasaspdfromhumannotatorimportAnnotator# load datadf=pd.read_csv('examples/popcorn_classics.csv',sep=';',index_col=0)# set up the annotatorratings=['One bag','Two bags','Three bags','Four bags','Five-bagger',]annotator=Annotator(df,name='VFA | Rate my popcorn classics')annotator.tasks['Bags of popcorn']=ratings# run annotatorannotator(user='GT')In Jupyter this gives:Annotate your dataUse the annotator by calling it:annotator().The annotator keeps track of where you were.Highlight phrases with the 'phrases' argument.The annotator stores user (if provided) and timestamp with the annotation.Access your annotationsThe annotations are conveniently stored in a pandasDataFrame.Access the annotations with theannotatedattribute.Get the indeces of the records without annotation withunannotated.Return the data merged with its annotations with themergedmethod.Store your annotationsStore the annotator with thesavemethod.Load the annotator with theloadmethod.Load dataThe annotator acceptslist,dict,SeriesandDataFrameobjects as data.The data will be converted to a dataframe internally.DataframesBy default, the annotator will use the dataframe'sindexand allcolumns.Useload_datato easily create adataobject if you need more control:id_colsets the column to be used as index.item_colsset the column or columns to be displayed.Define tasksTasks can be set up through subscription or with thetask_factory.Setting up tasks with the task factoryCreate a task by passingtask_factory:thekindof taskthenameof the task(optionally) aninstruction(optionally) a list ofdependencieswhether it isnullable(default is False)anykwargsnecessary (depends on the kind of task)Typically:task_factory('kind','name',instruction='instruction',dependencies=dependencies,nullable=True/False,**kwargs,)Passing a dict or list tokindwill create a categorical task.In this case thecategorieskwarg is ignored.Setting up tasks through subscriptionIt is also possible to instantiate an annotator and add tasks through subscription:a=Annotator()a.tasks['topic']=['economy','politics','media','other']a.tasks['factual']=bool,"Is the article factual?",FalseTo add a task like this, you minimally need to provide thekindof task you are trying to create.
Optionally, you can addinstruction,nullability,dependenciesand any other kwargs (as dictionary).
Change the order in which tasks are prompted to the user with theorderattribute ontasks.Available taskskindkwargsdtypedescriptionstrobjectStringregexregexobjectString validated by regexintInt64Nullable integerfloatfloat64FloatboolboolBooleancategorycategoriesCategoricalDtypeCategorical variabledatedatetime64[ns]DateDependenciesDependencies consist of aconditionand avalue, that can be passed as tuple:("col1 == 'x'",False)The condition is apandas query statement.
Before prompting the user for input, the condition is evaluated on the current annotation.
If the query evaluates to True then the value will be assigned automatically.AnnotatorCalling the annotatorThe annotator detects if it is run from Jupyter.
If so, the annotator will render itself in html and css.
If not, the annotator will render itself as text.
You can annotate a selection of records by passing a list of ids to the annotator call. If you want to reannotate ids that have already been annotated, then setredoto True when calling the annotator.Instantiating the annotatorargumentstasks :Task, list of Task objects, Tasks, Annotations or DataFrameAnnotation task(s).
If passed a DataFrame, then the tasks will be inferred from it.
Annotation data in the dataframe will also be initialized.data :data, list-/dict-like, Series or DataFrame, default NoneData to be annotated.
If `data` is not already a data object,
then it will be passed through `load_data`.
The annotator can be instantiated without data,
but will only work after data is loaded.user :str, default NoneName of the user.name :str, default 'HUMANNOTATOR'Name of the annotator.save_data :boolean, default FalseSet flag to True if you want to store the data with the annotator.
This will ensure that the pickled object, will contain the data.other parametersDISPLAYtext_display :boolean, default NoneIf True will display the annotator in plain text instead of html.HTMLmarkdown :boolean, default {markdown}If True will pass values through markdown before rendering.markdown_extensions :list, default {markdown_extensions}List of markdown extensions to apply.escape_html :boolean, default {escape_html}If true will escape html content within items.maxheight :str, default '{maxheight_items}'Max height before item gets y-scroll bar.
Set to None to have no maximum.DATAitem_cols :str or list of str, default NoneName(s) of dataframe column(s) to display when annotating.
By default: display all columns.id_col :str, default NoneName of dataframe column to use as index.
By default: use the dataframe's index.HIGHLIGHTERphrases :str, list of str, default NonePhrases to highlight in the display.
The phrases can be regexes.
It also to pass in a dict where:
- the keys are the phrases
- the values are the css stylingescape :boolean, default FalseSet escape to True in order to escape the phrases.flags :int, default 0 (no flags)Flags to pass through to the re module, e.g. re.IGNORECASE.TRUNCATERtruncate :boolean, default {truncate}Set to False to not truncate items.trunc_limit :int, default {truncate_word_limit}The number of words beyond which an item will be truncated.The module contains aconfiguration filein which some of the default behaviour of the humannotator can be configured.