Sciris

--------------------------

Changes to odict and objdict
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
. Major improvements to ``sc.odict()`` performance: key lookup (e.g. ``my_odict['key']``) is ~30% faster, nearly identical to native ``dict()``; integer lookup (``my_odict[3]``) is now 10-100x faster. This was achieved by caching the keys rather than looking them up each time.
. Allow dicts with integer keys to be converted to odicts via the ``makefrom()`` method, e.g. ``sc.odict.makefrom({0:'foo', 1:'bar'})``. If an odict has integer keys, then these take precedence.
. Added ``force`` option to ``objdict.setattribute()`` to allow attributes to be set even if they already exist. Added ``objdict.delattribute()`` to delete attributes.
. Removed the ``to_OD()`` method (since dicts preserve order, ``dict(my_odict)`` is now much more common).
. Made ``sc.dictobj()`` a subclass of ``dict``, so ``isinstance(my_dictobj, dict)`` is now ``True``.
. Added ``sc.ddict()`` as an alias to ``collections.defaultdict()``.

Plotting
~~~~~~~~
. Updated ``sc.commaticks()`` to use a more thoughtful number of significant figures.

Printing
~~~~~~~~
. Fixed a bug in ``sc.heading()`` that printed an extraneous ``None``. Also allows more flexibility in spaces before/after the heading.
. Fixed a bug in ``sc.fonts()`` that prevented using a ``Path`` object. Also added a ``rebuild`` argument that rebuilds the Matplotlib font cache (useful when added fonts don't show up).
. Updated ``sc.colorize()`` to wrap the ``ansicolors`` module, allowing more flexible inputs such as ``sc.colorize('cat', fg='orange')``.
. Added ``output`` argument to ``sc.pp()`` which acts as an alias to ``pprint.pformat()``.

Other changes
~~~~~~~~~~~~~
. Removed the ``pkg_resources`` import, which roughly halves Sciris import time (from 0.3 s to 0.15 s, assuming ``matplotlib.pyplot`` is already imported).
. Added option to search the source code in ``sc.help()``.
. Improved the implementations of ``sc.smooth()``, ``sc.gauss1d()``, and ``sc.gauss2d()`` to handle different object types and edge cases.
. Fixed requirements for ``minimal`` install option.
. Removed the ``openpyexcel`` dependency (falling back to the nearly identical ``openpyxl``).

--------------------------

This version contains a number of major improvements, including:

. **Better date plotting**: ``sc.dateformatter()`` has been revamped to provide compact and intuitive date plotting.
. **Better smoothing**: The new functions ``sc.convolve()``/``sc.gauss1d()``/``sc.gauss2d()``, and the updated ``sc.smooth()``, provide new options for smoothing data.
. **Simpler fonts**: ``sc.fonts()`` can both list fonts and add new ones.
. **Simpler options**: Need a bigger font? Just do ``sc.options(fontsize=18)``.

New functions and methods
~~~~~~~~~~~~~~~~~~~~~~~~~
. Added a settings module to quickly set both Sciris and Matplotlib options; e.g. ``sc.options(dpi=150)`` is a shortcut for ``pl.rc('figure', dpi=150)``, while e.g. ``sc.options(aspath=True)`` will globally set Sciris functions to return ``Path`` objects instead of strings.
. Added ``sc.timer()`` as a simpler and more flexible way of accessing ``sc.tic()``/``sc.toc()`` and ``sc.Timer()``.
. Added ``sc.convolve()``, a simple fix to ``np.convolve()`` that avoids edge effects (see update to ``sc.smooth()`` below).
. Added ``sc.gauss1d()`` and ``sc.gauss2d()`` as additional (high-performance) smoothing functions.
. Added ``sc.fonts()``, to easily list or add fonts for use in plotting.
. Added ``sc.dictobj()``, the inverse of ``sc.objdict()`` -- an object that acts like a dictionary (instead of a dictionary that acts like an object). Compared to ``sc.objdict()``, ``sc.dictobj()`` is lighter-weight and slightly faster but less powerful.
. Added ``sc.swapdict()``, a shortcut for swapping the keys and values of a dictionary.
. Added ``sc.loadobj2or3()``, for legacy support for loading Python 2 pickles. (Support had been removed in version 1.1.1.)
. Added ``sc.help()``, to quickly allow searching of Sciris' docstrings.

Bugfixes
~~~~~~~~
. Fixed edge effects when using ``sc.smooth()`` by using ``sc.convolve()`` instead of ``np.convolve()``.
. Fixed a bug with checking types when saving files via ``sc.save()``. (Thanks to Rowan Martin-Hughes.)
. Fixed a bug with ``output=True`` not being passed correctly for ``sc.heading()``.

Improvements
~~~~~~~~~~~~
. ``sc.dateformatter()`` is now an interface to a new formatter for plotting dates (``ScirisDateFormatter``). This formatter is optimized for aesthetics, combining the best aspects of Matplotlib's and Plotly's date formatters. (Thanks to Daniel Klein.)
. ``sc.daterange()`` now accepts an ``interval`` argument.
. ``sc.datedelta()`` can now return the actual delta rather than just the date.
. ``sc.toc()`` has more flexible printing options.
. ``sc.Spreadsheet()`` now keeps a copy of the opened workbook, so there is no need to reopen it for every operation.
. ``sc.commaticks()`` can now use non-comma separators.
. Many other functions had small usability improvements, e.g. input arguments are more consistent and more flexible.

Housekeeping
~~~~~~~~~~~~
. ``xlrd`` has been removed as a dependency; ``openpyexcel`` is used instead, with simple spreadsheet loading now done by ``pandas``.
. Source files were refactored and split into smaller pieces (e.g. ``sc_utils.py`` was split into ``sc_utils.py``, ``sc_printing.py``, ``sc_datetime.py``, ``sc_nested.py``).

Regression information
~~~~~~~~~~~~~~~~~~~~~~
. To restore previous spreadsheet loading behavior, use ``sc.loadspreadsheet(..., method='xlrd')``.
. To use previous smoothing (with edge effects), use ``sc.smooth(..., legacy=True)``

--------------------------
. Fixed a bug with ``sc.asd()`` failing for ``verbose > 1``. (Thanks to Nick Scott and Romesh Abeysuriya.)
. Added ``sc.rolling()`` as a shortcut to pandas' rolling average function.
. Added a ``die`` argument to ``sc.findfirst()`` and ``sc.findlast()``, to allow returning no indices without error.

--------------------------

New functions and methods
~~~~~~~~~~~~~~~~~~~~~~~~~
. A new class, ``sc.autolist()``, is available to simplify appending to lists, e.g. ``ls = sc.autolist(); ls += 'not a list'``.
. Added ``sc.freeze()`` as a programmatic equivalent of ``pip freeze``.
. Added ``sc.require()`` as a flexible way of checking (or asserting) environment requirements, e.g. ``sc.require('numpy')``.
. Added ``sc.path()`` as an alias to ``pathlib.Path()``.

Improvements
~~~~~~~~~~~~
. Added an even more robust unpickler, that should be able to recover data even if exceptions are raised when unpickling.
. Updated ``sc.loadobj()`` to allow loading standard (not gzipped) pickles and from ``dill``.
. Updated ``sc.saveobj()`` to automatically swap arguments if the object is supplied first, then the filename.
. Updated ``sc.asd()`` to allow more flexible argument passing to the optimized function; also updated ``verbose`` to allow skipping iterations.
. Added a ``path`` argument to ``sc.thisdir()`` to more easily allow subfolders/files.
. Instead of being separate function definitions, ``sc.load()``, ``sc.save()``, and ``sc.jsonify()`` are now identical to their aliases (e.g. ``sc.loadobj()``).
. ``sc.dateformatter()`` now allows a ``rotation`` argument, since date labels often collide.
. ``sc.readdate()`` and ``sc.date()`` can now read additional numeric dates, e.g. ``sc.readdate(16166, dateformat='ordinal')``.

Backwards-incompatible changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
. ``sc.promotetolist()`` now converts (rather than wraps) ranges and dict_keys objects to lists. To restore the previous behavior, use the argument ``coerce='none'``.
. The ``start_day`` argument has been renamed ``start_date`` for ``sc.day()`` and ``sc.dateformatter()``.
. The ``dateformat`` argument for ``sc.date()`` has been renamed ``outformat``, to differentiate from ``readformat``.

--------------------------
. Added ``openpyxl`` as a Sciris dependency, since it was `removed from pandas <https://pandas.pydata.org/pandas-docs/stable/whatsnew/v1.3.0.html>`__.
. Added ``sc.datedelta()``, a function that wraps ``datetime.timedelta`` to easily do date operations on strings, e.g. ``sc.datedelta('2021-07-07', days=-3)`` returns ``'2021-07-04'``.
. Added additional supported date formats to ``sc.readdate()``, along with new ``'dmy'`` and ``'mdy'`` options to ``dateformat``, to read common day-month-year and month-day-year formats.
. Added the ability for ``sc.compareversions()`` to handle ``'<'``, ``'>='``, etc.
. Errors loading pickles from ``sc.load()`` are now more informative.

--------------------------

New functions and methods
~~~~~~~~~~~~~~~~~~~~~~~~~
. Added ``sc.figlayout()`` as an alias to both ``fig.set_tight_layout(True)`` and ``fig.subplots_adjust()``.
. Added ``sc.midpointnorm()`` as an alias to Matplotlib's ``TwoSlopeNorm``; it can also be used in e.g. ``sc.vectocolor()``.
. Added ``sc.dateformatter()``, which will (semi-)automatically format the x-axis using dates.
. Added ``sc.getplatform()``, ``sc.iswindows()``, ``sc.islinux()``, and ``sc.ismac()``. These are all shortcuts for checking ``sys.platform`` output directly.
. Added ``sc.cpu_count()`` as a simple alias for ``multiprocessing.cpu_count()``.

Bugfixes
~~~~~~~~
. Fixed ``sc.checkmem()`` from failing when an attribute was ``None``.
. Fixed a file handle that was being left open by ``sc.gitinfo()``.

``odict`` updates
~~~~~~~~~~~~~~~~~
. Defined ``+`` for ``sc.odict`` and derived classes; adding two dictionaries is the same as calling ``sc.mergedicts()`` on them.
. Updated nested dictionary functions, and added them as methods to ``sc.odict()`` and derived classes (like ``sc.objdict()``); for example, you can now do ``nestedobj = sc.objdict(); nestedobj.setnested(['a','b','c'], 4)``.
. Added ``sc.odict.enumvalues()`` as an alias to ``sc.odict.enumvals()``.

Plotting updates
~~~~~~~~~~~~~~~~
. Updated ``sc.commaticks()`` to use better formatting.
. Removed the ``fig`` argument from ``sc.commaticks()`` and ``sc.SIticks()``; now, the first argument can be an ``Axes`` object, a ``Figure`` object, or a list of axes.
. Updated ``sc.get_rows_cols()`` to optionally create subplots, rather than just return the number of rows/columns.
. Removed ``sc.SItickformatter``; use ``sc.SIticks()`` instead.

Other updates
~~~~~~~~~~~~~
. Updated ``sc.heading()`` to handle arguments the same way as ``print()``, e.g. ``sc.heading([1,2,3], 'is a list')``.
. Allowed more flexibility with the ``ncpus`` argument of ``sc.parallelize()``: it can now be a fraction, representing a fraction of available CPUs. Also, it will now never exceed the number of tasks to be run.
. Updated ``sc.suggest()`` to modify the threshold to be based on the length of the input word.