Pandas accessors

Pandas-OpenSCM also provides pandas accessors. For details of the implementation of this pattern, see pandas' docs.

The accessors must be registered before they can be used (we do this to avoid imports of any of our modules having side effects, which is a pattern we have had bad experiences with in the past). This is done with register_pandas_accessors,

By default, the accessors are provided under the "openscm" namespace. However, the namespace can be customised when using register_pandas_accessors, should you wish to use a different namespace for the accessor.

For the avoidance of doubt, in order to register/activate the accessors, you will need to run something like:

from pandas_openscm.accessors import register_pandas_accessors

# The `pd.DataFrame.openscm` and `pd.Series.openscm` namespaces
# will not be available at this point.

# Register the accessors
register_pandas_accessors()

# The `pd.DataFrame.openscm`, `pd.Series.openscm` and `pd.Index.openscm` namespaces
# will now be available.
# I.e. you could now do something like
df = pd.DataFrame(
    [
        [1.1, 0.8, 1.2],
        [2.1, np.nan, 8.4],
    ],
    columns=[2010.0, 2015.0, 2025.0],
    index=pd.MultiIndex.from_tuples(
        [
            ("sa", "v2", "W"),
            ("sb", "v2", "W"),
        ],
        names=["scenario", "variable", "unit"],
    ),
)

# Use pandas-openscm's functionality via the registered accessors.
df.openscm.to_long_data()

# If you want to register the accessors under a custom namespace instead,
# use something like the below instead
register_pandas_accessors(namespace="my_custom_namespace")

# Doing it this way will make the custom namespace available under
# `pd.DataFrame.my_custom_namespace`,
# `pd.Series.my_custom_namespace`
# and `pd.Index.my_custom_namespace`.
df.my_custom_namespace.to_long_data()

The full accessor APIs are documented at pandas_openscm.accessors.dataframe.PandasDataFrameOpenSCMAccessor, pandas_openscm.accessors.series.PandasSeriesOpenSCMAccessor and pandas_openscm.accessors.index.PandasIndexOpenSCMAccessor.