Package: xblobs
xblobsPython tool to detect and analyse coherent structures in turbulence, powered by xarray.The algorithm has been developed originally to detect and track coherent structures (blobs) in plasma turbulence simulations but it can be applied on any 2D xarray Dataset with a cartesian grid and constant spacingdx,dyanddt. An example is shown below:RequirementsPython >= 3.5xarray >= 0.11.2scipy >= 1.2.0dask-image >= 0.2.0numpy >= 1.14InstallationDev install:git clone https://github.com/gregordecristoforo/xblobs.git
cd xblobs
pip install -e .UsageThe algorithm is based on the threshold method, i.e. all structures exceeding a defined threshold are labeled as blobs. In order to track blobs over time they have to spatially overlap in two consecutive frames.Applyingfind_blobsfunction on xarray dataset returns the dataset with a new variable calledblob_labels. The number of blobs is added as an attribute toblob_labelsasnumber_of_blobs. The parameters of single blobs can then be calculated with theBlobclass.xstormThe default implementation is done for a xstorm dataset.fromxblobsimportBlobfromxblobsimportfind_blobsfromxstormimportopen_stormdatasetds=open_stormdataset(inputfilepath='./BOUT.inp')ds=find_blobs(da=ds,scale_threshold='absolute_value',threshold=5e18,region=0.0,background='flat')blob1=Blob(ds,1)# call blob methods you are interested inprint(blob1.lifetime())#etcxboutForBOUT++ simulationsusingxboutone has to specify the dimensions in addition.fromxblobsimportBlobfromxblobsimportfind_blobsfromxboutimportopen_boutdatasetds=open_boutdataset()ds=find_blobs(da=ds,scale_threshold='absolute_value',threshold=1.3,region=0.0,background='flat',n_var='n',t_dim='t',rad_dim='x',pol_dim='z')blob1=Blob(ds,1,n_var='n',t_dim='t',rad_dim='x',pol_dim='z')generic xarray datasetFor a generic xarray dataset adjust the dimensions to your needs, for example:fromxblobsimportBlobfromxblobsimportfind_blobsds=load_your_dataset()ds=find_blobs(da=ds,scale_threshold='absolute_value',threshold=1.3,region=0.0,background='flat',n_var='density',t_dim='time',rad_dim='radial',pol_dim='poloidal')blob1=Blob(ds,1,n_var='density',t_dim='time',rad_dim='radial',pol_dim='poloidal')Input parametersfind_blobs()da: xbout Datasetthreshold: threshold value expressed in terms of the chosen scale_thresholdscale_threshold: following methods implementedabsolute_value: threshold is scalar valueprofile: threshold is time- and poloidal-average profilestd: threshold is standard deviation over all three dimensionsstd_poloidal: threshold is standard deviation over poloidal dimensionstd_time: threshold is standard deviation over time dimensionregion: blobs are detected in the region with radial indices greater thanregionbackground: background that is subtracted. Options:profile: time- and poloidal-averaged backgroundflat: no background subtractedn_var: xarray variable used for blob trackingt_dim: xarray dimension for timerad_dim: xarray dimension for radial dimensionpol_dim: xarray dimension for poloidal dimensionBlob()variable: xbout Dataset containing blob_labelsid: integer between 0 and number of detected blobs0: refers to the background1-n: detected blobsother parameters equivalent tofind_blobsBlob methodsthe following blob parameters are implemented:t_init: time when blob is detectedlifetime: lifetime of blobcom: center of mass, over timevelocity: absolute velocity of centre of mass of blob, over timevelocity_x: radial velocity of centre of mass of blob, over timevelocity_y: poloidal velocity of centre of mass of blob, over timeamplitude: maximum of the signal within the blob above background, over timemax_amplitude: maximum of the signal within the blob above backgroundmass: integral of signal in area where background is exceeded, over timeaverage_mass: average blob masssize: integral of area above background, over timeother blob parameters are straightforward to implementParallelizationBlob detection is parallelised across any number of dimensions bydask-image.ContactIf you have questions, suggestions or other comments you can contact me undergregor.decristoforo@uit.no