Package: pyraug
DocumentationPyraugThis library provides a way to perform Data Augmentation using Variational Autoencoders in a
reliable way even in challenging contexts such as high dimensional and low sample size
data.InstallationTo install the library frompypi.orgrun the following usingpip$pipinstallpyraugor alternatively you can clone the github repo to access to tests, tutorials and scripts.$gitclonehttps://github.com/clementchadebec/pyraug.gitand install the library$cdpyraug
$pipinstall.Augmenting your DataIn Pyraug, a typical augmentation process is divided into 2 distinct parts:Train a model using the Pyraug'sTrainingPipelineor using the providedscripts/training.pyscriptGenerate new data from a trained model using Pyraug'sGenerationPipelineor using the providedscripts/generation.pyscriptThere exist two ways to augment your data pretty straightforwardly using Pyraug's built-in functions.Using Pyraug's PipelinesPyraug provides two pipelines that may be used to either train a model on your own data or generate new data with a pretrained model.note: These pipelines are independent of the choice of the model and sampler. Hence, they can be used even if you want to access to more advanced features such as defining your own autoencoding architecture.Launching a model trainingTo launch a model training, you only need to call aTrainingPipelineinstance.
In its most basic version theTrainingPipelinecan be built without any arguments.
This will by default train aRHVAEmodel with default autoencoding architecture and parameters.>>>frompyraug.pipelinesimportTrainingPipeline>>>pipeline=TrainingPipeline()>>>pipeline(train_data=dataset_to_augment)wheredataset_to_augmentis either anumpy.ndarray,torch.Tensoror a path to a folder where each file is a data (handled data formats are.pt,.nii,.nii.gz,.bmp,.jpg,.jpeg,.png).More generally, you can instantiate your own model and train it with theTrainingPipeline. For instance, if you want to instantiate a basicRHVAErun:>>>frompyraug.modelsimportRHVAE>>>frompyraug.models.rhvaeimportRHVAEConfig>>>model_config=RHVAEConfig(...input_dim=int(intput_dim)...)# input_dim is the shape of a flatten input data...# needed if you did not provide your own architectures>>>model=RHVAE(model_config)In case you instantiate yourself a model as shown above and you did not provide all the network architectures (encoder, decoder & metric if applicable), theModelConfiginstance will expect you to provide the input dimension of your data which equals ton_channels x height x width x .... Pyraug's VAE models' networks indeed default to Multi Layer Perceptron neural networks which automatically adapt to the input data shape.note: In case you have different size of data, Pyraug will reshape it to the minimum sizemin_n_channels x min_height x min_width x ...Then theTrainingPipelinecan be launched by running:>>>frompyraug.pipelinesimportTrainingPipeline>>>pipe=TrainingPipeline(model=model)>>>pipe(train_data=dataset_to_augment)At the end of training, the model weightsmodels.ptand model configmodel_config.jsonfile
will be saved in a folderoutputs/my_model/training_YYYY-MM-DD_hh-mm-ss/final_model.Important: For high dimensional data we advice you to provide you own network architectures and potentially adapt the training and model parameters seedocumentationfor more details.Launching data generationTo launch the data generation process from a trained model, run the following.>>>frompyraug.pipelinesimportGenerationPipeline>>>frompyraug.modelsimportRHVAE>>>model=RHVAE.load_from_folder('path/to/your/trained/model')# reload the model>>>pipe=GenerationPipeline(model=model)# define pipeline>>>pipe(samples_number=10)# This will generate 10 data pointsThe generated data is in.ptfiles indummy_output_dir/generation_YYYY-MM-DD_hh-mm-ss. By default, it stores batch data of a maximum of 500 samples.Retrieve generated dataGenerated data can then be loaded pretty easily by running>>>importtorch>>>data=torch.load('path/to/generated_data.pt')Using the provided scriptsPyraug provides two scripts allowing you to augment your data directly with commandlines.note: To access to the predefined scripts you should first clone the Pyraug's repository.
The following scripts are located inscripts folder. For the time being, onlyRHVAEmodel training and generation is handled by the provided scripts. Models will be added as they are implemented inpyraug.modelsLaunching a model training:To launch a model training, run$ python scripts/training.py --path_to_train_data "path/to/your/data/folder"The data must be located inpath/to/your/data/folderwhere each input data is a file. Handled image types are.pt,.nii,.nii.gz,.bmp,.jpg,.jpeg,.png. Depending on the usage, other types will be progressively added.At the end of training, the model weightsmodels.ptand model configmodel_config.jsonfile
will be saved in a folderoutputs/my_model_from_script/training_YYYY-MM-DD_hh-mm-ss/final_model.Launching data generationThen, to launch the data generation process from a trained model, you only need to run$ python scripts/generation.py --num_samples 10 --path_to_model_folder 'path/to/your/trained/model/folder'The generated data is stored in several.ptfiles inoutputs/my_generated_data_from_script/generation_YYYY-MM-DD_hh_mm_ss. By default, it stores batch data of 500 samples.Important:  In the simplest configuration, default configurations are used in the scripts. You can easily override as explained indocumentation. See tutorials for a more in depth example.Retrieve generated dataGenerated data can then be loaded pretty easily by running>>>importtorch>>>data=torch.load('path/to/generated_data.pt')Getting your hands on the codeTo help you to understand the way Pyraug works and how you can augment your data with this library we also
provide tutorials that can be found inexamples folder:getting_started.ipynbexplains you how to train a model and generate new data using Pyraug's Pipelinesplaying_with_configs.ipynbshows you how to amend the predefined configuration to adapt them to your datamaking_your_own_autoencoder.ipynbshows you how to pass your own networks to the models implemented in PyraugDealing with issuesIf you are experiencing any issues while running the code or request new features pleaseopen an issue on githubCitingIf you use this library please consider citing us:@article{chadebec_data_2021,title={Data {Augmentation} in {High} {Dimensional} {Low} {Sample} {Size} {Setting} {Using} a {Geometry}-{Based} {Variational} {Autoencoder}},copyright={All rights reserved},journal={arXiv preprint arXiv:2105.00026},arxiv={2105.00026},author={Chadebec, Clément and Thibeau-Sutre, Elina and Burgos, Ninon and Allassonnière, Stéphanie},year={2021}}CreditsLogo:SaulLu