REST Client¶

class SpayaClientREST(url, authorization, parameters=None, settings=None)¶

This client sends SMILES to the Spaya API to get an RScore.

Examples

>>> from iktos.spaya import BearerToken, SpayaClientREST
...
... # Create client with authorization
... client = SpayaClientREST(url="https://spaya.ai",
...                          authorization=BearerToken("myT0ken"))
...
... # Start a retrosynthesis and wait for the results
... scored_smiles = client.score_smiles(smiles=["O=C1CCCCO1", "O=C1CCCNN1",])
...
... # Show the results
... for smiles, result in scored_smiles.items():
...     print(f"{smiles}: {result.rscore} / {result.nb_steps}")

>>> from iktos.spaya import BearerToken, SpayaClientREST
... from pandas import DataFrame
...
... # Create client with authorization
... client = SpayaClientREST(url="https://spaya.ai",
...                          authorization=BearerToken("myT0ken"))
...
... # Start a retrosynthesis and wait for the results with a dataframe
... df = DataFrame({"input_smiles": ["O=C1CCCCO1", "O=C1CCCNN1",]})
... df = client.score_smiles(
...     smiles=df,
...     dataframe_smiles_column="input_smiles",
...     callback_progression=lambda p: print(f"progression:{p}")
... )
...
... # Show the results
... print(f"result: {df}")

>>> from iktos.spaya import BearerToken, SpayaClientREST
...
... # Create client with authorization
... client = SpayaClientREST(url="https://spaya.ai",
...                          authorization=BearerToken("myT0ken"))
...
... # Start a retrosynthesis
... client.start_retrosynthesis(smiles=["O=C1CCCCO1", "O=C1CCCNN1",])
...
... # Consume the results as soon as possible
... while not client.is_empty:
...     for smiles, result in client.consume():
...         print(f"{smiles} {result}")

Parameters

url (str) – URL to the Spaya API
authorization (iktos.spaya.authorization.Authorization) – Login authorization
parameters (Optional[iktos.spaya.model.RetrosynthesisParameters]) – Retrosynthesis algorithm parameters
settings (Optional[iktos.spaya.model.SettingsREST]) – Client settings

clustering(smiles, dataframe_smiles_column='smiles', min_relative_size=None, max_cluster=None, max_coverage=None, alpha=None, min_route_rscore=None, extra_smiles=None)¶

Get clusters for batches of SMILES, these SMILES should have been retrosynthesised first.

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) – a list of smiles or a dataframe
dataframe_smiles_column (str) – smiles column name in dataframe
min_relative_size (Optional[float]) – minimum relative number of atoms (compared to average size) for intermediates, values in [0 ; 1]
max_cluster (Optional[int]) – Maximum number of clusters to create
max_coverage (Optional[float]) – stopping criteria on the % of initial smiles in a cluster. values in [0 ; 1]
alpha (Optional[float]) – relative importance of the size of the intermediate in the clusters’ scoring, values in [0 ; 1]
min_route_rscore (Optional[float]) – Minimum rscore to filter routes, values in [0 ; 1]
extra_smiles (Optional[List[Tuple[iktos.spaya.model.RetrosynthesisParameters, List[str]]]]) – a list of different parameters and SMILES to add to this clustering. Only max_nb_iterations and early_stopping_timeout can be different

Returns

List of clusters. One cluster contains routes that are grouped by the smiles they lead to

Return type

iktos.spaya.model.ClusteringResult

Examples

