Migration guide for crandas 2.0

The 2.0 version of crandas introduces a number of breaking changes that require scripts to be updated. Following this guide will allow scripts to be converted to run in the new version of crandas. The main change in crandas 2.0 is an overhaul of the approval system, which is why every script must be recorded and approved again. The other main changes in crandas are making various defaults more logical and removing deprecated functionality.

Tip

In order to check the version of crandas you are running, you can do the following:

from importlib.metadata import version
version("crandas")

If the version you see is smaller than 2.0.0, you can update it as follows from the terminal:

pip install --upgrade crandas --index-url=https://pypi.rosemancloud.com

Approval changes

Starting from crandas 2.0, script approvals will be managed through the Registry. The main consequence of this is that analysts will no longer require an .approved file to execute a script. Once a script is approved, an approved analyst will be able to execute it based on the original recording. Further, the recording now has the extension .script instead of .recording. Therefore, every instance of script.load(script.approved) must be changed to script.load(script.script). This change makes the flow simpler, as signed scripts are no longer needed. However, as a consequence, every script in production must be recorded and approved again in order to fit the new system. Besides this main change, there are a number of small changes in the recording workflow.

Minor approval changes

Previously, when recording a script, you could add a name to the script. This is no longer allowed. You can still add a name to the script when uploading the script via the CLI or Platform. Adding a path for the recording file to be saved is now obligatory, do this by using cd.script.record(PATH) or cd.script.record(path=PATH). Remember that if the provided path has no extension, the extension .script will be added to the end of the file name.

Additionally, analyst keys will no longer be necessary when recording a script, as they will no longer be bundled with the recording. Therefore setting an analyst_key is no longer necessary when connecting to a design environment.

Closed-by-default

Starting in crandas 2.0, no function in crandas will present clear data without calling .open() first. This was true of almost every function beforehand except for aggregated values like .max(). Previously, these values were opened by default, but now they require a specific call to be opened. In order to update the script, you can add .open() to every call of an aggregation. Therefore col.mean() becomes col.mean().open(). However, pay attention whether you need this value to be opened, if you do not, you can keep it closed.

Tip

Keeping values closed makes it easier to work with them. If you compute the mean of a column and then filter the elements that are higher than the mean, you can keep the value closed, which means you will not need placeholders. For example

mean = tab["col"].mean().open()
filtered =  tab[tab["col"]>cd.Placeholder(mean)]

Becomes

mean = tab["col"].mean()
filtered =  tab[tab["col"]>mean]

The methods affected by this change are the following:

Additionally, methods that would return a table of aggregated data, like DataFrame.describe() now will return a DataFrame() that needs to be opened. This is true also for DataFrame.max() and DataFrame.min().

`cd.Placeholder` instead of `cd.placeholders.Any`

Using placeholders is simpler now, instead of using cd.placeholders.Any you can now use cd.Placeholder. Simply change any instance of cd.placeholders.Any to cd.Placeholder. Alternatively, if your script has the following line:

from crandas.placeholders import Any

you can erase it and change every instance of Any to cd.Placeholder. While crandas 2.0 still allows for Any, future versions of crandas will not, so changing it now is recommended.

Removed deprecated functions and options

A number of functions that were deprecated in previous releases have now been fully removed, here we present a list of the removed functions and the alternative to them:

Deprecated in crandas 2.0	Alternative function
`CSeries.get()`	`Series.as_table()`
`CDataFrame`	`DataFrame`
`CModel`	`Model`
`Series()`	`SeriesWithCtype()`
`DataFrame.append()`	`cd.concat()`
`LinearRegression.get_beta()`	`LinearRegression.open()['beta_']`
`LogisticRegression.get_beta()`	`LogisticRegression.open()['beta_']`
`crandas.unsafe.merge_m2m`	`crandas.caution.merge.merge_m2m()`

Certain machine learning functions kept their original functions in the crandas.compat namespace. These functions have now been removed, but have an equivalent function with the same name in crandas.crlearn.

Similarly, the use of crlearn.utils.min_max_normalize must be replaced by MinMaxScaler.fit_transform as seen in the Normalizing section in each of the regression chapters.

Additionally, the following variables for functions have been removed:

Removed name and dummy_for from query arguments.
Removed bitlength, modulus and assert_hostname from Session

Changes to defaults

The following defaults have been changed:

Uploads from crandas (e.g., cd.DataFrame(), cd.upload_pandas_dataframe(), cd.read_csv()) do not save its result by default anymore. Use tab.save() or tab.save(name=NAME) on the result to save it.
The default value of validate in col.astype() has been changed from False to True.
The functions cd.random.random(), cd.random.randint() and cd.random.randbytes() no longer specify a default value for num_rows which now always needs to be specified explicitly.