API

py4pm.chemutilities module

py4pm.chemutilities.format_ions(text)

py4pm.chemutilities.get_OC_from_OC_star_and_organic(df)

Re-compute OC taking into account the organic species

OC = OC* + sum(eqC_sp)

py4pm.chemutilities.get_sample_where(sites=None, date_min=None, date_max=None, species=None, min_sample=None, particle_size=None, con=None)

Get dataframe that meet conditions

Sites

TODO

Date_min

TODO

Date_max

TODO

Min_sample

int, minimum samples size

Particle_size

Con

sqlite3 connection

Returns

TODO

py4pm.chemutilities.get_site_typology()

py4pm.chemutilities.get_sourceColor(source=None)

Return the hexadecimal color of the source(s)

If no option, then return the whole dictionary

sourcestr

The name of the source

py4pm.chemutilities.get_sourcesCategories(profiles)

Get the sources category according to the sources name.

Ex. Aged sea salt → Aged_sea_salt

Profiles

list

Returns

list

class py4pm.chemutilities.plot

Bases: object

mainCompentOfPM(dateStart, dateEnd, seasonal=False, savefig=False, savedir=None)

Plot a stacked bar plot of the different constitutant of the PM

Parameters

• station (str) – name of the station

• dateEnd (dateStart,) – starting and ending date

• seasonal (boolean, default False) – Either to make separate graph per season

• savefig (boolean, default False) – Save the fig in png and pdf

• savedir (str path, default None) – Where to save the figures

what_do_we_have(date_min=None, date_max=None, species=None, min_sample=None, particle_size=None, con=None)

TODO: Docstring for what_do_we_have.

Sites

TODO

Date_min

TODO

Date_max

TODO

Species

TODO

Min_sample

TODO

Con

TODO

Returns

TODO

py4pm.chemutilities.replace_QL(dftmp, species=None, conn=None)

Replace the -1 and -2 in the dataframe by the appropriate DL and QL values

The change are done inplace.

Dftmp

pandas DataFrame

py4pm.dateutilities module

py4pm.dateutilities.add_season(df, month=True, month_to_season=None)

Add a season column to the DataFrame df.

Parameters

• df (Pandas DataFrame.) – The DataFrame to work with.

• month (add month number, default True) –

Returns

dfnew

Return type

a new pandas DataFrame with a ‘season’ columns.

py4pm.dateutilities.format_xaxis_timeseries(ax)

Format the x-axis timeseries with minortick = month and majortick=year

Ax

the ax to format

py4pm.deltaTool module

class py4pm.deltaTool.LegendTitle(text_props=None)

Bases: object

legend_artist(legend, orig_handle, fontsize, handlebox)

py4pm.deltaTool.compute_PD(df1, df2, factor1=None, factor2=None, isRelativeMass=True)

Compute the PD of the factors factor1 and factor2 in the profile df1`and `df2.

py4pm.deltaTool.compute_SID(df1, df2, factor1=None, factor2=None, isRelativeMass=True)

Compute the SID of the factors factor1 and factor2 in the profile df1`and `df2.

py4pm.deltaTool.get_all_SID_PD(PMF_profile, stations, factor2=None, isRelativeMass=False)

Compute the SID and PD for all profiles in PMF_profile for the stations stations.

py4pm.deltaTool.get_profile_from_PMF(pmfs)

Get a profile matrix from a list of PMF object

Pmfs

TODO

Returns

TODO

py4pm.deltaTool.plot_all_stations_similarity_by_source(PMF_profile)

Plot all individual pair of profile for each common source.

py4pm.deltaTool.plot_deltatool_pretty(ax)

Format the given ax to conform with the “deltatool-like” visualization.

py4pm.deltaTool.plot_relativeMass(PMF_profile, source='Biomass burning', isRelativeMass=True, totalVar='PM10', naxe=1, site_typologie=None)

py4pm.deltaTool.plot_similarity_profile(SID, PD, err='ci', plotAll=False)

Plot a point in the SID/PD space (+/-err) for all profile in SID and PD.

SID : DataFrame with index (factor, station) and column (station) : the SID matrix PD : DataFrame with index (factor, station) and column (station) : the PD matrix err : “ci” or “sd”, the type of error for xerr and yerr. plotAll: boolean. Either or not plot each pair of profile.

Returns

• similarity (pd.DataFrame) – columns: x, y, xerr, yerr, n index: profiles

