Documentation examples

# Documentation examples ## Trivial case ```python= @task def t1(a: int) -> pd.DataFrame: """ This is why this task exists and how to use it. :param a: This is input a's comment :return: Table of results """ ``` Task Description: ``` This is why this task exists and how to use it. ``` Param `a` Description: ``` This is input a's comment ``` Return value Description: ``` Table of results ``` ## An example from numpy ```python= @task def my_function(x1: array_like, x2: array_like) -> ndarray: """ Return (x1 == x2) element-wise. Unlike `numpy.equal`, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray. Parameters ---------- x1, x2 : array_like of str or unicode Input arrays of the same shape. Returns ------- out : ndarray Output array of bools. See Also -------- not_equal, greater_equal, less_equal, greater, less """ ``` Task Description: ``` Return (x1 == x2) element-wise. Unlike `numpy.equal`, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray. ``` Param `x1` Description: ``` array_like of str or unicode. Input arrays of the same shape. ``` Param `x2` Description: ``` array_like of str or unicode. Input arrays of the same shape. ``` Return value Description: ``` Output array of bools. ``` ## An elaborate example that uses reStructuredText ```python= @task def my_function(x1: array_like, x2: array_like) -> ndarray: """ ############################################################# Distilled Data-efficient Image Transformer (base-sized model) ############################################################# Distilled data-efficient Image Transformer (DeiT) model pre-trained at resolution 224x224 and fine-tuned at resolution 384x384 on ImageNet-1k (1 million images, 1,000 classes). It was first introduced in the paper Training data-efficient image transformers & distillation through attention by Touvron et al. and first released in this repository. However, the weights were converted from the timm repository by Ross Wightman. Disclaimer: The team releasing DeiT did not write a model card for this model so this model card has been written by the Hugging Face team. ################# Model description ################# This model is a distilled Vision Transformer (ViT). It uses a distillation token, besides the class token, to effectively learn from a teacher (CNN) during both pre-training and fine-tuning. The distillation token is learned through backpropagation, by interacting with the class ([CLS]) and patch tokens through the self-attention layers. Images are presented to the model as a sequence of fixed-size patches (resolution 16x16), which are linearly embedded. ########################### Intended uses & limitations ########################### You can use the raw model for image classification. See the model hub to look for fine-tuned versions on a task that interests you. ########## How to use ########## Since this model is a distilled ViT model, you can plug it into DeiTModel, DeiTForImageClassification or DeiTForImageClassificationWithTeacher. Note that the model expects the data to be prepared using DeiTFeatureExtractor. Here we use AutoFeatureExtractor, which will automatically use the appropriate feature extractor given the model name. Here is how to use this model to classify an image of the COCO 2017 dataset into one of the 1,000 ImageNet classes: ```python from transformers import AutoFeatureExtractor, DeiTForImageClassificationWithTeacher from PIL import Image import requests url = 'http://images.cocodataset.org/val2017/000000039769.jpg' image = Image.open(requests.get(url, stream=True).raw) feature_extractor = AutoFeatureExtractor.from_pretrained('facebook/deit-base-distilled-patch16-384') model = DeiTForImageClassificationWithTeacher.from_pretrained('facebook/deit-base-distilled-patch16-384') inputs = feature_extractor(images=image, return_tensors="pt") outputs = model(**inputs) logits = outputs.logits # model predicts one of the 1000 ImageNet classes predicted_class_idx = logits.argmax(-1).item() print("Predicted class:", model.config.id2label[predicted_class_idx]) Currently, both the feature extractor and model support PyTorch. Tensorflow and JAX/FLAX are coming soon. ``` ############# Training data ############# This model was pretrained and fine-tuned with distillation on ImageNet-1k, a dataset consisting of 1 million images and 1k classes. ################## Training procedure ################## Preprocessing The exact details of preprocessing of images during training/validation can be found here. At inference time, images are resized/rescaled to the same resolution (438x438), center-cropped at 384x384 and normalized across the RGB channels with the ImageNet mean and standard deviation. Pretraining The model was trained on a single 8-GPU node for 3 days. Pre-training resolution is 224. For all hyperparameters (such as batch size and learning rate) we refer to table 9 of the original paper. .. list-table:: Evaluation results :header-rows: 1 * - Model - ImageNet - top-1 - accuracy - ImageNet * - DeiT-tiny - 72.2 - 91.1 - 5M - https://huggingface.co/facebook/deit-tiny-patch16-224 * - DeiT-tiny - 72.2 - 91.1 - 5M - https://huggingface.co/facebook/deit-tiny-patch16-224 Note that for fine-tuning, the best results are obtained with a higher resolution (384x384). Of course, increasing the model size will result in better performance. Parameters ---------- x1, x2 : array_like of str or unicode Input arrays of the same shape. Returns ------- out : ndarray Output array of bools. See Also -------- not_equal, greater_equal, less_equal, greater, less """ ``` Rendering of the [restructured text](http://rst.ninjs.org/#IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIwpEaXN0aWxsZWQgRGF0YS1lZmZpY2llbnQgSW1hZ2UgVHJhbnNmb3JtZXIgKGJhc2Utc2l6ZWQgbW9kZWwpCiMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMKICAgIAogICAgRGlzdGlsbGVkIGRhdGEtZWZmaWNpZW50IEltYWdlIFRyYW5zZm9ybWVyIChEZWlUKSBtb2RlbCBwcmUtdHJhaW5lZCBhdCByZXNvbHV0aW9uIDIyNHgyMjQgYW5kIGZpbmUtdHVuZWQgYXQgcmVzb2x1dGlvbiAzODR4Mzg0IG9uIEltYWdlTmV0LTFrICgxIG1pbGxpb24gaW1hZ2VzLCAxLDAwMCBjbGFzc2VzKS4gSXQgd2FzIGZpcnN0IGludHJvZHVjZWQgaW4gdGhlIHBhcGVyIFRyYWluaW5nIGRhdGEtZWZmaWNpZW50IGltYWdlIHRyYW5zZm9ybWVycyAmIGRpc3RpbGxhdGlvbiB0aHJvdWdoIGF0dGVudGlvbiBieSBUb3V2cm9uIGV0IGFsLiBhbmQgZmlyc3QgcmVsZWFzZWQgaW4gdGhpcyByZXBvc2l0b3J5LiBIb3dldmVyLCB0aGUgd2VpZ2h0cyB3ZXJlIGNvbnZlcnRlZCBmcm9tIHRoZSB0aW1tIHJlcG9zaXRvcnkgYnkgUm9zcyBXaWdodG1hbi4KCiAgICBEaXNjbGFpbWVyOiBUaGUgdGVhbSByZWxlYXNpbmcgRGVpVCBkaWQgbm90IHdyaXRlIGEgbW9kZWwgY2FyZCBmb3IgdGhpcyBtb2RlbCBzbyB0aGlzIG1vZGVsIGNhcmQgaGFzIGJlZW4gd3JpdHRlbiBieSB0aGUgSHVnZ2luZyBGYWNlIHRlYW0uCgojIyMjIyMjIyMjIyMjIyMjIwpNb2RlbCBkZXNjcmlwdGlvbgojIyMjIyMjIyMjIyMjIyMjIwogICAgVGhpcyBtb2RlbCBpcyBhIGRpc3RpbGxlZCBWaXNpb24gVHJhbnNmb3JtZXIgKFZpVCkuIEl0IHVzZXMgYSBkaXN0aWxsYXRpb24gdG9rZW4sIGJlc2lkZXMgdGhlIGNsYXNzIHRva2VuLCB0byBlZmZlY3RpdmVseSBsZWFybiBmcm9tIGEgdGVhY2hlciAoQ05OKSBkdXJpbmcgYm90aCBwcmUtdHJhaW5pbmcgYW5kIGZpbmUtdHVuaW5nLiBUaGUgZGlzdGlsbGF0aW9uIHRva2VuIGlzIGxlYXJuZWQgdGhyb3VnaCBiYWNrcHJvcGFnYXRpb24sIGJ5IGludGVyYWN0aW5nIHdpdGggdGhlIGNsYXNzIChbQ0xTXSkgYW5kIHBhdGNoIHRva2VucyB0aHJvdWdoIHRoZSBzZWxmLWF0dGVudGlvbiBsYXllcnMuCgogICAgSW1hZ2VzIGFyZSBwcmVzZW50ZWQgdG8gdGhlIG1vZGVsIGFzIGEgc2VxdWVuY2Ugb2YgZml4ZWQtc2l6ZSBwYXRjaGVzIChyZXNvbHV0aW9uIDE2eDE2KSwgd2hpY2ggYXJlIGxpbmVhcmx5IGVtYmVkZGVkLgoKIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjCkludGVuZGVkIHVzZXMgJiBsaW1pdGF0aW9ucwojIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMKICAgIAogICAgWW91IGNhbiB1c2UgdGhlIHJhdyBtb2RlbCBmb3IgaW1hZ2UgY2xhc3NpZmljYXRpb24uIFNlZSB0aGUgbW9kZWwgaHViIHRvIGxvb2sgZm9yIGZpbmUtdHVuZWQgdmVyc2lvbnMgb24gYSB0YXNrIHRoYXQgaW50ZXJlc3RzIHlvdS4KCiMjIyMjIyMjIyMKSG93IHRvIHVzZQojIyMjIyMjIyMjCiAgICBTaW5jZSB0aGlzIG1vZGVsIGlzIGEgZGlzdGlsbGVkIFZpVCBtb2RlbCwgeW91IGNhbiBwbHVnIGl0IGludG8gRGVpVE1vZGVsLCBEZWlURm9ySW1hZ2VDbGFzc2lmaWNhdGlvbiBvciBEZWlURm9ySW1hZ2VDbGFzc2lmaWNhdGlvbldpdGhUZWFjaGVyLiBOb3RlIHRoYXQgdGhlIG1vZGVsIGV4cGVjdHMgdGhlIGRhdGEgdG8gYmUgcHJlcGFyZWQgdXNpbmcgRGVpVEZlYXR1cmVFeHRyYWN0b3IuIEhlcmUgd2UgdXNlIEF1dG9GZWF0dXJlRXh0cmFjdG9yLCB3aGljaCB3aWxsIGF1dG9tYXRpY2FsbHkgdXNlIHRoZSBhcHByb3ByaWF0ZSBmZWF0dXJlIGV4dHJhY3RvciBnaXZlbiB0aGUgbW9kZWwgbmFtZS4KCiAgICBIZXJlIGlzIGhvdyB0byB1c2UgdGhpcyBtb2RlbCB0byBjbGFzc2lmeSBhbiBpbWFnZSBvZiB0aGUgQ09DTyAyMDE3IGRhdGFzZXQgaW50byBvbmUgb2YgdGhlIDEsMDAwIEltYWdlTmV0IGNsYXNzZXM6CgogICAgLi4gY29kZS1ibG9jazo6IHB5dGhvbgoKICAgICAgICBmcm9tIHRyYW5zZm9ybWVycyBpbXBvcnQgQXV0b0ZlYXR1cmVFeHRyYWN0b3IsIERlaVRGb3JJbWFnZUNsYXNzaWZpY2F0aW9uV2l0aFRlYWNoZXIKICAgICAgICBmcm9tIFBJTCBpbXBvcnQgSW1hZ2UKICAgICAgICBpbXBvcnQgcmVxdWVzdHMKICAgICAgICB1cmwgPSAnaHR0cDovL2ltYWdlcy5jb2NvZGF0YXNldC5vcmcvdmFsMjAxNy8wMDAwMDAwMzk3NjkuanBnJwogICAgICAgIGltYWdlID0gSW1hZ2Uub3BlbihyZXF1ZXN0cy5nZXQodXJsLCBzdHJlYW09VHJ1ZSkucmF3KQogICAgICAgIGZlYXR1cmVfZXh0cmFjdG9yID0gQXV0b0ZlYXR1cmVFeHRyYWN0b3IuZnJvbV9wcmV0cmFpbmVkKCdmYWNlYm9vay9kZWl0LWJhc2UtZGlzdGlsbGVkLXBhdGNoMTYtMzg0JykKICAgICAgICBtb2RlbCA9IERlaVRGb3JJbWFnZUNsYXNzaWZpY2F0aW9uV2l0aFRlYWNoZXIuZnJvbV9wcmV0cmFpbmVkKCdmYWNlYm9vay9kZWl0LWJhc2UtZGlzdGlsbGVkLXBhdGNoMTYtMzg0JykKICAgICAgICBpbnB1dHMgPSBmZWF0dXJlX2V4dHJhY3RvcihpbWFnZXM9aW1hZ2UsIHJldHVybl90ZW5zb3JzPSJwdCIpCiAgICAgICAgb3V0cHV0cyA9IG1vZGVsKCoqaW5wdXRzKQogICAgICAgIGxvZ2l0cyA9IG91dHB1dHMubG9naXRzCiAgICAgICAgIyBtb2RlbCBwcmVkaWN0cyBvbmUgb2YgdGhlIDEwMDAgSW1hZ2VOZXQgY2xhc3NlcwogICAgICAgIHByZWRpY3RlZF9jbGFzc19pZHggPSBsb2dpdHMuYXJnbWF4KC0xKS5pdGVtKCkKICAgICAgICBwcmludCgiUHJlZGljdGVkIGNsYXNzOiIsIG1vZGVsLmNvbmZpZy5pZDJsYWJlbFtwcmVkaWN0ZWRfY2xhc3NfaWR4XSkKICAgICAgICBDdXJyZW50bHksIGJvdGggdGhlIGZlYXR1cmUgZXh0cmFjdG9yIGFuZCBtb2RlbCBzdXBwb3J0IFB5VG9yY2guIFRlbnNvcmZsb3cgYW5kIEpBWC9GTEFYIGFyZSBjb21pbmcgc29vbi4KCgojIyMjIyMjIyMjIyMjClRyYWluaW5nIGRhdGEKIyMjIyMjIyMjIyMjIwogICAgVGhpcyBtb2RlbCB3YXMgcHJldHJhaW5lZCBhbmQgZmluZS10dW5lZCB3aXRoIGRpc3RpbGxhdGlvbiBvbiBJbWFnZU5ldC0xaywgYSBkYXRhc2V0IGNvbnNpc3Rpbmcgb2YgMSBtaWxsaW9uIGltYWdlcyBhbmQgMWsgY2xhc3Nlcy4KCiMjIyMjIyMjIyMjIyMjIyMjIwpUcmFpbmluZyBwcm9jZWR1cmUKIyMjIyMjIyMjIyMjIyMjIyMjCiAgICBQcmVwcm9jZXNzaW5nCiAgICBUaGUgZXhhY3QgZGV0YWlscyBvZiBwcmVwcm9jZXNzaW5nIG9mIGltYWdlcyBkdXJpbmcgdHJhaW5pbmcvdmFsaWRhdGlvbiBjYW4gYmUgZm91bmQgaGVyZS4KCiAgICBBdCBpbmZlcmVuY2UgdGltZSwgaW1hZ2VzIGFyZSByZXNpemVkL3Jlc2NhbGVkIHRvIHRoZSBzYW1lIHJlc29sdXRpb24gKDQzOHg0MzgpLCBjZW50ZXItY3JvcHBlZCBhdCAzODR4Mzg0IGFuZCBub3JtYWxpemVkIGFjcm9zcyB0aGUgUkdCIGNoYW5uZWxzIHdpdGggdGhlIEltYWdlTmV0IG1lYW4gYW5kIHN0YW5kYXJkIGRldmlhdGlvbi4KCiAgICBQcmV0cmFpbmluZwogICAgVGhlIG1vZGVsIHdhcyB0cmFpbmVkIG9uIGEgc2luZ2xlIDgtR1BVIG5vZGUgZm9yIDMgZGF5cy4gUHJlLXRyYWluaW5nIHJlc29sdXRpb24gaXMgMjI0LiBGb3IgYWxsIGh5cGVycGFyYW1ldGVycyAoc3VjaCBhcyBiYXRjaCBzaXplIGFuZCBsZWFybmluZyByYXRlKSB3ZSByZWZlciB0byB0YWJsZSA5IG9mIHRoZSBvcmlnaW5hbCBwYXBlci4KCiAgICAuLiBsaXN0LXRhYmxlOjogRXZhbHVhdGlvbiByZXN1bHRzCiAgICAgICA6aGVhZGVyLXJvd3M6IDEKCiAgICAgICAqIC0gTW9kZWwKICAgICAgICAgLSBJbWFnZU5ldAogICAgICAgICAtIHRvcC0xCiAgICAgICAgIC0gYWNjdXJhY3kKICAgICAgICAgLSBJbWFnZU5ldAogICAgICAgKiAtIERlaVQtdGlueQogICAgICAgICAtIDcyLjIKICAgICAgICAgLSA5MS4xCiAgICAgICAgIC0gNU0KICAgICAgICAgLSBodHRwczovL2h1Z2dpbmdmYWNlLmNvL2ZhY2Vib29rL2RlaXQtdGlueS1wYXRjaDE2LTIyNAogICAgICAgKiAtIERlaVQtdGlueQogICAgICAgICAtIDcyLjIKICAgICAgICAgLSA5MS4xCiAgICAgICAgIC0gNU0KICAgICAgICAgLSBodHRwczovL2h1Z2dpbmdmYWNlLmNvL2ZhY2Vib29rL2RlaXQtdGlueS1wYXRjaDE2LTIyNAoKICAgIE5vdGUgdGhhdCBmb3IgZmluZS10dW5pbmcsIHRoZSBiZXN0IHJlc3VsdHMgYXJlIG9idGFpbmVkIHdpdGggYSBoaWdoZXIgcmVzb2x1dGlvbiAoMzg0eDM4NCkuIE9mIGNvdXJzZSwgaW5jcmVhc2luZyB0aGUgbW9kZWwgc2l6ZSB3aWxsIHJlc3VsdCBpbiBiZXR0ZXIgcGVyZm9ybWFuY2UuCg==)