canary.argument_pipeline package¶

The argument_pipeline package contains the functionality required to analyse a unstructured document of natural language.

analyse(document: str, min_link_confidence=0.8, min_support_confidence=0.8, min_attack_confidence=0.8)[source]¶

Analyses a document .

Parameters

document: str: The document text that is being analysed
min_link_confidence: float, default=0.8: The minimum confidence needed for two arguments to be considered “linked”
min_support_confidence: float, default=0.8: The minimum confidence needed to be classified as a support relation
min_attack_confidence: float, default=0.8: The minimum confidence needed to be classified as an attack relation

Returns

dict: the SADFace document.

Notes

Refer to https://github.com/ARG-ENU/SADFace

Examples

>>> from canary import analyse
>>> document_text = "..."
>>> analysis = analyse(document_text, min_link_confidence=0.65)
>>> analysis
{
    "metadata": {...},
    "resources": {...},
    "nodes": {...},
    "edges": {...}
}

analyse_file(file, min_link_confidence=0.8, min_support_confidence=0.8, min_attack_confidence=0.8)[source]¶

Wrapper around the analyse function which takes in a file location as a string.

Parameters

file: str: The absolute file path
min_link_confidence: float, default=0.8: The minimum confidence needed for two arguments to be considered “linked”
min_support_confidence: float, default=0.8: The minimum confidence needed to be classified as a support relation
min_attack_confidence: float, default=0.8: The minimum confidence needed to be classified as an attack relation

Returns

dict: the SADFace document.

Notes

Refer to https://github.com/ARG-ENU/SADFace

Examples

>>> from canary import analyse_file
>>> document = "/Users/my_user/doc.txt"
>>> analysis = analyse_file(document)
>>> analysis
{
    "metadata": {...},
    "resources": {...},
    "nodes": {...},
    "edges": {...}
}

download_model(model: str, download_to: Optional[str] = None, overwrite=False)[source]¶

Downloads the pretrained Canary models from a GitHub.

Parameters

model: str: The model ID to download.
download_to: str: Where to download the model to.
overwrite: bool, default=False: Should Canary overwrite existing models if they are already present.

load_model(model_id: str, model_dir=None, download_if_missing=False)[source]¶

Load a trained Canary model from disk.

Parameters

model_id: str: The ID of the model to download
model_dir: str: Where the model should be loaded from
download_if_missing: bool: Should Canary attempt to download the model if it is not present on disk?

Returns

Model: The Canary model.

Examples

>>> import canary
>>> component_detector = canary.load_model("argument_component")
>>> print(component_detector.__class__.__name__)

Submodules¶

canary.argument_pipeline.argument_segmentation module¶

class ArgumentSegmenter(model_id=None)[source]¶

Bases: canary.argument_pipeline.base.Model

Argument Segmenter using Conditional Random Fields.

Examples

>>> import canary
>>> segmenter = canary.load_model("arg_segmenter")
>>> sentence = "To sum up, I believe that a higher pay can be one of the incentive if were to encourage harder-working employees."
>>> print(segmenter.predict(sentence))
[('To', 'O'), ('sum', 'O'), ('up', 'O'), (',', 'O'), ('I', 'O'), ('believe', 'O'), ('that', 'O'), ('a', 'Arg-B'), ('higher', 'Arg-I'), ('pay', 'Arg-I'), ('can', 'Arg-I'), ('be', 'Arg-I'), ('one', 'Arg-I'), ('of', 'Arg-I'), ('the', 'Arg-I'), ('incentive', 'Arg-I'), ('if', 'Arg-I'), ('were', 'Arg-I'), ('to', 'Arg-I'), ('encourage', 'Arg-I'), ('harder-working', 'Arg-I'), ('employees', 'Arg-I'), ('.', 'O')]

Attributes

metrics: Property which returns model metrics
model_id: Returns the model id
supports_probability: Returns a boolean if the model supports probability prediction.

Methods

`fit`(training_data, training_labels)	Fits a model to the training data.
`get_components_from_document`(document)	Helper method which extracts components from a document which have been identified as argument spans.
`predict`(data[, probability, binary])	Make a prediction on some data.
`save`([save_to])	Saves the model to disk after training
`set_model`(model)	Set the scikit-learn model that sits under self._model
`train`([pipeline_model, train_data, ...])

default_train

static default_train()[source]¶

get_components_from_document(document: str) → list[source]¶

Helper method which extracts components from a document which have been identified as argument spans.

Parameters

document: str: The document which is to be analysed.

Returns

list: A list of dictionary items which detail the components that have been identified.

predict(data, probability=False, binary=False)[source]¶

Make a prediction on some data. A wrapper around scikit-learn’s predict method.

Parameters

data:: The data the predictor will be ran on.
probability: bool: boolean indicating if the method should return a probability prediction.

Returns

Union[list, bool]: a boolean indicating the predictions or list of predictions

Notes

Not all models support probability predictions. This can be checked with the supports_probability property.

classmethod train(pipeline_model=None, train_data=None, test_data=None, train_targets=None, test_targets=None, save_on_finish=True, *args, **kwargs)[source]¶

canary.argument_pipeline.base module¶

class Model(model_id=None)[source]¶

Bases: object

Abstract class that other Canary models descend from

Attributes

metrics: Property which returns model metrics
model_id: Returns the model id
supports_probability: Returns a boolean if the model supports probability prediction.

Methods

