Package: dlsia
Welcome to dlsia's documentation!dlsia (Deep Learning for Scientific Image Analysis) provides easy access to a number of segmentation and denoising
methods using convolution neural networks. The tools available are build for
microscopy and synchrotron-imaging/scattering data in mind, but can be used
elsewhere as well.The easiest way to start playing with the code is to install dlsia and
perform denoising/segmenting using custom neural networks in our tutorial
notebooks located in the dlsia/tutorials folder.Install dlsiaWe offer several methods for installation.pip: Python package installerWe are currently working on a stable release.From sourcedlsia may be directly downloaded and installed into your machine by
cloning the public repository into an empty directory using:$gitclonehttps://github.com/phzwart/dlsia.gitOnce cloned, move to the newly minted dlsia directory and install
dlsia using:$cddlsia$pipinstall-e.Further documentation & tutorial downloadFor more in-depth documentation and end-to-end training workflows, please
visit ourreadthedocspage
for more support. To download only the tutorials in a new folder, use the
following terminal input for a sparse git checkout:mkdir dlsiaTutorialscd dlsiaTutorialsgit initgit config core.sparseCheckout truegit remote add -f origin https://github.com/phzwart/dlsia.gitecho "dlsia/tutorials/*" > .git/info/sparse-checkoutgit checkout mainGetting startedWe start with some basic imports - we import a network and some training
scripts:fromdlsia.core.networksimportmsdnetfromdlsia.coreimporttrain_scriptsMixed-Scale dense networks (MSDNet)A plain 2d mixed-scale dense network is constructed as follows:fromdlsia.core.networksimportmsdnetmsdnet_model=msdnet.MixedScaleDenseNetwork(in_channels=1,out_channels=1,num_layers=20,max_dilation=10)while 3d network types for volumetric images can be built passing in equivalent
kernels for 3 dimensions:importtorchfromtorchimportnnmsdnet3d_model=msdnet.MixedScaleDenseNetwork(in_channels=1,out_channels=1,num_layers=20,max_dilation=10,normalization=nn.BatchNorm3d,convolution=nn.Conv3d)Note that each instance of a convolution operator is followed by ReLU
activation and batch normalization. To turn these off, simply pass in the
parametersactivation=None,normalization=NoneSparse mixed-scale dense network (SMSNet)The dlsia suite also provides ways and means to build random, sparse mixed
scale networks. SMSNets contain more sparsely connected nodes than a standard
MSDNet and are useful to alleviate overfitting and multi-network aggregation.
Controlling sparsity is possible, see full documentation for more details.fromdlsia.core.networksimportsmsnetsmsnet_model=smsnet.random_SMS_network(in_channels=1,out_channels=1,layers=20,dilation_choices=[1,2,4,8],hidden_out_channels=[1,2,3])Tunable U-NetsAn alternative network choice is to construct a UNet. Classic U-Nets can easily
explode in the number of parameters it requires; here we make it a bit easier
to tune desired architecture-governing parameters:fromdlsia.core.networksimporttunettunet_model=tunet.TUNet(image_shape=(64,128),in_channels=1,out_channels=4,base_channels=4,depth=3,growth_rate=1.5)TrainingData preparationTo prep data for training, we make liberal use of PyTorch DataLoader
classes. This allows for easy handling of data in the training process and
automates the iterative loading of batch sizes.In the example below, we take pair two numpy arrays of shape[num_images,  num_channels, x_size, y_size]consisting of training images and masks, convert
them into PyTorch tensors, then initialize the DataLoader class.importtorchfromtorch.utils.dataimportTensorDataset,DataLoadertrain_data=TensorDataset(torch.Tensor(training_imgs),torch.Tensor(training_masks))train_loader_params={'batch_size':20,'shuffle':True}train_loader=DataLoader(train_data,**train_loader_params)Training loopOnce your DataLoaders are constructed, the training of these networks is as
simple as defining a torch.nn optimizer, and calling the training script:fromtorchimportoptim,nnfromdlsia.coreimporthelpers,train_scriptscriterion=nn.CrossEntropyLoss()# For segmentingoptimizer=optim.Adam(tunet_model.parameters(),lr=1e-2)device=helpers.get_device()tunet_model=tunet_model.to(device)tunet_model,results=train_scripts.train_segmentation(net=tunet_model,trainloader=train_loader,validationloader=test_loader,NUM_EPOCHS=epochs,criterion=criterion,optimizer=optimizer,device=device,show=1)The output of the training scripts is the trained network and a dictionary with
training losses and evaluation metrics. You can view them as follows:fromdlsia.viz_toolsimportplotsfig=plots.plot_training_results_segmentation(results)fig.show()Saving and loading modelsEach dlsia network library contains submodules for saving trained
networks and loading them from file. Using the conventional PyTorch.ptmodel file extension, the TUNet above may be saved withsavepath='this_tunet.pt'tunet_model.save_network_parameters(savepath)and reloaded for future use withcopy_of_tunet=tunet.TUNetwork_from_file(savepath)License and Legal StuffThis software has been developed from funds that originate from the US tax
payer and is free for academics. Please have a look at the license agreement
for more details. Commercial usage will require some extra steps. Please
contactipo@lbl.govfor more details.Final ThoughtsThis documentation is far from complete, but have some notebooks as part of the codebase, which could provide a good
entry point.More to come!