from fastai.gen_doc.nbdoc import *
from fastai.text import *
from fastai.gen_doc.nbdoc import *
from fastai import *
This module contains the TextDataset
class, which is the main dataset you should use for your NLP tasks. It automatically does the preprocessing steps described in text.transform
. It also contains all the functions to quickly get a TextDataBunch
ready.
You should get your data in one of the following formats to make the most of the fastai library and use one of the factory methods of one of the TextDataBunch
classes:
If you are assembling the data for a language model, you should define your labels as always 0 to respect those formats. The first time you create a DataBunch
with one of those functions, your data will be preprocessed automatically. You can save it, so that the next time you call it is almost instantaneous.
Below are the classes that help assembling the raw data in a DataBunch
suitable for NLP.
show_doc(TextLMDataBunch, title_level=3, doc_string=False)
class
TextLMDataBunch
[source]
TextLMDataBunch
(train_dl
:DataLoader
,valid_dl
:DataLoader
,test_dl
:Optional
[DataLoader
]=None
,device
:device
=None
,tfms
:Optional
[Collection
[Callable
]]=None
,path
:PathOrStr
='.'
,collate_fn
:Callable
='data_collate'
) ::TextDataBunch
show_doc(TextLMDataBunch.show_batch)
show_batch
[source]
show_batch
(sep
=' '
,ds_type
:DatasetType
=<DatasetType.Train: 1>
,rows
:int
=10
,max_len
:int
=100
)
Show rows
texts from a batch of ds_type
, tokens are joined with sep
, truncated at max_len
.
show_doc(TextClasDataBunch, title_level=3, doc_string=False)
class
TextClasDataBunch
[source]
TextClasDataBunch
(train_dl
:DataLoader
,valid_dl
:DataLoader
,test_dl
:Optional
[DataLoader
]=None
,device
:device
=None
,tfms
:Optional
[Collection
[Callable
]]=None
,path
:PathOrStr
='.'
,collate_fn
:Callable
='data_collate'
) ::TextDataBunch
Create a DataBunch
suitable for a text classifier: all the texts are grouped by length (with a bit of randomness for the training set) then padded.
show_doc(TextClasDataBunch.show_batch)
show_batch
[source]
show_batch
(sep
=' '
,ds_type
:DatasetType
=<DatasetType.Train: 1>
,rows
:int
=10
,max_len
:int
=100
)
Show rows
texts from a batch of ds_type
, tokens are joined with sep
, truncated at max_len
.
show_doc(TextDataBunch, title_level=3, doc_string=False)
class
TextDataBunch
[source]
TextDataBunch
(train_dl
:DataLoader
,valid_dl
:DataLoader
,test_dl
:Optional
[DataLoader
]=None
,device
:device
=None
,tfms
:Optional
[Collection
[Callable
]]=None
,path
:PathOrStr
='.'
,collate_fn
:Callable
='data_collate'
) ::DataBunch
Create a DataBunch
with the raw texts. This is only going to work if they all ahve the same lengths.
All those classes have the following factory methods.
show_doc(TextDataBunch.from_folder, doc_string=False)
This function will create a DataBunch
from texts placed in path
in a train
, valid
and maybe test
folders. Text files in the train
and valid
folders should be places in subdirectories according to their classes (always the same for a language model) and the ones for the test
folder should all be placed there directly. tokenizer
will be used to parse those texts into tokens. The shuffle
flag will optionally shuffle the texts found.
You can pass a specific vocab
for the numericalization step (if you are building a classifier from a language model you fine-tuned for instance). kwargs will be split between the TextDataset
function and to the class initialization, you can precise there parameters such as max_vocab
, chunksize
, min_freq
, n_labels
(see the TextDataset
documentation) or bs
, bptt
and pad_idx
(see the sections LM data and classifier data).
show_doc(TextDataBunch.from_csv, doc_string=False)
This function will create a DataBunch
from texts placed in path
in a csv file and maybe test
csv file opened with header
. You can specify txt_cols
and lbl_cols
or just an integer n_labels
in which case the label(s) should be the first column(s). tokenizer
will be used to parse those texts into tokens.
You can pass a specific vocab
for the numericalization step (if you are building a classifier from a language model you fine-tuned for instance). kwargs will be split between the TextDataset
function and to the class initialization, you can precise there parameters such as max_vocab
, chunksize
, min_freq
, n_labels
(see the TextDataset
documentation) or bs
, bptt
and pad_idx
(see the sections LM data and classifier data).
show_doc(TextDataBunch.from_df, doc_string=False)
This function will create a DataBunch
in path
from texts in train_df
, valid_df
and maybe test_df
. By default, those are opened with header=infer
but you can specify another value in the kwargs. You can specify txt_cols
and lbl_cols
or just an integer n_labels
in which case the label(s) should be the first column(s). tokenizer
will be used to parse those texts into tokens.
You can pass a specific vocab
for the numericalization step (if you are building a classifier from a language model you fine-tuned for instance). kwargs will be split between the TextDataset
function and to the class initialization, you can precise there parameters such as max_vocab
, chunksize
, min_freq
, n_labels
(see the TextDataset
documentation) or bs
, bptt
and pad_idx
(see the sections LM data and classifier data).
show_doc(TextDataBunch.from_tokens, doc_string=False)
This function will create a DataBunch
from trn_tok
, trn_lbls
, val_tok
, val_lbls
and maybe tst_tok
.
You can pass a specific vocab
for the numericalization step (if you are building a classifier from a language model you fine-tuned for instance). kwargs will be split between the TextDataset
function and to the class initialization, you can precise there parameters such as max_vocab
, chunksize
, min_freq
, n_labels
, tok_suff
and lbl_suff
(see the TextDataset
documentation) or bs
, bptt
and pad_idx
(see the sections LM data and classifier data).
show_doc(TextDataBunch.from_ids, doc_string=False)
from_ids
[source]
from_ids
(path
:PathOrStr
,vocab
:Vocab
,trn_ids
:Collection
[Collection
[int
]],val_ids
:Collection
[Collection
[int
]],tst_ids
:Collection
[Collection
[int
]]=None
,trn_lbls
:Collection
[Union
[int
,float
]]=None
,val_lbls
:Collection
[Union
[int
,float
]]=None
,classes
:ArgStar
=None
,kwargs
) →DataBunch
This function will create a DataBunch
in path
from texts already processed into trn_ids
, trn_lbls
, val_ids
, val_lbls
and maybe tst_ids
. You can specify the corresponding classes
if applciable. You must specify the vocab
so that the RNNLearner
class can later infer the corresponding sizes in the model it will create. kwargs will be passed to the class initialization.
To avoid losing time preprocessing the text data more than once, you should save/load your TextDataBunch
using thse methods.
show_doc(TextDataBunch.load)
load
[source]
load
(path
:PathOrStr
,cache_name
:PathOrStr
='tmp'
,kwargs
)
Load a TextDataBunch
from path/cache_name
. kwargs
are passed to the dataloader creation.
show_doc(TextDataBunch.save)
Untar the IMDB sample dataset if not already done:
path = untar_data(URLs.IMDB_SAMPLE)
path
PosixPath('/home/ubuntu/.fastai/data/imdb_sample')
Since it comes in the form of csv files, we will use the corresponding text_data
method. Here is an overview of what your file you should look like:
pd.read_csv(path/'texts.csv').head()
label | text | is_valid | |
---|---|---|---|
0 | negative | Un-bleeping-believable! Meg Ryan doesn't even ... | False |
1 | positive | This is a extremely well-made film. The acting... | False |
2 | negative | Every once in a long while a movie will come a... | False |
3 | positive | Name just says it all. I watched this movie wi... | False |
4 | negative | This movie succeeds at being one of the most u... | False |
And here is a simple way of creating your DataBunch
for language modelling or classification.
data_lm = TextLMDataBunch.from_csv(Path(path), 'texts.csv')
data_clas = TextClasDataBunch.from_csv(Path(path), 'texts.csv')
Behind the scenes, the previous functions will create a training, validation and maybe test TextDataset
which will then be transformed in a TokenizedDataset
then a NumericalizedDataset
. Those are all subclasses of TextBase
.
show_doc(TextBase, title_level=3)
class
TextBase
[source]
TextBase
(x
:ArgStar
,labels
:Collection
[Union
[int
,float
]]=None
,classes
:ArgStar
=None
,encode_classes
:bool
=True
) ::DatasetBase
Base class for all fastai datasets.
x
is an array representing the inputs (filenames, texts, tokens or ids) with certain labels
(default to all zeros if not specified). classes
can be passed and if encode_classes
, the labels
are changed from their class to the corresponding index.
show_doc(TextDataset, doc_string=False, title_level=3)
Create a TextBase
dataset of texts
with labels
belonging to classes
. The texts
are joined in the column dimension and if mark_fields
, field markers are added in-between. If encode_classes
the labels
are changed from their class to the corresponding index. If is_fnames
, the filenames in texts
are read to pull the texts.
show_doc(TextDataset.from_folder, doc_string=False)
from_folder
[source]
from_folder
(path
:PathOrStr
,classes
:ArgStar
=None
,valid_pct
:float
=0.0
,extensions
:StrList
=['.txt']
,mark_fields
:bool
=True
) →TextDataset
Create a TextDataset
by scanning the subfolders in path
for files with extensions
. Only keep the ones with labels in classes
if it's specified. If valid_pct
is not 0., returns two datasets randomly split. mark_fields
is passed to the initialization.
show_doc(TextDataset.from_one_folder, doc_string=False)
from_one_folder
[source]
from_one_folder
(path
:PathOrStr
,classes
:ArgStar
,extensions
:StrList
=['.txt']
,mark_fields
:bool
=True
) →TextDataset
Primarly used for the test set. Create a TextDataset
by scanning the subfolders in path
for files with extensions
. Labels all of them for classes[0]
. mark_fields
is passed to the initialization.
show_doc(TextDataset.from_df)
from_df
[source]
from_df
(df
:DataFrame
,classes
:ArgStar
=None
,n_labels
:int
=1
,txt_cols
:Collection
[Union
[int
,str
]]=None
,label_cols
:Collection
[Union
[int
,str
]]=None
,mark_fields
:bool
=True
) →TextDataset
Create a TextDataset
from the texts in a dataframe
show_doc(TextDataset.tokenize)
show_doc(TokenizedDataset, doc_string=False, title_level=3)
Create a TextBase
dataset of tokens
with labels
belonging to classes
. If encode_classes
the labels
are changed from their class to the corresponding index.
show_doc(TokenizedDataset.save)
show_doc(TokenizedDataset.numericalize)
show_doc(NumericalizedDataset, doc_string=False, title_level=3)
Create a TextBase
dataset of ids
with labels
belonging to classes
. vocab
contains the correspondance between ids an tokens. If encode_classes
the labels
are changed from their class to the corresponding index.
show_doc(NumericalizedDataset.get_text_item)
get_text_item
[source]
get_text_item
(idx
,sep
=' '
,max_len
:int
=None
)
Return the text in idx
, tokens separated by sep
and cutting at max_len
.
show_doc(NumericalizedDataset.save)
show_doc(NumericalizedDataset.load)
A language model is trained to guess what the next word is inside a flow of words. We don't feed it the different texts separately but concatenate them all together in a big array. To create the batches, we split this array into bs
chuncks of continuous texts. Note that in all NLP tasks, we use the pytoch convention of sequence length being the first dimension (and batch size being the second one) so we transpose that array so that we can read the chunks of texts in columns. Here is an example of batch from our imdb sample dataset.
path = untar_data(URLs.IMDB_SAMPLE)
data = TextLMDataBunch.from_csv(path, 'texts.csv')
x,y = next(iter(data.train_dl))
example = x[:20,:10].cpu()
texts = pd.DataFrame([data.train_ds.vocab.textify(l).split(' ') for l in example])
texts
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | |
---|---|---|---|---|---|---|---|---|---|---|
0 | xxfld | can | the | ! | - | young | xxunk | xxunk | him | his |
1 | 1 | xxunk | xxunk | firstly | watch | xxunk | this | and | ? | xxunk |
2 | a | one | corpse | , | the | is | stinks | have | no | debut |
3 | definite | 's | of | there | xxunk | sent | ! | considered | xxunk | with |
4 | no | perception | the | are | stealing | by | as | myself | for | this |
5 | . | of | dead | a | scene | his | everyone | as | taste | chilling |
6 | a | reality | hitchhiker | number | to | xxunk | knows | an | ) | , |
7 | xxunk | . | . | of | see | to | it | atheist | . | dark |
8 | no | in | \n\n | reviews | what | conclude | 's | throughout | the | , |
9 | . | this | xxunk | available | i | the | based | my | xxunk | and |
10 | this | case | awful | from | mean | xxunk | upon | adult | of | xxunk |
11 | movie | , | , | the | . | of | some | life | madness | made |
12 | is | we | but | film | \n\n | a | geico | . | ( | thriller |
13 | an | have | i | 's | the | recently | insurance | in | simply | about |
14 | absolute | a | really | german | fight | deceased | commercials | fact | xxunk | a |
15 | dud | well | did | xxup | scenes | widow | ; | when | being | widowed |
16 | . | - | n't | theatrical | were | , | what | it | enough | xxunk |
17 | \n\n | known | get | release | at | who | no | comes | to | ( |
18 | having | xxunk | into | - | once | died | one | to | be | paxton |
19 | been | xxunk | this | i | quite | on | knows | religion | a | himself |
Then, as suggested in this article from Stephen Merity et al., we don't use a fixed bptt
through the different batches but slightly change it from batch to batch.
iter_dl = iter(data.train_dl)
for _ in range(5):
x,y = next(iter_dl)
print(x.size())
torch.Size([64, 64]) torch.Size([69, 64]) torch.Size([71, 64]) torch.Size([71, 64]) torch.Size([76, 64])
This is all done internally when we use TextLMDataBunch
, by creating DataLoader
using the following class:
show_doc(LanguageModelLoader, doc_string=False)
class
LanguageModelLoader
[source]
LanguageModelLoader
(dataset
:TextDataset
,bs
:int
=64
,bptt
:int
=70
,backwards
:bool
=False
,shuffle
:bool
=False
,max_len
:int
=25
)
Takes the texts from dataset
and concatenate them all, then create a big array with bs
columns (transposed from the data source so that we read the texts in the columns). Spits batches with a size approximately equal to bptt
but changing at every batch. If backwards
is True, reverses the original text. If shuffle
is True, we shuffle the texts before concatenating them together at the start of each epoch. max_len
is the maximum amount we add to bptt
.
show_doc(LanguageModelLoader.batchify, doc_string=False)
batchify
[source]
batchify
(data
:ndarray
) →LongTensor
Called at the inialization to create the big array of text ids from the data
array.
show_doc(LanguageModelLoader.get_batch)
get_batch
[source]
get_batch
(i
:int
,seq_len
:int
) →Tuple
[LongTensor
,LongTensor
]
Create a batch at i
of a given seq_len
.
When preparing the data for a classifier, we keep the different texts separate, which poses another challenge for the creation of batches: since they don't all have the same length, we can't easily collate them together in batches. To help with this we use two different techniques:
PAD
token to get all the ones we picked to the same sizePAD
tokens), we regroup the texts by order of length. For the training set, we still add some randomness to avoid showing the same batches at every step of the training.Here is an example of batch with padding (the padding index is 1, and the padding is applied before the sentences start).
path = untar_data(URLs.IMDB_SAMPLE)
data = TextClasDataBunch.from_csv(path, 'texts.csv')
iter_dl = iter(data.train_dl)
_ = next(iter_dl)
x,y = next(iter_dl)
x[:20,-10:]
tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1, 1]], device='cuda:0')
This is all done internally when we use TextClasDataBunch
, by using the following classes:
show_doc(SortSampler, doc_string=False)
pytorch Sampler
to batchify the data_source
by order of length of the texts. Used for the validation and (if applicable) the test set.
show_doc(SortishSampler, doc_string=False)
pytorch Sampler
to batchify with size bs
the data_source
by order of length of the texts with a bit of randomness. Used for the training set.
show_doc(pad_collate, doc_string=False)
pad_collate
[source]
pad_collate
(samples
:BatchSamples
,pad_idx
:int
=1
,pad_first
:bool
=True
) →Tuple
[LongTensor
,LongTensor
]
Function used by the pytorch DataLoader
to collate the samples
in batches while adding padding with pad_idx
. If pad_first
is True, padding is applied at the beginning (before the sentence starts) otherwise it's applied at the end.
The data block API works for the text application too. Here are a few subclasses of the usual objects to implement the parts speficic to the text application.
show_doc(TextFileList, doc_string=False, title_level=3)
This subclasses InputList
just to change the defulat extentions in from_folder
to text extensions.
show_doc(TextFileList.from_folder)
from_folder
[source]
from_folder
(path
:PathOrStr
='.'
,extensions
:StrList
=['.txt']
,recurse
=True
) →ImageFileList
Get the list of files in path
that have a suffix in extensions
. recurse
determines if we search subfolders.
show_doc(TextSplitDatasets, doc_string=False, title_level=3)
class
TextSplitDatasets
[source]
TextSplitDatasets
(path
:PathOrStr
,train_ds
:Dataset
,valid_ds
:Dataset
,test_ds
:Optional
[Dataset
]=None
) ::SplitDatasets
A subclass of SplitDatasets
that implements methods specific to texts.
show_doc(TextSplitDatasets.tokenize)
show_doc(TextSplitDatasets.numericalize)
show_doc(TextSplitDatasets.databunch)
databunch
[source]
databunch
(cls_func
,path
:PathOrStr
=None
,kwargs
)
Create an cls_func
from self, path
will override self.path
, kwargs
are passed to cls_func.create
.
show_doc(TextMtd, alt_doc_string='`TextDataset` enum to keep track of what data needs to be processed (dataframe, csv, tokens, ids)')
Enum
= [DF, TOK, IDS]
TextDataset
enum to keep track of what data needs to be processed (dataframe, csv, tokens, ids)
show_doc(TextLMDataBunch.create)
create
[source]
create
(train_ds
,valid_ds
,test_ds
=None
,path
:PathOrStr
='.'
,kwargs
) →DataBunch
Create a TextDataBunch
in path
from the datasets
for language modelling.
show_doc(TextClasDataBunch.create)