`fit`(training_data, training_labels)	Fits a model to the training data.
`predict`(data[, probability])	Make a prediction on some data.
`save`([save_to])	Saves the model to disk after training
`set_model`(model)	Set the scikit-learn model that sits under self._model
`train`([pipeline_model, train_data, ...])	Classmethod which initialises a model and trains it on the provided training data.

fit(training_data: list, training_labels: list)[source]¶

Fits a model to the training data.

Parameters

training_data: list: The training data on which the model is fitted
training_labels: list:: The training labels on which the data is fitted to

Returns

self

property metrics¶

Property which returns model metrics

Returns

dict: Returns the metrics of the model as a dict

Examples

>>> self.metrics
{"f1score" 54.6, ...}

property model_id¶

Returns the model id

Returns

str: The model id

predict(data, probability=False) → Union[list, bool][source]¶

Make a prediction on some data. A wrapper around scikit-learn’s predict method.

Parameters

data:: The data the predictor will be ran on.
probability: bool: boolean indicating if the method should return a probability prediction.

Returns

Union[list, bool]: a boolean indicating the predictions or list of predictions

Notes

Not all models support probability predictions. This can be checked with the supports_probability property.

save(save_to: Optional[pathlib.Path] = None)[source]¶

Saves the model to disk after training

Parameters

save_to: str: Where to save the model

set_model(model)[source]¶

Set the scikit-learn model that sits under self._model

Parameters

model: a model that conforms to the standard scikit-learn API

property supports_probability¶

Returns a boolean if the model supports probability prediction.

Returns

str: The boolean value indicating if probability predictions are possible.

classmethod train(pipeline_model=None, train_data=None, test_data=None, train_targets=None, test_targets=None, save_on_finish=True, *args, **kwargs)[source]¶

Classmethod which initialises a model and trains it on the provided training data.

Parameters

pipeline_model: The model which is trained to make predictions
train_data: list: Training data
test_data: list: Test data
train_targets: list: The training labels
test_targets: list: The test labels
save_on_finish: bool: Should the model be saved when training has finished?
*args: tuple: Additional positional arguments
**kwargs: dict: Additional keyed-arguments

Returns

Model: The model instance

canary.argument_pipeline.binary_detection module¶

class ArgumentDetector(model_id=None)[source]¶

Bases: canary.argument_pipeline.base.Model

Argument Detector

Performs binary classification on text to determine if it is argumentative or not.

Examples

>>> import canary
>>> arg_detector = canary.load_model("argument_detector")
>>> component = "The more body fat that you have, the greater your risk for heart disease"
>>> print(arg_detector.predict(component))
True

>>> print(arg_detector.predict(component, probability=True))
{False: 0.0, True: 1.0}

Attributes

metrics: Property which returns model metrics
model_id: Returns the model id
supports_probability: Returns a boolean if the model supports probability prediction.

Methods

`default_train`()	Default training method which supplies the default training set
`fit`(training_data, training_labels)	Fits a model to the training data.
`predict`(data[, probability])	Make a prediction on some data.
`save`([save_to])	Saves the model to disk after training
`set_model`(model)	Set the scikit-learn model that sits under self._model
`train`([pipeline_model, train_data, ...])

static default_train()[source]¶: Default training method which supplies the default training set

classmethod train(pipeline_model=None, train_data=None, test_data=None, train_targets=None, test_targets=None, save_on_finish=False, *args, **kwargs)[source]¶

canary.argument_pipeline.component_prediction module¶

canary.argument_pipeline.link_predictor module¶

class LinkFeatures(*args: Any, **kwargs: Any)[source]¶

Bases: sklearn.base., sklearn.base.

Transformer which handles LinkPredictor features

Methods

`__call__`(args, *kwargs)	Call self as a function.
`fit`(x[, y])	Fits self to data provided.
`transform`(x)	Transform data into features

feats = [sklearn.base.TransformerMixin, sklearn.base.TransformerMixin, sklearn.base.TransformerMixin, sklearn.base.TransformerMixin]¶

fit(x, y=None)[source]¶

Fits self to data provided.

Parameters

x: list: A list of datapoints which are to be transformed using the mixin

Returns

scipy.sparse.hstack: The features of the inputted list

canary.argument_pipeline.structure_prediction module¶

The structure prediction module provides functionality in respect toe the prediction and structure of a document.

class StructureFeatures(*args: Any, **kwargs: Any)[source]¶

Bases: sklearn.base., sklearn.base.

A custom feature transformer used for extracting features relevant to structure prediction

Methods

`__call__`(args, *kwargs)	Call self as a function.
`fit`(x[, y])	Fits self to data provided.
`transform`(x)	Transform data into features

cover_features = [sklearn.base.TransformerMixin, sklearn.base.TransformerMixin, sklearn.base.TransformerMixin, sklearn.base.TransformerMixin, sklearn.base.TransformerMixin, sklearn.base.TransformerMixin, sklearn.base.TransformerMixin]¶

fit(x, y=None)[source]¶

Fits self to data provided.

Parameters

x: list: The data on which the transformer is fitted.
y: list, default=None: Ignored. Providing will have no effect. Provided for compatibility reasons.

Returns

self

transform(x) → list[source]¶

Transform data into features

Parameters

x: list: A list of datapoints which are to be transformed using the mixin

Returns

scipy.sparse.hstack: The features of the inputted list

`default_train`()	Default training method
`fit`(training_data, training_labels)	Fits a model to the training data.
`predict`(data[, probability])	Make a prediction on some data.
`save`([save_to])	Saves the model to disk after training
`set_model`(model)	Set the scikit-learn model that sits under self._model
`train`([pipeline_model, train_data, ...])