• handles_labels (tuple of handles and labels) – legend of the plot

py4pm.deltaTool.plot_similarityplot(PMF_profile, station1, station2, source1, source2=None, SID=None, PD=None, isRelativeMass=False, ax=None, plot_kw={})

Plot the distance in the SID/PD space of 2 profiles for 2 stations.

py4pm.deltaTool.save4deltaTool(contrib, profile)

py4pm.deltaTool.to_relativeMass(df, totalVar='PM10')

Normalize the profile df to the relative mass with regard to the totalVar (=PM10 or PM2.5).

py4pm.pmfutilities module

class py4pm.pmfutilities.CachedAccessor(name, accessor)

Bases: object

Custom property-like object (descriptor) for caching accessors.

Parameters

• name (str) – The namespace this will be accessed under, e.g. df.foo

• accessor (cls) – The class with the extension methods. The class’ __init__ method should expect one of a Series, DataFrame or Index as the single argument data

class py4pm.pmfutilities.PMF(site, BDIR, program=None)

Bases: object

PMF are able to read file from US EPA PMF5.0 software output (in xlsx format), then parse them in a more handy format (pandas DataFrame). Several plot utilities are also available.

get_seasonal_contribution(specie=None, annual=True, normalize=True, constrained=True)

Get a dataframe of seasonal contribution

Parameters

• specie (default None) –

• annual (default True) –

• normalize (default True) –

• constrained (default True) –

Returns

df

Return type

seasonal contribution

get_total_specie_sum(constrained=True)

Return the total specie sum profiles in %

Parameters

constrained (boolean, default True) – use the constrained run or not

Returns

df – The normalized species sum per profiles

Return type

pd.DataFrame

plot

alias of PlotterAccessor

print_uncertainties_summary(constrained=True, profiles=None, species=None)

Get the uncertainties given by BS, BS-DISP and DISP for the given profiles and species

Parameters

• constrained (boolean, True) – Use the constrained run (False for the base run)

• profiles (list of str) – list of profiles, default all profiles

• species (list of str) – list of species, default all species

Returns

df – BS, DISP and BS-DISP ranges

Return type

pd.DataFrame

read

alias of ReaderAccessor

recompute_new_species(specie)

Recompute a specie given the other species. For instance, recompute OC from OC* and a list of organic species.

It modify inplace both dfprofile_b and dfprofile_c, and update self.species.

Parameters

specie (str in ["OC",]) –

rename_profile_to_profile_category()

Rename the factor profile name to match the category

replace_totalVar(newTotalVar)

replace the total var to all dataframe

NewTotalVar

TODO

Returns

TODO

to_cubic_meter(constrained=True, specie=None, profiles=None)

Convert the contribution in cubic meter for the given specie

Parameters

• specie (str, the specie, default totalVar) –

• profiles (list of profile, default all profiles) –

Returns

df

Return type

dataframe

to_relative_mass(constrained=True, species=None, profiles=None)

Compute the factor profile relative mass (i.e. each species divided by the totalVar mass)

Parameters

• constrained (TODO) –

• species (TODO) –

• profiles (TODO) –

class py4pm.pmfutilities.PlotterAccessor(data)

Bases: object

Accessor class for the PMF class with all plotter methods.

plot_all_profiles(constrained=True, profiles=None, specie=None, BS=True, DISP=True, BSDISP=False, plot_save=False, savedir=None)

TODO: Docstring for plot_all_profiles.

Parameters

• constrained (Boolean, default True) – Either to use the constrained run or the base one

• profiles (list of string) – Profiles to plot

• species –