>>> from iktos.spaya import BearerToken, SpayaClientREST
...
... # 1- Create client with authorization
... client = SpayaClientREST(
...     url="https://spaya.ai",
...     authorization=BearerToken("myT0ken"),
...     parameters=RetrosynthesisParameters(
...         early_stopping_timeout=1
...     )
... )
...
... # 2- Start a retrosynthesis and wait for the results
... smiles_list = ["O=C1CCCCO1", "O=C1CCCNN1"]
... client.score_smiles(smiles=smiles_list)
...
... # 3- Get clusters
... best_routes = client.clustering(
...     smiles=smiles_list,
...     min_relative_size=0.1,
...     max_cluster=10,
...     max_coverage=0.95,
...     alpha=0.,
...     extra_smiles=[
...         (
...             RetrosynthesisParameters(early_stopping_timeout=3),
...             ["Cc1occc(=O)c1O", "CN1C=CCSC1=N"]
...         )
...     ]
... )
...
... # 4- Show results
... for cluster in best_routes.clusters:
...     print(f"{cluster.key}:"
...     print(f"  mean_depths:{cluster.mean_depths}")
...     print(f"  mean_max_score:{cluster.mean_max_score}")
...     print(f"  smiles:{cluster.smiles}")

Return type

ClusteringResult

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) –
dataframe_smiles_column (str) –
min_relative_size (Optional[float]) –
max_cluster (Optional[int]) –
max_coverage (Optional[float]) –
alpha (Optional[float]) –
min_route_rscore (Optional[float]) –
extra_smiles (Optional[List[Tuple[iktos.spaya.model.RetrosynthesisParameters, List[str]]]]) –

consume()¶

Update and return all finished SMILES and remove them

Returns: All finished SMILES
Return type: Generator[Tuple[str, RetrosynthesisResult], None, None]

get_commercial_compounds(smiles, provider=None, catalog=None, packaging_g_min=None, packaging_g_max=None, price_per_g_min=None, price_per_g_max=None, delivery_date_max_day=None, delivery_included=None)¶

Access to commercial compounds

Parameters

smiles (Union[str, List[str], iktos.spaya.model.Route, pandas.core.series.Series]) – Molecules represented as either, a SMILES, a list of SMILES, a Route, or a Series.
provider (Optional[List[str]]) – List of desired commercial compounds providers. None or an empty list select them all
catalog (Optional[List[iktos.spaya.model.Catalog]]) – Select the type of compounds (building block / screening / virtual). A null value or an empty list select them all
packaging_g_min (Optional[float]) – Minimum packaging in gramme for a commercial compounds
packaging_g_max (Optional[float]) – Maximum packaging in gramme for a commercial compounds
price_per_g_min (Optional[float]) – Minimum price per gramme for a commercial compounds
price_per_g_max (Optional[float]) – Maximum price per gramme for a commercial compounds
delivery_date_max_day (Optional[int]) – Maximum delivery time in day. A null value select them all
delivery_included (Optional[bool]) – If True the comparaison will done with the maximum delivery date. If False the comparaison will done with the minimum delivery date”,

Returns

A dictionnary SMILES -> commercial compounds found

Return type

Dict[str, List[CommercialCompound]]

get_commercial_compounds_providers()¶

Returns: List of available commercial compounds providers.
Return type: List[str]

get_name_reactions(filter_name_reactions=None)¶

Get the possible value for name_reactions

Parameters: filter_name_reactions (Optional[str]) – optional case unsensitive regex
Returns: List of name reactions found.
Return type: List[str]

get_retrosynthesis_quota()¶

Returns: The number of retrosynthesis left or None if illimited
Return type: Optional[int]

get_status()¶

Returns: Current spaya api status
Return type: Status

property is_empty¶

True if all SMILES have been consumed

Return type: bool

property is_retro_finished¶

True if all SMILES have been processed

Return type: bool

property parameters¶

Retrosynthesis algorithm parameters

Return type: RetrosynthesisParameters

pop_finished(smiles)¶

Remove and return a Spaya RScore of a finished SMILES

Parameters: smiles (str) – SMILES to access
Returns: A retrosynthesis result or None if the SMILES is not finished
Raises: KeyError – if the SMILES is not in the client
Return type: Optional[RetrosynthesisResult]

pop_finished_to_dataframe(df, smiles_column='smiles', rscore_column='rscore', nb_steps_column='nb_steps')¶

Remove and complete a dataframe with a Spaya RScore and number of steps for each finished smiles

Parameters

df (pandas.core.frame.DataFrame) – dataframe to complete with RScore and number of steps
smiles_column (str) – smiles column name
rscore_column (str) – rscore column name
nb_steps_column (str) – number of steps column name

Returns

A completed dataframe

Return type

DataFrame

property progression¶

Progression (as percentage) of SMILES not consumed

Return type: float

remove(smiles)¶

