diff --git a/docs/source/FAQ/data_manager_migration.rst b/docs/source/FAQ/data_manager_migration.rst deleted file mode 100644 index 06114f5fc..000000000 --- a/docs/source/FAQ/data_manager_migration.rst +++ /dev/null @@ -1,144 +0,0 @@ -============================= -Migrating to Use Data Manager -============================= - -Summary -======= - -This guide provides users of Citrine Python background and instructions for migrating code to -take full advantage of Data Manager features and -prepare for the future removal of endpoints that will occur with Citrine Python v4.0. - -The key change will be that :py:class:`Datasets ` are now assets -of :py:class:`Teams `, -rather than :py:class:`Projects `. -The bulk of code changes will be migrating calls that access collections of data objects and Datasets from a Project-based method to a Team or Dataset-based method. - -If you require any additional assistance migrating your Citrine Python code, -do not hesitate to reach out to your Citrine customer support team. - -What’s new? -=========== - -Once Data Manager has been enabled on your deployment of the Citrine Platform, -the primary change that will affect Citrine Python code is that Datasets, -formerly contained within a Project, are rather assets of a Team. -In other words, Teams contain both Datasets and Projects. - -Projects still contain assets such as GEMTables, Predictors, DesignSpaces, etc., but Datasets and their contents are now at the level of a Team. -Data within a Dataset (in the form of GEMD Objects, Attributes, and Templates, as well as files) are only leveraged within a Project by creating a GemTable. - -After Data Manager is activated, any new Datasets created, -either via Citrine Python or the Citrine Platform web UI, will be created at a Team level, -and will not be accessible via the typical `project..{method}` endpoints\* . -New collections, at both the Team and Dataset level, will be available in v3.4 of Citrine Python. - -\*Newly-registered Datasets can be accessible via Project-based methods if pulled into a project with `project.pull_in_resource(resource=dataset)`. -However, this is not recommended as endpoints listing data by projects and the “pull_in” endpoint for datasets will be removed in 4.0. - -How does this change my code? -============================= - -The change in behavior is most localized to two sets of operations on Datasets and their constituent GEMD data objects: -Sharing and Project-based Collections. - -Sharing -------- - -**Within a Team** - -Previously, sharing a Dataset from one Project to another was a 2-step process: first publishing the Dataset to a Team, then pulling the Dataset into the new project. -Now that all Datasets are assets of teams, sharing within a team is unnecessary. -All of the `publish`, `un_publish`, and `pull_in_resource` endpoints, when applied to Datasets will undergo deprecation. -To be precise, the following calls will return a deprecation warning version for Citrine Python versions 3.4 and above, and be removed in version 4.0: - -.. code-block:: python - - # Publishing a Dataset to a Team will do nothing once Data Manager is activated - project.publish(resource=dataset) - - # Un-publishing a Dataset will similarly be a no-op with Data Manager activated - project.un_publish(resource=dataset) - - # Pulling a Team into a Project can still be done with Data Manager activated, but not - # recommended and will be deprecated - project.pull_in_resource(resource=dataset) - -**Between Teams** - -Sharing a Dataset from one project to another where those projects are in different Teams was a 3-step process: -publishing to the Team, sharing from one Team to another, then pulling into a Project. -With Data Manager, only the sharing action is needed. - -Previous code for sharing My Dataset from Project A in Team A to eventually use in a Training Set -in Project B in Team B: - -.. code-block:: python - - project_a.publish(resource=my_dataset) - team_a.share( - resource=my_datset, - target_team_id=team_b.uid, - ) - project_b.pull_in_resource(resource=my_dataset) - -Is now: - -.. code-block:: python - - team_a.share( - resource=my_datset, - target_team_id=team_b.uid, - ) - -Project-based Collections -------------------------- - -As Datasets are now assets of Teams, typical ways to `list()`, `get()`, or otherwise manipulate Datasets or data objects within a Project will undergo a deprecation cycle. -As of v3.4, these endpoints will still work as usual with a deprecation warning, but will be removed in v4.0. -It is therefore recommended to migrate your code from all project-based listing endpoints as soon as possible -to adhere to supported patterns and avoid any costly errors. - -The following endpoints will return a return a deprecation warning version for Citrine Python versions 3.4 and above, and be removed in version 4.0. -Moreover, they will not reference Datasets or their contents that are registered after Data Manager has been activated: - -.. code-block:: python - - # Listing Datasets or their Contents (such as MaterialSpecs or ProcessTemplates) from a Project - project.datasets.list() - project.gemd.list() - project.process_runs.list() - ... - - # Getting Datasets or GEMD Assets via their UID and a Project - project.datasets.get(uid) - project.measurement_specs.get(uid) - ... - - # Doing any operations (updating, deleting, etc.) to Datasets via a Project collection - project.datasets.update() - -The following new methods introduced in citrine python v3.4 are preferred: - -.. code-block:: python - - # Listing Datasets or their Contents - team.datasets.list() - team.gemd.list() - dataset.property_templates.list() - ... - - # Getting Datasets or GEMD Assets via their UID - team.datasets.get(uid) - team.ingredient_runs.get(uid) - dataset.process_specs.get(uid) - ... - - # Doing any operations (updating, deleting, dumping, etc.) to Datasets or GEMD Assets - team.datasets.delete(uid) - dataset.condition_templates.update(object) - ... - -Note again that even though these endpoints will still be operational, -registration of any new Datasets will be at a Team level and thus inaccessible via these Project-based collections, -unless “pulled in” to a specific Project in that Team. \ No newline at end of file diff --git a/docs/source/FAQ/index.rst b/docs/source/FAQ/index.rst index 392611db1..56676d268 100644 --- a/docs/source/FAQ/index.rst +++ b/docs/source/FAQ/index.rst @@ -6,5 +6,4 @@ FAQ :maxdepth: 2 prohibited_data_patterns - v3_migration - data_manager_migration + predictor_evaluation_migration diff --git a/docs/source/FAQ/predictor_evaluation_migration.rst b/docs/source/FAQ/predictor_evaluation_migration.rst new file mode 100644 index 000000000..47fb83f35 --- /dev/null +++ b/docs/source/FAQ/predictor_evaluation_migration.rst @@ -0,0 +1,51 @@ +================================== +Migrating to Predictor Evaluations +================================== + +Summary +======= + +In version 4.0, :py:class:`Predictor Evaluation Workflows ` and :py:class:`Predictor Evaluation Executions ` (collectively, PEWs) will be merged into a single entity called :py:class:`Predictor Evaluations `. The new entity will retain the functionality of its predecessors, while simplyfing interactions with it. And it will support the continuing evolution of the platform. + +Basic Usage +=========== + +The most common pattern for interacting with PEWs is executing the default evaluators and waiting for the result: + +.. code:: python + + pew = project.predictor_evaluation_workflows.create_default(predictor_id=predictor.uid) + execution = next(pew.executions.list(), None) + execution = wait_while_executing(collection=project.predictor_evaluation_executions, execution=execution) + +With Predictor Evaluations, it's more straight-forward: + +.. code:: python + + evaluation = project.predictor_evaluations.trigger_default(predictor_id=predictor.uid) + evaluation = wait_while_executing(collection=project.predictor_evaluations, execution=evaluation) + +The evaluators used are available with :py:meth:`~citrine.informatics.executions.predictor_evaluation.PredictorEvaluation.evaluators`. + +Working With Evaluators +======================= + +You can still construct evaluators (such as :class:`~~citrine.informatics.predictor_evaluator.CrossValidationEvaluator`) the same way as you always have, and run them against your predictor: + +.. code:: python + + evaluation = project.predictor_evaluations.trigger(predictor_id=predictor.uid, evaluators=evaluators) + +If you don't wish to construct evaluators by hand, you can retrieve the default one(s): + +.. code:: python + + evaluators = project.predictor_evaluations.default(predictor_id=predictor.uid) + +You can evaluate your predictor even if it hasn't been registered to the platform yet: + +.. code:: python + + evaluators = project.predictor_evaluations.default_from_config(predictor) + +Once evaluation is complete, the results will be available by calling :py:meth:`~citrine.informatics.executions.predictor_evaluation.PredictorEvaluation.results` with the name of the desired evaluator (which are all available through :py:meth:`~citrine.informatics.executions.predictor_evaluation.PredictorEvaluation.evaluator_names`). diff --git a/docs/source/FAQ/v3_migration.rst b/docs/source/FAQ/v3_migration.rst deleted file mode 100644 index 0095fd01c..000000000 --- a/docs/source/FAQ/v3_migration.rst +++ /dev/null @@ -1,158 +0,0 @@ -================ -Migrating to 3.0 -================ - -Summary -======= - -The newest major release of citrine-python cleans accumulated deprecations as we evolve the Citrine -platform. The intent is to focus users as we aim to reduce confusion by providing a single way to -accomplish each of your tasks. - -Keep in mind that you can keep using 2.x until you're ready to upgrade. But until you do, you won't -get any new features or bug fixes. - -Goals ------ - -The intent of this guide is not to itemize every piece of code removed. The easiest way to -determine what you'll need to change is to upgrade citrine to the latest 2.x release (2.42.2), run -your scripts, and take note of the deprecation warnings. Whenever possible, those warnings will -direct you on how to modify your code such that it will continue to function as desired upon -upgrading to citrine-python 3.x. - -This guide seeks to give a high-level overview of those changes, naming some of the categories of -elements no longer supported and what action to take, as well as some of the more consequential -individual changes. - -Versions / Runtimes -=================== - -The following library versions and Python versions are no longer supported. - -Versions < 2.26.1 ------------------ - -The citrine-python SDK is a client for the Citrine platform. As such, we will occasionally need to -make upgrades to the platform which will break old versions of the SDK. - -At some point after the release of 3.0, we will be making platform upgrades which will change the -way clients must interact with Search Spaces. So if you're using any version of citrine prior to -2.26.1 (released on June 28, 2023), and you're interacting with Search Spaces (e.g. through -:py:attr:`project.design_spaces `), your code will -break. Please upgrade to the latest 2.x release, or to 3.0, to avoid this issue. If this poses any -problems for you, please notify your customer contact so we can work with you. - -Python 3.7 ----------- - -Official upstream support for Python 3.7 by the Python Software Foundation ended in June 2023. As -such, we no longer support its use, and may begin using language features which are not backwards -compatable with it. Upgrade to at least Python 3.8, keeping in mind -`their migration guide `_. - -Features -======== - -The following features are no longer supported. - -Branch ID ---------- - -Previously, branch references were inconsistent. Some used a unique "branch ID", and others the -"root ID". This was further complicated by the web app only ever showing the "root ID". The reason -has to do with the platform implementation, but resulted in a confusing user experience. - -Beginning in 3.0, that "branch ID" is hidden from users. Instead, the SDK will always present the -branch's root ID and version, akin to -:py:class:`Predictor ` ID and -version. To access branches, you'll just use that root ID, and optionally the version: omitting the -version will grab the most recent version, which will almost always be what you want. - -status_info ------------ - -We have completed moving all our assets which previously used :code:`status_info` (such as but not -limited to :py:class:`~citrine.informatics.predictors.predictor.Predictor` and -:py:class:`~citrine.informatics.workflows.design_workflow.DesignWorkflow`) to use -:code:`status_detail`. These objects contain richer information, such as log level and (optionally) -error codes, along with the message. - -DesignSpace.archive and DesignSpace.restore -------------------------------------------- - -In the past, archiving a Search Space required updating it, which carried the risk of accidental -modification. Since 2.26.1, we've supported a separate -:py:meth:`~citrine.resources.design_space.DesignSpaceCollection.archive` and -:py:meth:`~citrine.resources.design_space.DesignSpaceCollection.restore` call. So we no longer -support archiving via :py:meth:`~citrine.resources.design_space.DesignSpaceCollection.update`. - -citrine.builders ----------------- - -This package contained a handful of utilities which were by all accounts unused, and better suited -to live outside citrine-python, anyways. - -formulation_descriptor parameters ---------------------------------- - -In many cases, the Citrine platform will generate an appropriate formulation descriptor on your -behalf. For example, when creating a -:py:class:`~citrine.informatics.predictors.simple_mixture_predictor.SimpleMixturePredictor` or -:py:class:`~citrine.informatics.data_sources.GemTableDataSource`. In such cases, you can no longer -specify a formulation descriptor. - -:py:attr:`project.modules ` --------------------------------------------------------------------------------- - -This was the remnant of the old Citrine platform, before we began to specialize our assets. For -over a year, it has only returned Search Spaces, for which you should be using -:py:meth:`project.design_spaces `. As -such, both it and :code:`citrine.resources.modules` were dropped. - -Dehydrated Search Spaces ------------------------- - -This is a feature from the early days of the platform. It hasn't been supported for quite some time -due to lack of use and complexity of support. But mechanisms for it were still present in -citrine-python, allowing users to specify subspaces by ID. Fully dropping support completes its -removal. - -Process File Protocol ---------------------- - -This refers to the old method of getting data on the platform using :code:`Dataset.files.process`. -It's been supplanted by :py:meth:`~citrine.resources.file_link.FileCollection.ingest`, rendering -:code:`process` and the whole :code:`citrine.resources.job` module irrelevant. - -convert_to_graph and convert_and_update ---------------------------------------- - -:code:`SimpleMLPredictor` was a very old type of AI Model which hasn't been supported by the -platform in a long time. As such, these methods to convert them into the equivalent -:py:class:`~citrine.informatics.predictors.graph_predictor.GraphPredictor` are no longer needed. If -you think you still use a :code:`SimpleMLPredictor`, please reach out to your customer contact so we can -work with you to convert it. - -:py:meth:`~citrine.seeding.find_or_create.find_or_create_project` requires a team ID ------------------------------------------------------------------------------------- - -In mid-2022, the platform introduced teams, which are collections of projects. As such, starting -with 3.0, :py:meth:`~citrine.seeding.find_or_create.find_or_create_project` can only operate on a -:py:class:`~citrine.resources.project.ProjectCollection` which includes a team ID. That is, instead -of passing :py:attr:`citrine.projects `, you most likely want to -pass :py:attr:`team.projects `. - -Ingredient Ratio Constraint bases are now sets ----------------------------------------------- - -They were initially implemented as Python dictionaries to allow for flexibility. But as we evolved -their usage on the platform, we found we only needed the list of ingredients/labels. To allow -migration while preserving the old behavior, we added -:py:meth:`~citrine.informatics.constraints.ingredient_ratio_constraint.IngredientRatioConstraint.basis_ingredient_names` -and -:py:meth:`~citrine.informatics.constraints.ingredient_ratio_constraint.IngredientRatioConstraint.basis_label_names`. -Note that -once you've upgraded to 3.0, you'll be prompted to move back to -:py:meth:`~citrine.informatics.constraints.ingredient_ratio_constraint.IngredientRatioConstraint.basis_ingredients` and -:py:meth:`~citrine.informatics.constraints.ingredient_ratio_constraint.IngredientRatioConstraint.basis_labels`. diff --git a/src/citrine/__version__.py b/src/citrine/__version__.py index c1d933105..1e6bdc426 100644 --- a/src/citrine/__version__.py +++ b/src/citrine/__version__.py @@ -1 +1 @@ -__version__ = "3.25.2" +__version__ = "3.26.0"