# settings

[settings](../api/settings.md#starsim_data.settings)

Package-level settings.

Everything here is optional: the bundled data (tier 0) needs no configuration at all. These settings exist for the parts that touch the filesystem or the network - the download cache used by [fetch()](../api/fetching.md#starsim_data.fetching.fetch) and [download()](../api/downloading.md#starsim_data.downloading.download) - and for the type of dataframe returned.

Settings are read from the environment at import time but *acted on* lazily, so nothing here creates a directory, opens a file or emits a warning merely because the package was imported. The cache directory is not created until something is actually cached.

``` python
import starsim_data as ssd
ssd.options.cache_dir = '/fast/scratch/wpp'   # or set STARSIM_DATA_CACHE_DIR
ssd.options(verbose=False)                     # quieten downloads
ssd.options.pandas = True                      # plain pandas DataFrames, not Sciris ones
with ssd.options.context(cache_dir='/tmp/x'):  # temporarily
    ssd.download('kenya', which='deaths')
```

## Functions

| Name | Description |
|----|----|
| [dataframe](#starsim_data.settings.dataframe) | Make the dataframe this package returns: an `sc.dataframe`, or a `pd.DataFrame` if `options.pandas` is set. |

### dataframe

``` python
settings.dataframe(*args, **kwargs)
```

Make the dataframe this package returns: an `sc.dataframe`, or a `pd.DataFrame` if `options.pandas` is set.

Takes the same arguments as `pd.DataFrame`. Every function that builds a dataframe for the caller goes through this, so the option applies everywhere.