Remove a SMILES from the client without removing the SMILES from the retrosynthesis queue

Parameters: smiles (str) – SMILES to remove
Raises: KeyError – if the SMILES is not in the client
Return type: None

routes(smiles, top_k_routes=None, dataframe_smiles_column='smiles')¶

Get routes for batches of SMILES, these SMILES should have been retrosynthesised first.

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) – a list of smiles
top_k_routes (Optional[int]) – Number of routes to fetch per molecule
dataframe_smiles_column (str) – smiles column name in dataframe

Returns

A dictionnary of smiles and their routes

Raises

ValueError – The SMILES are not DONE, and still need to be retrosynthesised

Return type

Dict[str, List[iktos.spaya.model.Route]]

Examples

>>> # 1. Using a list of smiles
... from iktos.spaya import BearerToken, SpayaClientREST
...
... # 1.1- Create client with authorization
... client = SpayaClientREST(url="https://spaya.ai",
...                          authorization=BearerToken("myT0ken"))
...
... # 1.2- Start a retrosynthesis and wait for the results
... smiles_list = ["O=C1CCCCO1", "O=C1CCCNN1"]
... client.score_smiles(smiles=smiles_list)
...
... # 1.3- Get best 2 routes for each smiles
... best_routes = client.routes(smiles=smiles_list, top_k_routes=2)
...
... # 1.4- Show results
... for smiles_str, routes_list in best_routes.items():
...     for route in routes_list:
...         print(f"{smiles_str}: {route.rscore} / {route.nb_steps}"
...               f" -> {route.tree}")

>>> # 2. Using a DataFrame
... from iktos.spaya import BearerToken, SpayaClientREST
...
... # 2.1- Create client with authorization
... client = SpayaClientREST(url="https://spaya.ai",
...                          authorization=BearerToken("myT0ken"))
...
... # 2.2- Start a retrosynthesis and wait for the results
... df = DataFrame({"input_smiles": ["O=C1CCCCO1", "O=C1CCCNN1",]})
... client.score_smiles(smiles=df, dataframe_smiles_column="input_smiles")
...
... # 2.3- Get best 2 routes for each smiles
... best_routes = client.routes(
...     smiles=df,
...     top_k_routes=2,
...     dataframe_smiles_column="input_smiles",
... )
...
... # 2.4- Show results
... for smiles_str, routes_list in best_routes.items():
...     for route in routes_list:
...         print(f"{smiles_str}: {route.rscore} / {route.nb_steps}"
...               f" -> {route.tree}")

Return type

Dict[str, List[Route]]

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) –
top_k_routes (Optional[int]) –
dataframe_smiles_column (str) –

score_smiles(smiles, dataframe_smiles_column='smiles', dataframe_rscore_column='rscore', dataframe_nb_steps_column='nb_steps', callback_progression=None)¶

Start and wait for the retrosynthesis score for one or many SMILES

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) – one or a list of SMILES to be scored
dataframe_smiles_column (str) – smiles column name in dataframe
dataframe_rscore_column (str) – rscore column name to be created in dataframe
dataframe_nb_steps_column (str) – number of steps column name to be created in dataframe
callback_progression (Optional[Callable[[float], None]]) – a callable with progression as parameter

Returns

A dictionary of SMILES -> retrosynthesis result If smiles is a dataframe: a dataframe completed with rscore and nb_steps

Return type

If smiles is str or a List

Return type

Union[Dict[str, RetrosynthesisResult], DataFrame]

start_retrosynthesis(smiles, dataframe_smiles_column='smiles')¶

Add SMILES to score

Parameters

smiles (Union[str, List[str], pandas.core.frame.DataFrame]) – SMILES to score
dataframe_smiles_column (str) – smiles column name in dataframe

Return type

None

property unfinished_smiles¶

All smiles submited and not finished

Return type: Dict[str, RetrosynthesisResult]

property url¶

Spaya URL

Return type: str

wait_result(callback_progression=None, timeout=None)¶

Wait for the retrosynthesis of all SMILES

Parameters

callback_progression (Optional[Callable[[float], None]]) – a callable with progression as parameter
timeout (Optional[float]) – stop waiting after a value in second

Return type

None