• DISP, BSDISP} ({BS,) – Use them as error estimation

• plot_save (boolean, default False) – Either or not saving the plot

• savedir (str) – Path to save the plot

plot_contrib(dfBS=None, dfDISP=None, dfcontrib=None, profiles=None, specie=None, constrained=True, plot_save=False, savedir=None, BS=True, DISP=True, BSDISP=False, new_figure=True, **kwargs)

Plot temporal contribution in µg/m3.

Parameters

• df (pd.DataFrame, default self.dfBS_profile_c) – DataFrame with multiindex [species, profile] and an arbitrary number of column.

• dfcontrib (pd.DataFrame, default self.dfcontrib_c) – Profile as column and specie as index.

• profiles (list of string, default self.profiles) – profile to plot (one figure per profile)

• specie (string, default totalVar.) – specie to plot (y-axis)

• plot_save (boolean, default False) – Save the graph in savedir.

• savedir (string) – directory to save the plot

plot_per_microgramm(df=None, constrained=True, profiles=None, species=None, plot_save=False, savedir=None)

Plot profiles in concentration unique (µg/m3).

Parameters

• df (DataFrame with multiindex [species, profile] and an arbitrary) – number of column. Default to dfBS_profile_c.

• constrained (Boolean, either to use the constrained run or the base run) –

• profiles (list of str, profile to plot (one figure per profile)) –

• species (list of str, specie to plot (x-axis)) –

• plot_save (boolean, default False. Save the graph in savedir.) –

• savedir (string, directory to save the plot.) –

plot_seasonal_contribution(constrained=True, dfcontrib=None, dfprofiles=None, profiles=None, specie=None, plot_save=False, savedir=None, annual=True, normalize=True, ax=None, barplot_kwarg={})

Plot the relative contribution of the profiles.

Parameters

• dfcontrib (DataFrame with contribution as column and date as index.) –

• dfprofiles (DataFrame with profile as column and specie as index.) –

• profiles (list, profile to plot (one figure per profile)) –

• specie (string, default totalVar. specie to plot) –

• plot_save (boolean, default False. Save the graph in savedir.) –

• savedir (string, directory to save the plot.) –

• annual (plot annual contribution) –

• normalize (plot relative contribution or absolute contribution.) –

Returns

df

Return type

DataFrame

plot_stacked_contribution(constrained=True, order=None, plot_kwargs=None)

Plot a stacked plot for the contribution

Parameters

• constrained (TODO) –

• order (TODO) –

• plot_kwargs (TODO) –

plot_stacked_profiles(constrained=True)

plot the repartition of the species among the profiles, normalized to 100%

Parameters

constrained (boolean, default True) – use the constrained run or not

Returns

ax

Return type

the axe

plot_totalspeciesum(df=None, profiles=None, species=None, constrained=True, plot_save=False, savedir=None, **kwargs)

Plot profiles in percentage of total specie sum (%).

Parameters

• df (DataFrame with multiindex [species, profile] and an arbitrary) – number of column. Default to dfBS_profile_c.

• profiles (list, profile to plot (one figure per profile)) –

• species (list, specie to plot (x-axis)) –

• plot_save (boolean, default False. Save the graph in savedir.) –

• savedir (string, directory to save the plot.) –

class py4pm.pmfutilities.ReaderAccessor(data)

Bases: object

Accessor class for the PMF class with all reader methods.

read_base_bootstrap()

Read the “base” bootstrap result from the file: ‘_boot.xlsx’ and add :

• self.dfBS_profile_b: all mapped profile

• self.dfbootstrap_mapping_b: table of mapped profiles

read_base_contributions()

Read the “base” contributions result from the file: ‘_base.xlsx’, sheet “Contributions”, and add :

• self.dfcontrib_b: base factors contribution

read_base_profiles()

Read the “base” profiles result from the file: ‘_base.xlsx’, sheet “Profiles”, and add :

• self.dfprofiles_b: constrained factors profile

read_base_uncertainties_summary()

Read the _BaseErrorEstimationSummary.xlsx file and add:

• self.df_uncertainties_summary_b : uncertainties from BS, DISP and BS-DISP

read_constrained_bootstrap()

Read the “base” bootstrap result from the file: ‘_Gcon_profile_boot.xlsx’ and add :

• self.dfBS_profile_c: all mapped profile

• self.dfbootstrap_mapping_c: table of mapped profiles

read_constrained_contributions()

Read the “constrained” contributions result from the file: ‘_Constrained.xlsx’, sheet “Contributions”, and add :

• self.dfcontrib_c: constrained factors contribution

read_constrained_profiles()

Read the “constrained” profiles result from the file: ‘_Constrained.xlsx’, sheet “Profiles”, and add :

• self.dfprofiles_c: constrained factors profile

read_constrained_uncertainties_summary()

Read the _ConstrainedErrorEstimationSummary.xlsx file and add :

• self.df_uncertainties_summary_b : uncertainties from BS, DISP and BS-DISP

read_metadata()

Get profiles, species and co

It add a totalVariable (by default one of “PM10”, “PM2.5”, “PMrecons” or “PM10recons”, “PM10rec”). Otherwise, try to guess (variable with “PM” on its name).